IBM Series/1 Program Preparation Subsystem Introduction User's Guide

- - - -

-----

PROGRAM

PRODUCT

GC34-0121-0

S1-20 l

1

,

I

IBM Series/1

Program Preparation Subsystem

Introduction

Program Number 5719-AS1

0

0 fEE : cOl

II

11111111111111111111111111111111111111111111111

0

[]

..c::.

J* .

~

:f.C

--:ra

l

1 0

1'-,

111 1111111111111111111111111111111111111111 11 111

0

0

1111111111111111111 rn

0

[]

~

[[] I

~( z

1 1 1 111111111111111111111111111111111111111111111

./(1]

/

Series/

1

-

-

-

---

GC34-0121-0

51-20

PROGRAM

PRODUCT c

IBM Series/1

Program Preparation Subsystem

Introduction

Program Number 5719-A51

Series/1

o

This publication is for planning purposes only. The information herein is subject to change before the products described become available. o

t \

First Edition (February 1977)

This manual applies to the IBM Series/l Program Preparation Subsystem, 5719-ASl.

Significant changes or additions to the contents of this publication will be reported in subsequent revisions or Technical Newsletters. Requests for copies of IBM publications should be made to your

IBM representative or the IBM branch office serving your locality.

A form for readers' comments is provided at the back of this pUblication. If the form has been removed, send your comments to IBM Corporation, Systems Publications, Department 27T, P.O.

Box 1328, Boca Raton, Florida 33432. Comments become the property of IBM.

©Copyright International Business Machines Corporation 1977 ii GC34-0121

Contents

c c

Preface v

How This Book is Organized v

Related Publications vi

Programming Publications vi

Hardware Publications vi

Chapter I. Overview of the Series/l Program Preparation

Subsystem 1-1

The Subsystem Components 1-2

The Job Stream Processor 1-2

The Text Editor 1-4

The Macro Assembler 1-5

The Application Builder 1-6

Using the Subsystem Components in Program Preparation 1-8

Typical Uses of the Program Preparation Subsystem 1-8

Using the Subsystem Programs in the Realtime

Environment 1-10

Preparing Programs for Execution Under Your Own

Supervisor 1-10

Using the Subsystem Programs in a Batch Environment 1-11

Problem Solving with the Compile, Load, and Go Facility 1-12

Invoking and Executing the Subsystem Programs 1-13

Data Sets and Devices Used by the Subsystem Programs 1-14

The Required Data Set Definitions 1-14

Work Data Sets 1-15

Environment Lists 1-16

Req uired Hardware 1-16

Installing the Program Preparation Subsystem 1-18

Chapter 2. The Job Stream Processor 2-1

The Job Input Stream 2-1

Jobs and Steps 2-1

Data Set Definition Statements 2-2

DSD Environment 2-2

Compile Load and Go Statements 2-3

Input Data 2-4

Sources of the Input Stream 2-4

Redirecting the Input Stream 2-5

Which Input Stream Source to Use 2-6

Summary of Job Stream Processor Control Statements 2-6

Summary of Job Stream Processor Features 2-7

Chapter 3. The Text Editor 3-1

Using the Text Editor 3-2

Interactive and Noninteractive Use 3-2

Line Numbers 3-2

Tailoring the Editing Session 3-3

Preserving Editing Sessions 3-4

Defining Editor Data Sets 3-5

Invoking the Editor 3-5

The Editor Commands 3-6

Summary of Text Editor Features 3-7

Chapter 4. The Macro Assembler 4-1

The Assembler Program 4-1

Defining Assembler Data Sets 4-1

Invoking the Assembler 4-2

The Assembler Language 4-3

Machine Instructions 4-3

Assembler Instructions 4-3

Macro Instructions 4-5

Assembler Coding Features 4-7

Symbolic Representation of Program Elements 4-7

Variety of Data Representation 4-7

Relocatable Object Mod ules 4-7

Address Assignment 4-7

Flexible Register Usage 4-7

Program Sections 4-7

Symbolic Linkages Between Separately Assembled Source

Modules 4-8

Comprehensive Assembler Listings 4-8

Structured Macro Usage 4-9

Summary of Macro Assembler Features 4-10

Chapter 5. The Application Builder 5-1

Execution Environments Supported 5-1

An Environment You Provide 5-2

The Realtime Programming System Execution Environment 5-3

Application Builder Processing 5-6

Phase 1 Processing 5-6

Phase 2 Processing 5-8

Phase 3 Processing 5-11

Summary of Application Builder Data Sets 5-13

Invoking the Application Builder 5-13

Listing and Processing Options 5 -14

Summary of Application Builder Features 5-15

Appendix A. Configuration Requirements A-I

Hardware A-I

Storage Requirements A-I

Disk Requirements

A-I

Diskette Requirements

A-2

Timer Requirements

A-3

Printer Requirements

A-3

Programming Requirements

A-3

Compatibilities

A-3

The Base Program Preparation Facilities and the Program

Preparation Subsystem

A-3

The Realtime Programming System and the Program

Preparation Subsystem A-4

Appendix B. Using the Series/I Programming Library B-l

Glossary G-l

Index X-I

Contents iii

iv

GC34-0121

,

,

Preface

c:

This book provides introductory information about the IBM Series/l Program

Preparation Subsystem for the reader who is evaluating the subsystem for applicability to his installation, as well as for the reader who simply wants a general understanding of the subsystem facilities.

The reader should have a basic knowledge of programming systems and be familiar with the information in the IBM Series/l Realtime Programming

System: Introduction and Planning Guide, GC34-0102.

How this Book is Organized

Chapter 1. Overview of the Program Preparation Subsystem. This chapter describes the purpose, organization, functions, and operating environment of the components of the Program Preparation Subsystem.

Chapter 2. The Job Stream Processor. This chapter explains how the job stream processor control statements are used to invoke batch programs and define the data sets and devices required by those programs.

Chapter 3. The Text Editor. This chapter explains how the text editor is used to create, modify, list and save text modules.

Chapter 4. The Macro Assembler. This chapter describes assembler language features and explains how the assembler program is used to create relocatable object modules.

Chapter 5. The Application Builder. This chapter explains how the application builder processes object modules to prepare them for execution as application programs.

For each of these components, there is a description of its purpose, data sets and devices used, the input required, the processing sequence, and the output created.

Each of these chapters also directs the reader to the appropriate manual for more detailed information about the component.

Appendix A. Configuration Requirements. This appendix contains information about hardware and software requirements and compatibilities.

Appendix B. Using the Series/1 Programming Library. This appendix is a quick-reference guide to help you determine the other Series/l manuals you may need for various types of programming activities.

A glossary is provided to define terms referenced in this manuaL c

Preface v

Related Publications

Programming Publications

IBM Series/l Program Preparation Subsystem: Batch User's Guide

IBM Series/l Program Preparation Subsystem: Text Editor User's Guide

IBM Series/l Program Preparation Subsystem: Macro Assembler User's Guide,

SC34-0124

IBM Series/l Program Preparation Subsystem: Application Builder

User's Guide

IBM Series/l Realtime Programming System: Introduction and Planning Guide,

GC34-0102

IBM Series/l FORTRAN IV: Introduction,

GC34-0132

IBM Series/l PL/ I: Introduction,

GC34-0084

IBM Series/l Mathematical and Functional Subroutine Library: Introduction,

GC34-0138

Hardware Publications

The following hardware and programming publications contain more detailed information about topics covered in this book.

Note.

Order numbers are shown only for the publications that are available at this time.

IBM Series/l Model

5 4955

Processor and Processor Features Description,

GA34-0021

IBM Series/l Model

3 4953

Processor and Processor Features Description,

GA34-0022

IBM Series/l

4962

Disk Storage Unit Description and

4964

Diskette Unit

Description,

GA34-0024

IBM Series/l

4973

Printer Description,

GA34-0044

IBM Series/l

4974

Printer Description,

GA34-0025

IBM Series/l

4979

Display Station Description,

GA34-0026

IBM Series/l System Summary,

GA34-0035-1

(

,

"\

, vi GC34-0121

c

Chapter 1. Overview of the Series /1

Program Preparation Subsystem

The Program Preparation Subsystem is a set of programs in the

IBM

Series/l software system that offers:

• A general-purpose disk-based job stream processor.

• Powerful program preparation facilities for creating realtime and batch applications.

The job stream processor reads, analyzes, and processes the job input stream, which is a sequence of your requests for invoking batch programs and defining the data sets and devices they use.

The program preparation facilities-the text editor, macro assembler, and application builder-allow you to create, update, and assemble source programs, and then build executable application programs.

The programs that make up the Program Preparation Subsystem will also be referred to in this manual as the subsystem programs or the subsystem components.

You can also use PL/I, FORTRAN IV, and the Mathematical and Functional

Subroutine Library (MFSL) with the subsystem programs. Information about the

Series/l software-the program products and how they form a total system-is contained in the IBM Series/l Realtime Programming System: Introduction and

Planning Guide, GC34-0 1 02. c

Text editor

Macro Application assembler builder

Job stream processor

Figure I-\. The IBM Series/l software system

Overview of the Series/l Program Preparation Subsystem 1 - 1

The subsystem programs can run concurrently with realtime applications under the realtime supervisor or, in the absence of realtime applications, can run under the realtime supervisor in a simple batch environment. Batch processing provides a convenient method of invoking and executing programs, with little or no operator intervention required.

The Subsystem Components

Each of the components in the Program Preparation Subsystem performs functions that allow you to prepare programs for execution-in the Realtime

Programming System execution environment or in an environment you provide.

The following section introduces the features and functions of each of the components to give you some background information about the component before you read the individual chapters describing each component. It covers the:

• Job stream processor.

• Text editor.

• Macro assembler.

• Application builder.

The Job Stream Processor

The job stream processor, which serves as the interface to the system resources, provides a simple set of control statements for invoking the programs and for defining data sets they use. These control statements and related data make up a job input stream composed of jobs and steps. Upon reading the control statements (such as JOB, EXEC, and PARM) the job stream processor analyzes the parameters you supply and processes your requests for executing programs. It also manages the data sets and devices used by the programs and handles the automatic job-to-job, step-to-step transition during job input stream processing.

The job stream processor provides the facility to:

• Specify your work requests to the system, using a simple control language.

• Process a job input stream of work requests, the source of which may be an operator station or a previously-created data set.

• Start the input stream from one device and redirect it to another device. For example, you could start the primary input stream from an operator station, then switch to a secondary input stream on a disk data set.

• Use data set definition (DSD) statements to define data sets and devices required by the subsystem programs or your own programs.

• Specify a group of data set definitions to be in effect at various levels of input stream processing-session level, job level or step level.

• Predefine lists containing all of the data set definitions (DSDs) required for executing particular jobs. These environment lists can be prepared and stored on the system. Jobs that require them can then refer to the appropriate environment list, and the job stream processor will process the DSDs as if you had entered them in the input stream.

• Use special control statements -ASMGO, FORTGO, or PLIGO-to initiate a "compile, load, and go" sequence. This lets you translate, build, and execute a program with a minimum of effort.

• Run the Realtime Programming System utilities under the Program Preparation

Subsystem.

( \

' "

I

1 - 2 GC34-0121

c

D

Source of the input stream

The job input stream

Allocating resources in the input stream

DSDs for required work data sets - - - ' "

DSD for output data set A B C - - - - - -

DSD for listing o u t p u t - - - - - - - - -....

DSD for system logging device - - - - -

DSD for message logging device

--~

•

•

•

JOBI

STEPl

JOB

EXEC

ENVL refers to

TSN=

•

•

Changing the source of the input stream

ALTER - - - - - - " " "

Figure

1-2.

Using the job stream processor facilities c

Overview of the Series/l Program Preparation Subsystem 1 - 3

The Text Editor

The text editor allows you to create, modify, list, and save text modules. These text modules can consist of previously-prepared job input streams, source statements, or input data to a batch program. You can use the editor in an interactive mode, entering text and commands from an operator station, or you can use it in a noninteractive mode by defining a disk or diskette data set as the input source.

Using the editor, you can create a new text module or retrieve and update an existing text module. The actual editing takes place in two work data sets, referred to as the editor workspace. The output from the text editor is a newly-created or updated text module that can be saved on a disk or diskette data set and later used as input to a language translator or one of your own application programs.

The editor has 15 easily-learned commands that provide a variety of editing capabilities. You can:

Replace text data within a field in one or more lines. (CF)

• Clear the editor workspace to prepare for a new editing session. (CL)

• Copy lines of text from one area of the editor workspace to another. (CO)

• Display the current status of the editing environment. (CS)

• Change a character string in one or more lines. (CT)

• Delete one or more lines in the editor workspace. (DE)

• End the editing session. (END)

• Search for text in the editor workspace and print each line containing the text.

(FI)

• Get text from a data set and place it in the editor workspace. (GE)

• Insert new lines of text into the editor workspace. (IN)

• Set a line display range and set a line length. (LF)

• List one or more text lines of the editor workspace. (LI)

• Move one or more lines from one area in the editor workspace to another.

(MO)

• Save text lines of the editor workspace to a data set. (SA)

• Set tabs to be used during an editing session. (T A)

( '\

\.

j f

\,

, ,

Establishing an editing environment

CS

LF

TA

CL

Retrievin/{ text modules

GE

Modifyin/{ text

CF DE MO

CO FI

CT IN

Listing text

Ll

Saving text

SA

Ending an editing session

END

Text editor

Figure

1-3.

Program preparation-the text editor (part

1 of 3)

Source statements

1 - 4 GC34-0121

c

The Macro Assembler

Once source statements have been created, the next step in the program preparation sequence is a language translator. The macro assembler is a powerful language translator that provides:

• A function-oriented assembler language for specifying machine instructions.

• A flexible macro language facility.

• Conditional assembly capability within macros.

• Sectional assembly capability.

• Assembler options for data definition and listing control.

• Relocatable object module output.

• Listing output that can include the source program and object text, external symbol dictionary, relocation dictionary, cross-reference table, error messages, and statistics.

The main purpose of the assembler program is to process source statements and create one or more relocatable object modules. These object modules consist of machine instructions and information that will be used by the application builder in its processing.

Note.

Using the PL/I and FORTRAN IV program products in program preparation is described in the IBM Series/l PL/I: Introduction, GC34-0084 and the IBM Series/l FORTRAN IV: Introduction, GC34-0132. c

Source statements

Macro assembler

Figure 1-4. Program preparation-the macro assembler (part 2 of 3) c

Overview of the Series/1 Program Preparation Subsystem 1 - 5

The Application Builder

The application builder provides a variety of services that can be used in creating an application program for execution in the Realtime Programming System environment or in an environment you provide. How you use these services will depend on the execution environment for which you are preparing the application program.

To execute in the realtime environment, an application program must be in the form of a

task set.

A task set is a planned program structure that consists of one or more modules grouped together and combined with various tables and control blocks (a control module) required by the realtime supervisor. To execute in an environment other than the realtime environment, an application program must be a load module in absolute format.

To create an application program, in the form of a task set, to execute in the

Realtime Programming System environment, the application builder:

• Processes control statements that allow you to select the options and data set environment to perform the functions required.

• Assigns storage addresses and resolves external references to create a composite module in relocatable format, which will later become part of a task set.

• Produces composite modules that may be structured in a single segment

(simple structure) or multiple segments (overlay structure).

• Provides a recycling capability to process multiple sets of control statements, where each set of statements creates a composite module.

• Can include modules automatically from a program library through an

autocall facility.

• Creates a

control module,

which specifies the control blocks required by the

Realtime Programming System, at application build time rather than at execution time. (This control module resides in your task set at execution time.)

• Creates a

prebind module,

which allows you to specify the resources to be pre bound to a task set when it is installed rather than at execution time. This pre binding of resources will allow your task set to begin executing faster.

To create an absolute load module that is executable in an environment you provide, the application builder:

• Processes the control statements you specify to identify the contents, structure, and name of the absolute load module.

• Processes object modules to create absolute load modules that consist of a single segment. Addresses are assigned relative to the specified origin for that module, as well as having external references between the object modules resolved.

( \

\. ;

t

1\

" ,

(

.......

-,

1 - 6 GC34-0121

c

Using the application builder to create an application program to execute in an environment other than that of the

Realtime Programming System.

Application builder

(phase 1)

Using the application builder to create an application program to execute in the Realtime Programming System environment.

Applica tion builder

(phase

I)

Applica tion builder

(phase

2) c

Application builder

(phase 3)

*optional

9

~

Figure 1-5. Program preparation-the application builder (part 3 of 3) c

Overview of the Series/I Program Preparation Subsystem I - 7

Using the Subsystem Components

in

Program Preparation

A major use of the subsystem components is preparing programs for execution under the realtime supervisor or your own supervisor.

The basic steps involved in creating an application task set are:

1. Use the job stream processor to manage the program preparation environment.

2. Use the text editor (or

IBM

3741 Programmable Work Station) to create the source code.

3. Use the macro assembler or a compiler to translate the source code and create object modules.

4. Use the application builder to create composite modules or absolute load modules. (If you are creating an absolute load module to execute under your own supervisor, you can skip steps 5 and 6.)

5. Use the application builder to create a control module and (optionally) a pre bind module.

6. Use the application builder to create an application task set that can be executed in the Realtime Programming System environment.

Figure 1-6 shows the sequence of steps in creating an application task set.

Typical Uses of the Program Preparation Subsystem

The facilities of the Program Preparation Subsystem meet the requirements of a wide range of users. Typical uses of these facilities include:

• Preparing application task sets to run under the realtime supervisor in a realtime environment.

• Creating your own supervisor and preparing programs to run under that supervisor.

• Using the subsystem programs in a batch environment.

• Using the compile, load and go capability for problem-solving purposes.

Us;"g the Subsystem Programs in the Realtime Environment

Typically, you would create programs and data using the text editor, then store them on permanent data sets. The source statements are compiled or assembled to create object modules, which must undergo application builder processing to build your realtime application.

To execute under the realtime supervisor, an application must be in the form of a task set. Phases 1, 2, and 3 of application builder processing are required to create task sets that are executable in the realtime environment. Figure 1-6 illustrates this processing.

The subsystem programs may execute concurrently with your realtime applications.

(

'\

\. ?

I - 8 GC34-0121

C

C c

--- ---

Control statements

- - - - r -

I

I

I

I

I

I

I

I

I

I I

.-J or

~L_

I

: I

I

I

I

L

I

I

I

I

L_

Text editor

(optional)

Figure 1-6. Program preparation sequence

Overview of the Series/l Program Preparation Subsystem 1 - 9

Preparing Programs for Execution Under Your Own Supervisor

In this case, you prepare programs in much the same manner as you would for the Realtime Programming System, with one exception. Instead of creating programs, in the form of task sets, to execute under the realtime supervisor, you create absolute load modules to execute independently or under your own supervisor.

Phase 1 of application builder processing can create these absolute load modules. However, none of the Realtime Programming System support functions can be requested, and you must provide a means of loading the programs into storage and passing control to them. The Disk IPL Bootstrap Loader, which is described in the IBM Series/l Stand-Alone Utilities User's Guide, GC34-0070, can be used for loading a program and passing control to it.

Figure 1-7 illustrates this processing.

(

\

'?

/ '

Control statements

Text editor

((tatements ij

~

Language translator

Application builder

Your own supervisor

Figure 1-7.

Preparing programs for execution under your own supervisor

1 - 10 GC34-0121

C ··~

~

Using the Subsystem Programs in a Batch Environment

You may use application programs that you have created to run in a batch environment. Application program input, stored in data sets, can be prepared or updated by using the text editor. The data set can be passed to the application program through the job stream processor.

For example, you may have a payroll program residing on a data set.

Periodically you would use the text editor to enter such data as overtime for the last period of time. This data and the appropriate job stream processor control statements would then be entered in the job input stream for processing by your payroll program. o

Text editor

Input data c

\

•

JOB1 JOB

STEP1 EXEC TSN=PA YRPGM

~:

•

Job stream processor

Figure 1-8. Using the subsystem programs in a batch environment

PAYRPGM o

Overview of the Series/l Program Preparation Subsystem 1 - 11

Problem Solving with the Compile, Load, and Go Facility

The Program Preparation Subsystem provides a simple method for performing problem solving activities through the compile, load, and go facility. This allows you to compile or assemble a program, build a task set, and execute that task set by specifying a few simple control statements. The DSD statements identifying the required data sets and devices are defined in advance in an

environment list.

(Compile, load, and go is described in the job stream processor chapter of this manual.)

Typically, you would write a small program in a high level language, enter this program through the text editor, and then use the appropriate statement

(ASMGO, PLIGO, or FORTGO) to perform a compile, load, and go. Usually you would only be interested in the printed output and would not need to save object data or to specify intermediate input, output, or disk space requirements.

Figure 1-9 illustrates the use of the compile, load, and go facility. CLGLST refers to a previously-prepared environment list.

(

.~

,

Text edi tor

~2 or

FORTGO or

PUGO

EO]

•

Language translator processing

Applica tion builder processing

(

,

'\

~

Task set execution

Figure 1-9. Example of using the compile, load, and go facility c

I - 12 GC34-0121

c

Invoking and Executing the Subsystem Programs

The subsystem programs run under control of the Realtime Programming System as realtime applications in a predefined, fixed partition. The text editor, macro assembler and application builder are all task sets that are invoked through the job stream processor, which is also a task set.

To begin a batch session, you must invoke the job stream processor by entering a system command-TSET STR, CPJ, ptn, qprty-at the operator station. This command starts the job stream processor task set (CPJ), specifies the number of the partition in which the job stream processor is to execute (ptn), and establishes the queuing priority of the job stream processor (qprty). The job stream processor is then loaded and starts processing the input stream. The input stream, which consists of control statements and related input data, is logically subdivided into jobs and steps. The step is the basic unit of work in which you can specify the EXEC control statement to invoke a batch program.

Figure 1-10 illustrates this sequence. c~

Job stream processor

1. Issue the system command TSET STR ... to start the job stream processor.

Realtime applications

Batch partition

2. The job stream processor is loaded and starts processing the input stream.

It reads a request to invoke the assembler (STEPI ... ).

TSET STR, CPJ, ptn, qprty o

JOBl JOB.

STEPl I:XEC TSN

=

CPA

EO]

A<;sembler

3. The job stream processor queues itself to the batch partition, and the assembler is loaded. After the assembler terminates, the job stream processor is the next task set to get con trol.

- fub

7tr~l;

I processor

~~ei

I

_

-I

Figure 1-10. Invoking and executing the subsystem programs

Note.

The batch partition is not reserved for the subsystem programs. Realtime applications use it either when the subsystem programs are inactive or by preempting the partition during a batch processing session. c

Overview of the Series/1 Program Preparation Subsystem 1 - 13

Data Sets and Devices Used by the Subsystem Programs

In the input stream there can be a variety of requests to execute programs-the text editor, the assembler, the application builder, PL/I, FORTRAN IV, or your own batch programs. Each of these programs uses certain data sets and devices to make up its operating environment. You can specify these resources to the program through data set definition (DSD) statements. DSD statements are used to establish a connection between a data set or device and a DSD name used in a program.

You can use DSD statements to create new data sets, identify existing data sets or delete data sets that are no longer needed. The length of time the DSD is in effect depends on where it is located in the input stream-in a step, in a job, or at the beginning of a batch session.

The Required Data Set Definitions

Certain DSDs are established when the Program Preparation Subsystem is installed to make required data sets available to the job stream processor when you start a batch processing session.

To simplify the installation process, default DSDs are supplied for the required data sets at installation time. You can change any of these DSDs if they do not suit your needs.

The required data set information and DSD names are summarized here. The data sets and devices described are those that are required by the job stream processor and, therefore, by all components invoked through the job stream processor. For information about the required data sets and devices that are unique to each component-the text editor, macro assembler, or application builder-refer to the chapter describing that component.

IN STREAM

The INSTREAM DSD defines the input stream source. Unless you specify another input source in the P ARM field of the task set start command, the job stream processor always reads the input stream from the device defined by

INSTREAM.

The default IN STREAM device is the operator station.

JSPWORK

JSPWORK defines a disk data set in which the job stream processor saves its control blocks when it relinquishes the batch partition to another task set.

MSGLOG

MSGLOG defines the messages log device or data set that the job stream processor and text editor use for writing prompts and messages when in the interactive mode. The device assigned to MSGLOG should be the same as the

IN STREAM device.

The default MSGLOG device is the operator station.

PRINT

The device specified by the PRINT DSD is used by all of the subsystem programs for listing various types of printed output that you need in hard copy form.

(For example, the assembler and application builder print their listings and maps at the device defined by PRINT.)

The default PRINT device established at installation time is the printer.

( "

\..

J

(

\

"

,

1 - 14 GC34-0121

c

SPOOL

The disk volume defined by the SPOOL DSD is used by the job stream processor to handle your inline input data for the batch programs. When the job stream processor is processing the input stream and encounters your input data for a batch program, it automatically creates a data set on the SPOOL volume and transfers the inline data to that data set before the batch program is invoked.

Processor storage o

Job stream processor

JSPWORK

SPOOL c o

Work Data Sets

Figure 1-11. Default DSDs for required data sets and devices common to all subsystem components

The text editor, macro assembler, and application builder all require work data sets in order to perform their processing. Each of these components requires a different size and number of work data sets. You can specify the space required for a work data set by:

• Using individual DSD statements to indicate a specific volume and a specific amount of space for the WORKI-WORKx data sets.

• Using the WORKVOL DSD to define space for all the work data sets

(WORKI-WORKx) and the volume on which the space is to be allocated.

Note.

The DSD statements for WORKI-WORKx must always be specified for the assembler and for the application builder, whether or not you use the

WORKVOL DSD. The operands you specify on these statements will vary, depending on the use of the WORKVOL DSD. The text editor only requires that you specify the WORKVOL DSD.

To maximize workspace efficiency, you can use the WORKVOL DSD to define a volume to which all available space will be allocated. Each component can then dynamically allocate this space between the number of the work data sets it needs and in the proportion it needs.

Overview of the Series/l Program Preparation Subsystem 1 - 15

Environment Lists

For example, suppose you were to specify the WORKVOL DSD (to create a temporary work volume) and dummy work data sets-WORKi, WORK2, and

WORK3-for assembler processing. The assembler, which requires three work data sets, would allocate the space among WORKi, WORK2, and WORK3.

Work data set requirements for each component are summarized in the individual chapters describing the component.

Once the Program Preparation Subsystem is installed, you can also specify data sets to contain lists of DSDs that the job stream processor will use to create the environments for various batch programs. These environment lists can contain all the DSDs required to execute a job or step.

Many jobs can effectively use environment lists. For example, if you use the compile, load, and go facility, you should have environment lists prepared for the compile, load and go jobs. You might also want to prepare environment lists for jobs that use the program preparation facilities.

The chapters covering the text editor, macro assembler, and application builder give you more specific information about the data sets and devices used by each of these components. This information should help you to plan the data set and device assignments most efficient for your system and to set up the appropriate environment lists.

Required Hardware

The minimum hardware configuration for the Program Preparation Subsystem is the same as is required for the Realtime Programming System:

Required hardware

Processor

Disk/ diskette

Printer

Operator station

Product name

One IBM 4953 Processor or IBM 4955 Processor with at least 48K bytes of processor storage.

One (or more) IBM 4962 Model 2 or Model 2F Disk

Storage Unit (combination disk/diskette unit).

or

One (or more) IBM 4962 Model 1 or Model 1 F Disk

Storage Unit

and

One (or more) IBM 4964 Diskette Units

One (or more) IBM 4973 Line Printers or IBM 4974

Printers

One (or more) IBM 4979 Display Stations

or

Teletype* Model ASR 33/35 or an ASCII equivalent device that can be used an an operator station and is attached to the system through the Teletypewriter

Adapter Feature #7850.

{

\

,

1 - 16 GC34-0121

*Trademark of the Teletype Corporatioon

annn

ITIIIIIl

111111111111 r

I!I

I~

" I

II

I

I

I I

Timers may optionally be used with the subsystem programs.

For information about sensor I/O and communications support, which are not supported by the Program Preparation Subsystem, refer to the IBM Series/l

Realtime Programming System: Introduction and Planning Guide, GC34-0102. mn:n

UIllD

' " I " II "

@)

11111111

"J

13

0 m

11111111 II c c

UIIIl

UIID

II

I

I

I

I I rn

I1II

OJ m

I I I I

I

I

-

-

Figure 1-12. Sample hardware configurations

IIITID

UIIIIJ

[]

(jJ

11111 " I I

• •

Overview of the Series/l Program Preparation Subsystem 1 - 17

Installing the Program Preparation Subsystem

Once you have determined your data set and device requirements and the required hardware configuration, you can prepare to install your Program

Preparation Subsystem. Before the subsystem programs can be installed, you must have already performed a system generation for the Realtime Programming

System. The subsystem programs are installed in a stand-alone environment, and the installation process requires 48KB of processor storage.

The installation package you receive from IBM contains diskettes that contain the information required for converting the IBM-supplied code into task sets designed to run in the batch partition.

IBM also supplies a generation program that prompts you to supply information about the system to be built. To simplify the installation process, defaults are provided for all of the required DSDs.

If you accept these defaults, the system can be installed as is.

If you do not want to accept the defaults, you can make changes to the DSDs through your responses to the generation program prompts.

After you have supplied the information requested by the generation program, a job input stream will be generated. When this job input stream is executed, you will have a Program Preparation Subsystem tailored to your requirements. The generation program can also perform a system verification to ensure that your system is properly installed. System verification can only be performed against a complete Program Preparation Subsystem.

Although the Program Preparation Subsystem requires only a 16KB partition for execution of batch programs, you may want the partition to be larger for program preparation activity. This would make more efficient use of the system because the text editor, assembler, and application builder execute faster in a larger partition.

The IBM Series/l Program Preparation Subsystem: Batch User's Guide will give a step-by-step description of installing and verifying the Program

Preparation Subsystem.

( '

\.

-,

1 - 18 GC34-0121

Chapter 2. The Job Stream Processor

c

The job stream processor is the subsystem component that reads, analyzes, and processes the job input stream. The job input stream is made up of your requests for executing programs along with related information, such as data set definitions. The job stream processor provides a simple set of control statements for specifying these requests.

To start a batch session, you would invoke the job stream processor with a task set start command. Once started, the job stream processor will read the input stream from the device you designated as the input stream source. The input stream source could be an operator station or a disk or diskette data set.

This can be specified at installation time or when the job stream processor is started. The job stream processor reads and processes the control statements and data that make up the input stream until the end of the input stream is reached,

or a task set stop command is issued for the job stream processor, or a severe error occurs.

Detailed information about the job stream processor will be contained in the

IBM Series/l Program Preparation Subsystem: Batch User's Guide.

The Job Input Stream

The job input stream is logically divided into independent units of work called jobs. Each job may be made up of steps, which are basic units of work for the subsystem. c

Jobs and Steps

Jobs are self-contained elements and, as such, have no relation to other jobs in the input stream. The input stream can consist of many jobs, which are processed one after another in the sequence that they appear in the input stream. If a job terminates because of an error, the jobs that follow it will not be affected, and the job stream processor will automatically continue with the next job in the input stream.

Each job usually contains one or more related steps. A step is the basic unit of the input stream that allows you to invoke a batch program. A step is identified by the EXEC statement, which specifies the batch program to be executed. This example shows a request to execute a task set called PGMl.

I

EXEC TSN=PGMI o

When there is more than one step in a job, execution of a given step depends on successful execution of the previous step. The job stream processor can determine whether or not a batch program was successfully executed by the

return code it receives from the batch program. Return codes are used by all of the subsystem programs to indicate the results of their processing. If a step is not successfully executed, the job stream processor does not attempt to execute the steps that follow, but goes on to the next job in the input stream.

Within a job or step, you can also include data set definition (DSD) statements that define data sets and devices to be used for that job or step. This is discussed in the section that follows.

The Job Stream Processor 2 - 1

Figure 2-1 shows an example of the structure of an input stream.

·

.

.

DSD

·

. .

• • •

DSD

JOBI

·

.

.

JOB

DSD

· .

.

STEPI

EXEC TSN=PGMI

EOS

STEP2 EXEC TSN=PGM2

·

.

.

DSD

DSD

EOS

·

.

.

JOB2

EOJ

JOB

·

.

.

STEPX EXEC TSN=PGMX

EOS

EOJ

•

Figure 2-1. Sample input stream

Data Set Definition Statements

Before a data set can be used by a batch program, it must be defined to the system. To do this, you can use DSD statements. (You can also use the Realtime

Programming System's BLDDSD macro, DEFDSD macro, or DEFINE utility to establish the connection between a DSD name and the associated data set or device.) Once the definition has been established, a program can access the data set by using the DSD name associated with it. ( \

You can use DSD statements to establish new data sets or to identify existing,

~ data sets. Both permanent and temporary data sets can be created. Permanent data sets can also be deleted with a DSD statement. In addition to defining data sets, DSDs can be used to identify a device to be used by a program.

If you enter DSDs at the start of a batch session, these DSDs remain in effect for the entire session unless you override them with the appropriate DSD statements at the job or step level. To override an existing data set or device definition, enter a new DSD statement with the same name as the DSD name of the definition that you want to override. The new DSD statement overrides all parameters on the previously-established DSD of the same name.

DSDs placed within a job are defined for the duration of that job; DSDs placed within a step are defined for the duration of that step. At the end of the associated job or step, the definition is deleted although the data set itself may be permanent.

DSD Environment

The DSDs in effect at any given time in the input stream make up the

DSD environment.

At installation time, required DSDs are established when you either accept the default DSDs that IBM supplies or modify them to suit your needs.

After the program preparation subsystem has been installed, you can prepare lists of DSDs to create environments used by the subsystem programs or your own batch programs. These

environment lists

are very useful because they can reduce the number of statements that must be entered to execute a particular job. On the JOB statement, you simply include the ENVL parameter to refer to the desired environment list. An example of this is shown in the following section.

C

'"'

2 - 2 GC34-0121

c

Compile, Load, and Go Statements

There are special control statements you can use to perform a compile, load, and go with a minimum of effort and knowledge of the Program Preparation

Subsystem. These special statements and their functions are:

• ASMGO-causes

execution of the assembler program, application builder, and the task set created by the application builder.

• FORTGO-causes

execution of the FORTRAN IV compiler, application builder, and the task set created by the application builder.

• PLIGO-causes

the execution of the PL/I compiler, application builder, and the task set created by the application builder.

When you specify one of these statements, a series of steps is initiated to translate, build, and execute a program. By using these statements, you let data set definitions default to data sets that have been previously defined in environment lists. All you have to do is specify the statement (ASMGO,

FORTGO, or PLIGO) and include the ENVL parameter on the JOB statement and all the necessary steps are performed for you. The IBM Series/l Program

Preparation Subsystem: Batch User's Guide will provide the information you need in order to prepare for compile, load, and go processing.

Figure 2-2 illustrates the use of the ASMGO statement.

Here, the ENVL parameter indicates that ALIST refers to a list of DSDs for this compile, load, and go job. c o

JOBI JOB ENVL=ALIST

ASMGO

EOJ

environment list

... DSD .. .

... DSD .. .

... DSD .. .

... DSD .. .

... DSD .. .

... DSD .. .

... DSD .. .

... DSD .. .

Assembler c

Figure 2-2. Using the ASMGO statement

Application builder

Realtime

Programming

System execution environment

The

Job

Stream Processor 2 - 3

Input Data

Along with the control statements in the input stream, you may also include input data for the subsystem programs or your own batch programs. Before the program is invoked, this inline data will be spooled out to a disk data set (which you must have preallocated for that purpose), then passed to the program for use. Spooling is done to preserve input stream integrity.

To include input data in the input stream, specify a DSD statement with an asterisk

(*) parameter preceding the data and a slash asterisk

(/*) delimiter following the data. Suppose you wanted to include data to be used by the assembler. Figure 2-3 shows how the input data is spooled by the job stream processor, then passed to the assembler.

( .,

\ ;

JOB! JOB

STEPl EXEC

SOURCIN DSD

*

P""" .,.. ;-""'"."7

"1

I

I--~ l •

I •

: irtpul t data

I

I

•

. 1

1 ....••

< ..••

1

/*

STEP 2

EOS

EXEC· • •

Assembler

Figure 2-3. Spooling input data

Note.

Your input data to the subsystem programs must be defined by specific

DSD names-SOURCIN for the assembler, APBIN for the application builder, and CMDIN for the text editor. You cannot assign an interactive device to

SOURCIN or APBIN.

Input data for a batch program need not be located in the input stream. It could be on a completely separate data set. In this case, you would define the data set using a DSD statement with the appropriate DSD name (SOURCIN,

APBIN, or CMDIN) and the job stream processor would pass the data set to the subsystem program, which then controls that data set.

Sources of the Input Stream

The source of the input stream may be an operator station or a previously-created text library. c

2 - 4 GC34-0121

c

From the Operator Station

The operator station may be an IBM 4979 Display Station or any ASCII interactive device that can be attached to the processor through the

Teletypewriter Adapter Feature. When the input stream is to come from the operator station, the job stream processor control statements and data will be accepted even though the operator station is also being used as the interface to the Realtime Programming System.

From a Text Library

The source of the input stream can be a text library, which may be contained on a disk or diskette data set. In this case, you must have previously created the input stream by using the text editor or the IBM 3741 Programmable Work

Station. Assembler and application builder input must come from a text library.

Redirecting the Input Stream

You may, at some time, wish to change the source of the input stream. The job stream processor allows you to have input streams residing on more than one device. You might have one main input stream along with secondary input streams that are only processed periodically. Suppose your main input stream source is an operator station, and you have a secondary input stream on a disk data set. You can start the input stream from the operator station and then use the ALTER statement to redirect the input stream to come from the disk data set.

Figure 2-4 gives an example of redirecting the input stream. c~

/

JOBI JOB

~LIB

DS!) DSN=ABC • • •

•

•

• • EXEC.·

·

.

DSD • •

EOS

EOJ

JOB2JOB

•

•

•

EXEC TSN= • •

•

•

•

EOS

EXEC TSN

= ••

•

•

~~OS

V~EOF

Figure 2-4. Redirecting the input stream

This feature gives you flexibility in creating your input stream because you can execute different jobs or steps within jobs from different locations. This is useful when you have various jobs that you want to execute under a single environment, but they are not all in one location. All you have to do is start the batch session from the operator station, enter the environment, and use ALTER statements to go to each job. This saves you the time of reentering each job individually. o

The Job Stream Processor 2 - 5

Which Inpllt Stream SOllrce to Use

The input stream source you wish to use-operator station or a previously-created data set--depends on your time and flexibility requirements.

If you want to be able to change the input stream at the last moment, you would use an operator station. This way the input stream does not have to be created until the moment it is ready to be processed. The disadvantage to this is that it can be time-consuming and requires that someone be present at the operator station at all times.

If you anticipate no changes to the input stream, you can create it on a disk or diskette ahead of time. When you start the batch session, you can indicate that this previously-created input stream is the one to be processed- either by defining it as the primary input stream on the task set start command or by using an ALTER statement to switch to it. For standard jobs that are in different locations, you can put them in a text library and use ALTER statements to combine and execute these jobs as needed.

Summary of Job Stream Processor Control Statements

Statement

ALTER

ASMGO

DSD

EOF

EOJ

EOS

EXEC

FORTGO

JOB

NOEXEC

PARM

PLIGO

*(comment)

/*

Use

Redirects the job input stream from one data set to another.

Creates a compile, load, and go sequence . for the assembler program.

Establishes a connection between a data set or device and a DSD name used in a program.

Indicates the end of an input stream file.

Ends a job.

Ends a step.

Starts a step.

Creates a compile, load, and go sequence for the FORTRAN IV programs.

Starts and names a job.

Used at an interactive device to cancel a step.

Used to pass parameters to a task set to be executed for a step.

Creates a compile, load, and go sequence for the PL/I programs.

* indicates that a comment follows.

Comments can be placed anywhere in the input stream except between continuation statements.

Ends an inline data set started by a DSD

* statement.

f

'\

" I '

2 - 6 GC34-0121

c

Summary of Job

Stream

Processor Features

• The job stream processor gives you a simple control language for specifying requests to execute programs and defining the data sets and devices they require.

• Your input stream can come from an operator station or from a previously-created data set.

• You can redirect the source of the input stream. The input stream can be started from one device, then redirected to come from another device by an

ALTER statement.

• You can predefine environment list DSDs. These lists will contain all the

DSDs needed to execute particular jobs.

• You can add to the environment or override DSDs in the environment. These changes can be in effect for an entire session, a job, or a step.

• You can initiate a compile, load, and go sequence for PL/I, FORTRAN IV, or assembler programs by specifying PLIGO, FORTGO, or ASMGO.

You can pass parameters to a task set that is to be executed in a step.

• You can have multiple stacked jobs per job stream and multiple steps per job. o

The Job Stream Processor 2 - 7

2 - 8 GC34-0121

(:

c c c

Chapter 3. The Text Editor

The text editor provides a facility for creating and editing text modules. It executes in the batch partition and is invoked through the job stream processor.

Once you define the required data sets and start the editor, you can enter new text or retrieve and modify existing text. The actual editing takes place in two work data sets referred to as the editor workspace.

The editor commands let you manipulate the text in a variety of ways. You can easily make changes, additions, and deletions to the text, then save the updated text module on an output data set. Text modules can be independently or compositely retrieved, edited, and saved during a single editing session.

The printed output is a listing of commands and text that you entered, along with the prompts and messages issued by the editor. You can also get a complete listing of the text module that you have created or updated.

Detailed information about the text editor will be contained in the IBM

Series/l Program Preparation Subsystem: Text Editor User's Guide.

cr

CO

DE CS

END IN

LF

MO

Insert or edit text from the operator station

(teletypewriter or display station)

CL

Qear the editor disk or diskette data set

Store text module on disk or diskette data set

Figure 3-1. Retrieving, editing, and saving text with the text editor

The Text Editor 3 - 1

Using the Text Editor

The editor features offer flexibility and ease of use in your editing sessions.

Interactive and Noninteractive Use

You can use the editor in an interactive or noninteractive mode. It executes in a noninteractive mode when the source of commands and data is a disk or diskette data set rather than an operator station.

Most of the time you will probably use the editor interactively, entering commands and data from a teletypewriter or display station.

Text editor

Text editor

Line Numbers

Interactive mode Noninteractive mode

Figure 3-2. Interactive and noninteractive use of the text editor

If you use a display station that is also being used by the system, the lower portion of the display screen is reserved for system use, and the upper portion is for editor use.

The basic unit of text is a line. As lines are placed in the editor workspace

(through the get command or insert command), these lines are assigned temporary line numbers for reference. The line numbers are displayed at the beginning of the line of text but are not part of the text. You can specify the starting line number and the increment to be added to each succeeding line or let both values default to 10.

(

\.

\

'

3 - 2 GC34-0t21

c

D

If you anticipate updating the text module, you have more editing flexibility if you let the starting line number and increment both default to 10. This way you can insert up to nine lines before or after each one of the original lines, without having to rearrange text or reassign line numbers. Figure 3-3 illustrates this concept.

Editor workspace

_r-

------'--

~

---------,

_____ ---.--J

Text number data

~

10 line 1...

20 line

2 .. .

30 line 3 .. .

40 line 4 .. .

50 line 5 .. . c o

Figure 3-3. Editing by line number

Tailoring the Editing Session

The editor has features that allow you to tailor an editing session. You can set a line length, line display range, and tabs that will remain in effect for an entire editing session unless you change them.

Line Length

You can establish a line length-1 to 132 characters-for each record to be edited. This line length does not have to match the record length associated with the text modules to be edited. The line length defaults to 80 characters if you do not specify otherwise.

Line Display Range

You can also specify a line display range to control the length of a text line to be printed or displayed. This feature is useful when you want to avoid line wraparound. Line wraparound occurs when a line is too long to be printed on one device line and is therefore continued on the next line. This can detract from readability of the text lines. To eliminate line wraparound, you can specify a certain number of characters to be printed so that only as many characters as will fit on a device line will be printed.

The line display range can also be useful when you are editing from a teletypewriter and do not need to see the entire line printed out. Specifying a line display range to print only as much of the line as you need to see can reduce printing time.

If you do not specify a line display range, it defaults to the line length established by the line format (LF) command.

The Text Editor 3 - 3

Tabs

The editor tabbing feature adds to your formatting flexibility. Through the tab

(T A) command, you can establish tab settings that will be in effect throughout an editing session unless you change them. You can specify up to ten levels of indentation.

The tabbing feature is easy to use. Through the tab command, specify a tab

character

(which will invoke the tab function) and the column positions of all the tabs you want to set. Suppose you have specified a

"I"

as the tab character and set tabs at 1 0, 16, and 35. When you enter lines of text, simply type the"

I"

wherever you want a tab. Each time the editor encounters a tab character in a text line, it shifts the data following the tab character to the position you specified in the tab command (10, 16 or 35). The resulting "tabbed line" will have the tab character replaced by the proper number of blanks and will be placed in the editor workspace.

Example:

Text line as you entered it

I

LABEL/MVA/TABLE,R1

Text line in editor workspace

I

LABEL

MVA TABLE,R1

Preserving Editing Sessions

To ensure that no text is inadvertently lost from the editor workspace when you end an editing session, the editor automatically preserves the text and editing environment for that session. This way, if you were to enter the END command before saving your text module, the text is not deleted from the editor workspace. The text and editing environment remain intact until you restart the editor. At that time, you can either continue editing the text in the editor workspace, or you can use the clear (CL) command to clear the editor workspace and start a new editing session.

In addition to preventing loss of text, this feature offers you another convenience. If you are interrupted during an editing session, you can end it and restart it later-without having to save the text, retrieve it, and respecify such information as line length, line display range, and tab settings.

( ,

\ ,

~

.T

c

3 - 4 GC34-0121

c

Defining Editor Data Sets

Before you can invoke and use the editor, certain data sets must be defined. The

DSD names and descriptions of data sets used by the editor are summarized in the following chart.

DSD Name

CMDIN

MSGLOG

SYSLOG

TXTIN

TXTOUT

PRINT

WORKVOL

Description

Input device for commands and new data-usually the operator station.

Message log device for listing text data, editor messages, and editor prompts-usually the operator station.

System message log device-usually a printer device, so that you can have a hard copy of messages.

Text module input data set-usually a disk or diskette data set that defines the location of one or more text modules to be retrieved.

Text module output data set that defines the location where edited modules are to be saved-usually a disk or diskette data set or data set member.

Output print device for listing lines of text-usually a printer.

Volume from which space for work data sets 1 and 2 are obtained. This must be specified. c

You can specify these DSDs when you invoke the editor or you may have previously defined them in an environment list. An environment list can contain all the DSDs required to execute the editor. Using environment lists can simplify editing sessions. Once these lists are prepared, you can refer to the environment list you need without having to respecify all the DSDs needed to create the environment for a particular editing job.

Invoking the Editor

If you have already specified the necessary DSDs in an environment list, you can invoke the editor as easily as in this example:

TEJOB JOB ENVL=TELIST

TESTEP EXEC TSN=CPE

EOJ where TEJOB is the name of your job, TELIST is the environment list, and CPE is the text editor task set name.

Messages are printed at the operator station to tell you that the editor is started and ready to accept your editing commands. o

The Text Editor 3 - 5

The Editor Commands

The editor provides a variety of commands. You can use them to retrieve existing text or create new text. You can modify the text-insert and delete text lines, move and copy text lines, and change fields or character strings. When editing is completed, you can save the edited text on an output data set.

The following chart summarizes the editor commands and their functions.

Command

CF (change field)

CL (clear)

CO (copy)

CS (current status)

CT (change text)

DE (delete)

END (end)

FI (find)

GE (get)

IN (insert)

LF (line format)

LI

(list)

MO (move)

SA (save)

TA (tab)

Function

Replaces text data within a field in one or more lines.

Clears the editor workspace to prepare for a new editing session and sets the line length to 80.

Copies one or more lines from one area in the editor workspace to another

(original lines not deleted).

Prints the current status of the editor-the line length, last line number used, line display range, the tab character and tab settings.

Changes a character string in one or more lines.

Deletes one or more lines in the editor workspace.

Ends the editing session.

Searches for text in one or more lines in the editor workspace and prints each line containing this text.

Gets text data from a disk or diskette data set member and places it in the editor workspace.

Inserts new lines of text into the editor workspace.

Sets the line display range for lines to be listed. Sets a line length.

Lists one or more text lines of the editor workspace.

Moves one or more lines from one area of the editor workspace to another.

Saves all text lines in the editor workspace to a data set or data set member on a disk or diskette (workspace contents not affected).

Sets tabs to be used during an editing session.

,

;-

(.

'

. f

3 - 6 GC34-0121

c

Summary of Text Editor Features

• You can use the editor in an interactive mode (entering data and commands from an operator station) or noninteractive mode (data and commands coming from a data set or a data set member on a disk or diskette).

• You can use a teletypewriter or display station for editing in the interactive mode.

• You can establish tab settings, line length and a line display range to suit your needs for a particular editing session.

• At any time during the editing session, you can display the current status of the editor-the tab settings, tab character, the line length, line display range and last line number used.

• The editor automatically preserves the editor workspace contents when you end an editing session, so that you can restart the session later.

• The editor gives you a variety of easy-to-use commands to retrieve, create, delete, update, list and save text. c o

The Text Editor 3 - 7

3 - 8 GC34-0121

(

\

,

,

Chapter 4. The Macro Assembler

c

This chapter describes the macro assembler-the assembler program and the assembler language. Throughout the chapter, the term assembler is used to denote the macro assembler.

For detailed information about the assembler, refer to the IBM Series/l

Prof?ram Preparation Subsystem: Macro Assembler User's Guide,

SC34-0124. c

The Assembler Program

The assembler program processes the machine, assembler and macro instructions you have coded in assembler language (the source program) and produces an object module in machine language.

The assembler also produces information for other programs. The application builder uses such information to combine object modules into load modules. The assembler processing sequence is illustrated in Figure 4-1.

Defining Assembler Data Sets

Before you can use the assembler program, you must define certain data sets to establish the DSD environment for assembler processing.

The DSD names and descriptions of data sets the assembler uses are summarized in the following chart.

DSD Name

LIB 1 AND/OR LIB2

OBJOUT

PRINT

SOURCIN

SYSLOG

TSOVLY

WORK 1, WORK2, WORK3

WORKVOL

Description

System or user macro data sets-disk or diskette data sets that define the location of macro files.

(Optional)

Object module output data set that defines the location where object modules are to be saved.

Output print device-usually a printer where listings are to be printed.

Assembler input data set-a disk or diskette data set that defines the location of input source modules.

Device or data set where error messages can be printed.

(Optional)

Assembler phase and overlay data set.

Work data sets used in assembler processing.

Volume from which space for

WORKl,WORK2 and WORK3 is obtained. o

The Macro Assembler 4 - 1

Invoking the Assembler

If you have already set up the recommended program preparation default environment-with DSDs for assembler work data sets, system logging device, object data sets, printer and system macro library-you can invoke the assembler through these simple control statements.

ASMl

STEPl

JOB ENVL=ALIST

EXEC TSN=CPA

EOJ where ASMI is the name of your job, ALIST refers to the environment list containing the required DSDs, and CPA is the assembler task set name.

(- "

Coding and entering the source program

Assembler processing

Source program

Macro generation and conditional assembly

I

I

Assembler to machine language

I

I

{

'-

;

"

4 - 2 GC34-0121

Figure 4-1. Assembler processing sequence

Object module c:

c c

The Assembler Language

Assembler language is a symbolic programming language containing statements that represent instructions and comments. There are three types of instruction statements:

• Machine instructions.

• Assembler instructions.

• Macro instructions.

Machine Instructions

A machine instruction is the mnemonic representation of a single hardware instruction. The mnemonic implies the function and the type of data operated on.

For example, AB means add byte, SW means subtract word, and MVW means move word. The assembler program translates these mnemonic machine instructions into binary instructions that the system can execute.

Each machine instruction generates a hardware instruction. That instruction depends on the operation code and syntax of the operand. Based on the syntax of the operands, the assembler will generate one of several possible hardware instructions. If more than one hardware instruction can perform the operation specified by the mnemonic and its operand, the assembler generates the one that is most efficient in timing and storage usage.

There are more than 200 machine instructions that perform a wide variety of functions. The types of instructions included are:

• Data movement instructions.

• Arithmetic instructions.

• Branching instructions.

• Shift instructions.

• Stack instructions.

• Compare instructions.

• Logical instructions.

• Processor status instructions.

• Privileged instructions.

• Floating point instructions.

The individual instructions contained in each of these groups are described in detail in the

IBM Series/l Program Preparation Subsystem: Macro Assembler

User's Guide,

SC34-0124. Input/Output instructions and data format information will be contained in the

IBM Series/l Realtime Programming

System: Macro User's Guide-Data Management.

Assembler Instructions

An assembler instruction is a request to the assembler program to perform certain operations during the assembly of a source module. Some of these operations are defining data constants, defining the end of the source module, and reserving storage areas. Except for the instructions that define constants or provide boundary alignment, the assembler does not translate assembler instructions into object code.

Summary of Assembler Instructions

The following chart summarizes assembler instructions and their functions. o

The Macro Assembler 4 - 3

4 - 4 GC34-0121

EQU

EQUR

EXTRN

GLOBL

ICTL

ISEQ

ORG

POP

PREF

PRINT

PUSH

SPACE

START

TITLE

USING

WXTRN

Instruction

ALIGN

COM

COpy

CSECT

DC

DROP

DS

DSECT

EJECT

END

ENTRY

Function

Allows you to ensure the setting of the location counter to an odd byte or word address during program assembly.

Initiates a common control section or indicates its continuation.

Allows you to copy predefined source statements from a library and include them in your source module.

Initiates an executable control section or indicates its continuation.

Allows you to define data constants needed for program execution.

Allows you to terminate the USING domain for one or more registers.

Allows you to reserve areas of storage, provide labels for these areas and use these areas by referring to the symbols defined as labels.

Initiates a dummy control section or indicates its continuation.

Stops the printing of an assembly listing on the current page and continues printing on the next page.

Marks the end of a source module to indicate to the assembler where to stop assembly processing.

Allows you to identify symbols defined in the source module containing the ENTRY instruction so you can refer to them in another source module. These symbols define locations called entry points.

Allows you to assign absolute or relocatable values to symbols.

Allows you to define a register symbol by assigning to the symbol the value of an absolute expression.

Allows you to identify those symbols that are referred to in the source module containing the EXTRN instruction but are defined in another source module. These symbols are called external symbols.

Initiates a global control section or indicates its continuation.

Allows you to change the begin, end, and continue columns to establish a different coding format for your source statements.

Causes the assembler to sequence-check the statements in your source module.

Alters the setting of the location counters and thus controls the structure of the current control section. You can, therefore, redefine parts of a control section.

Restores the control section to the section on the top of the internal assembler section stack.

Allows you to generate a 1- to 5-word parameter list.

Allows you to control the amount of detail you want printed in the listing of your program.

Saves information about the current control section in an internal assembler stack.

Allows you to insert one or more blank lines in the assembly listing.

Initiates the first executable control section in your source module.

Allows you to provide headings for each page of the assembly listing.

Allows you to specify that a register is available for use as a base register.

Allows you to identify those symbols that are referred to in the source module containing the WXTRN instruction but defined in another source module.

(

\

\

, c

c c

Macro Instructions

A macro instruction is a request to the assembler program to generate a predefined sequence of machine and assembler instructions. This predefined sequence of code is called a macro definition.

You can prepare your own macro definitions and invoke them by coding the appropriate macro instruction. From the macro definitions, the assembler generates an instruction sequence that is processed as if it were part of the original input in the source module.

The conditional assembly language is used within a macro definition to process input from a calling macro instruction. The conditional assembly language allows you to:

• Select statements for generation.

• Determine the generation order.

• Perform computations that affect the content of the generated statements.

• Produce assembly-time messages through the MNOTE instruction.

Macro instructions simplify coding for functions that are complex or occur frequently in a program. When you create your own macros, you can tailor the code with parameters you supply as operands. Each time you specify a macro in your program, the parameters you name are substituted for the prototype operands when the assembler program expands the macro.

The advantage to using macro language is that you reduce programming effort.

You write and test the code for a macro definition only once. You and other programmers can then use the same code as often as you need by calling the definition. You only need to code one macro instruction to call for the generation of many assembler language statements from the macro definition.

Macro Instructions and Their Functions

The following chart summarizes the macro language instructions and their functions. o

The Macro Assembler 4 - 5

4-6 GC34-0121

Instruction

macro name prototype name

ACTR

AGO

AIF

ANOP

GBLA

GBLB

GBLC

LCLA

LCLB

LCLC

MACRO

MEND

MEXIT

MNOTE

SETA

SETB

SETC

Function

Provides the name of the macro definition.

Provides a symbol that identifies the macro definition.

Sets a conditional assembly loop counter.

Provides an unconditional branch.

Provides a conditional branch.

No operation-branches to next sequential instruction.

Allows you to declare initial value, type, and array dimensions for variable symbols (global

SETA).

Note.

Global variables communicate values between macro definitions.

Allows you to declare initial value, type, and array dimensions for variable symbols (global

SETB).

Allows you to declare initial value, type, and array dimensions for variable symbols (global

SETC).

Allows you to declare initial value, type, and array dimensions for variable symbols Oocal

SETA).

Note.

Local variables are communicated within a single macro definition.

Allows you to declare initial value, type, and array dimensions for variable symbols (local

SETB).

Allows you to declare initial value, type, and array dimensions for variable symbols (local

SETC).

Serves as the macro definition header. It is the first statement of every macro definition.

Indicates the end of a macro definition and provides an exit from the end of the macro definition when it is processed during macro expansion.

Causes the assembler to stop processing a macro definition and provides an exit from the middle of a macro definition when it is processed during macro expansion.

Allows you to generate an error message with an error condition code attached or to generate comments whereby you can display the results of preassembly operations.

Allows you to assign values to variable symbols

(arithmetic).

Allows you to assign values to variable symbols

(binary).

Allows you to assign values to variable symbols

(character) .

(~

(

,

,

"

(:

c c

Assembler Coding Features

The assembler features make assembler language coding easier.

Symbolic Representation of Program Elements

Use of symbols can reduce programming effort and errors. Symbols can represent storage addresses, displacements, constants, registers, and other elements of the assembler language. Besides being easier to remember and code, the symbols are listed in a symbolic cross reference table in your program listing. This makes it easy to find a particular symbol when searching for an error in your code.

Variety of Data Representation

You can represent data in character, decimal, binary, ASCII, or hexadecimal. The assembler converts these values to binary values required by the machine instructions.

Relocatable Object Modules

These object modules can be relocated from the originally-assigned storage area to any other suitable main storage area without affecting program execution.

Assignment to a physical memory location can be deferred until the code is linked with other object modules at application build time.

Address Assignment

To locate data to be operated on, most machine instructions refer to a storage address. You need not be concerned with specific main storage locations when you write a program because the assembler keeps track of locations of statements in your program (relative to the beginning of your program), then assigns addresses and displacements required when it produces the object program.

Flexible Register Usage

There are eight general-purpose registers that can be used to hold a value, an address, or displacement for manipulating data, maintaining counters, or determining the address of a particular instruction or storage location.

Program Sections

You can code a program in sections and, later, at application build time, combine the sections into an executable program. Advantages to this are:

• Many programmers can work on a large program, with each programmer working independently coding, assembling, and debugging his own section of the program.

• Less computer time is required because you can reassemble a section for the already-assembled program rather than reassembling the entire program.

• Sections common to more than one program are assembled only once, then linked to the unique sections of each program. This reduces computer time and results in shorter assembly listings that are easier to debug.

• You can configure a program to various main storage requirements much more easily by linking the sections into different combinations of storage loads or phases. o

The Macro Assembler 4 - 7

The four types of program sections that can be defined in the assembler language are summarized in the following chart.

Section Type

Control section

Common section

Global section

Dummy section

Assembler Instruction

ST AR T or CSECT

COM

GLOBL

DSECT

Function

Defines the object codethat is, machine instructions and data definitions.

Defines an area of storage that can be shared with the program sections in multiple assemblies within a task.

Defines either task set global or system global. Task set global is addressable by all programs executing in the same partition. System global is contained in the shared task set and is addressable by all programs linked to the shared task set.

Describes the format of data located elsewhere.

Symbolic Linkages Between Separately-Assembled Source Modules

Symbols can be defined in one module and referred to in another. If a linkage symbol is referenced by another module, it must be identified by an ENTRY assembler instruction unless it is a ST ART or CSECT statement. If a module refers to a linkage symbol defined in another module, the symbol must be identified by an EXTRN or WXTRN statement.

Comprehensive Assembler Listings

The listings generated by the assembler contain source statements, macro expansions, ESD, RLD and cross reference tables, error messages and statistics.

You can control the content of the listing output with assembler options.

C

....

'

4 - 8 GC34-0121

c c

Assembler Options

The following chart summarizes the assembler options. (Defaults are underlined).

You can specify parameters to the assembler through the P ARM control statement.

Option

LIST /NOLIST

XREF /NOXREF /FULLXREF

ESD/NOESD

RLD/NORLD

SYSPARM(' .. .')

OBJECT /NOOBJECT

LINECOUNT (n)

MACRO/NOMACRO

Explanation

LIST -write all assembly listings to the PRINT data set.

NOLIST-write only error messages to the PRINT data set.

TEXT -write source and object program listing to the

PRINT data set.

NOTEXT -suppresses the option.

XREF-write cross reference listing to the PRINT data set only for referenced symbols.

NOXREF-suppresses this processing.

FULLXREF-write the cross-reference listing to the

PRINT data set for all defined and referenced symbols.

ESD-write the external symbol dictionary before the source program listing.

NOESD-suppresses the option.

RLD-write relocation dictionary after source program listing

NORLD-suppresses the option.

Defines up to 8 characters of information substituted for the & SYSPARM value during macro processing.

OBJECT causes the object module to be written to the OBJOUT data set.

NOOBJECT suppresses this processing.

LINECOUNT specifies

n

as the number of lines per page of the PRINT data set. Default line count is 55.

The value of

n

can be from 1-999.

MACRO-macro processing is desired.

NO MACRO-suppresses macro processing.

Structured Macro Usage

A set of structured macros, which can be used as input to the assembler, is provided in a separate macro library. Some advantages of using structured macros are:

• They eliminate branch and jump instructions in source code.

• They generate reenterable code.

• They allow you to use all hardware facilities (such as indirect addressing) and data types (such as bit processing).

• They permit up to 20 levels of structure nesting.

• They print English-language assembly-time diagnostic messages, which can include the variables you have coded. This helps you to find and correct errors.

• They are easy to read and understand.

Use of structured macros can reduce errors, increase productivity, and reduce development and maintenance costs. o

The Macro Assembler 4 - 9

Summary of Macro Assembler Features

• You can code machine instructions using a function-oriented assembler language-the mnemonics imply the function.

• You can code macro instruction statements to generate a series of assembler language statements.

• You can use conditional assembly instructions within macro definitions to selectively generate sequences of instructions.

• You can use the structured macros.

• Source statements can come from an input data set or from a library.

• The assembler can process four types of program sections----common sections, control sections, global sections, and dummy sections.

• Programs may reference symbols defined in separately-assembled programs.

These external references are later resolved during application builder processing.

• The assembler produces object modules that include information for module relocation and external symbol resolution.

• The assembler also generates comprehensive listings. You can control the listing output by options you specify to the assembler.

(.

"

( ,-

,

" c

4 to GC34-0121

Chapter 5. The Application Builder

c

The application builder handles the final steps in the program preparation sequence.

It is the subsystem component that processes object modules to prepare them for execution as application programs.

To fully understand the significance of application builder processing, you should be familiar with the information presented in the

IBM Series/l Realtime

Programming System: Introduction and Planning Guide,

GC34-0102, particularly the sections describing task sets.

Detailed information about how to use the application builder to build task sets will be contained in

IBM Series/l Program Preparation Subsystem: Application

Builder User's Guide.

Note.

Throughout this chapter, the

Realtime Programming System

is also referred to as the

operating system.

c

Execution Environments Supported

Regardless of the execution environment for which you are preparing the application program, you must at least use the application builder to convert from object module format to composite or absolute load module format. An

object module

produced by a language translator, which is the initial input to the application builder, may contain one or more object programs and control information. The output of application builder processing will depend on how you use the application builder phases.

There are three phases in application builder processing, as shown in Figure

5-1.

Phase 1

Phase 2 Phase 3

o

Application builder

Application builder

Application builder

(optional)

Figure 5-1. The three phases of application builder processing

The Application Builder 5 - 1

Phase 1.

This phase can create a load module in absolute format or a

composite module

in relocatable format. Absolute load modules are not executable under the Realtime Programming System but can be executed in an environment you provide. A composite module, in relocatable format, will be used as input to phase 3 processing. A composite module is made up of object modules

(programs) structured into a resident segment and optional overlay segments.

Phase

2. This phase builds control modules and pre bind modules. The

control module,

which is required by the operating system, provides the tables and control blocks that the system needs in order to execute the functions requested

(data management, queuing, and tasking, for example). The

prebind module,

which is optional, allows you to specify the information needed for binding the required resources to an application task set when it is installed rather than at execution time. This pre binding of resources allows a task set to start execution faster.

Phase

3. This phase creates task sets that will be executable in the Realtime

Programming System environment. A task set is a planned program structure-a named collection of programs, data, and control blocks designed to execute within a partition under the operating system.

If you are creating an application program for execution in an environment you provide, you need only use the application builder for phase 1 processing. If you are creating an application program for execution under the operating system, you must use the application builder for all three phases in order to supply the information needed by the system to execute your application program, which must be in the form of a task set.

To simplify describing the phases of the application builder, this chapter first gives a brief explanation of what you must do to create an application program for execution in an environment other than that of the Realtime Programming

System. The rest of this chapter assumes that you are using the application builder to create an application program (a task set) that will execute under the operating system.

An Environment You Provide

This can be any execution environment other than the Realtime Programming

System environment. Creating an absolute load module for execution in an environment you provide requires only phase 1 processing.

(

~:

_

f f '

,_ ; c

5 - 2 GC34-0121

c c

Creating Absolute Load Modules

Phase 1 combines object modules produced by a language translator to create an absolute load module. The application builder control statements allow you to identify the contents, structure and name of the output load module. Through phase 1 control statements, you can specify the:

• Object modules to be included in the output load module (INCLUDE statement).

• Entry point of the output load module (ENTRY statement).

• Member name of an output load module, if more than one absolute load module is being created (NAME statement).

• Format of the output module-absolute or rclocatab1c (FORMAT statement).

You

must

specify an origin on the FORMAT control statement in order to create a load module in absolute format. Phase 1 processing assigns origin addresses to control sections and resolves external references within the control sections. The origin address will be whatever you specify on the FORMAT statement. References in one control section to items in another control section of a different object module are resolved relative to the address assigned to the item in the output load module.

The output load module, in absolute format, consists of a header record

(containing descriptive information about the load module-such as its name, origin address, length of text, etc.,) and text records, which make up an executable program with all address constants resolved against a specific storage address. An absolute load module is not executable under the Realtime

Programming System, and you cannot use any of the system support functions.

You must also provide a means of loading the module into storage and passing control to it. The DISK IPL Bootstrap Loader, which is described in the IBM

Series/l Stand-Alone Utilities User's Guide,

GC34-0070, can be used for loading a program into storage and passing control to it.

The Realtime Programming System Execution Environment

To create an application program that can execute in the Realtime Programming

System environment, you must use phases 1, 2, and 3, of the application builder.

Phases 1 and 2 create modules that are input to phase 3, which combines them into a task set and writes that task set to a

task set library.

A task set library is a volume containing all of the modules and tables associated with a single task set.

In phase 3 processing, you must supply partition information because task sets under the Realtime Programming System are executed within a partition. Task sets must be prepared for a specific partition because they are not relocated when loaded.

A task set can have a simple structure, where all segments are resident during execution, or complex structure (overlay), where some segments reside on disk.

In overlay structure, a storage-resident segment of code can request the system to retrieve a unit of code from disk and pass control to it. The specific structure and characteristics of the task set are defined by the information you supply on control statements that are input to the application builder. o

The Application Builder 5 - 3

5 - 4 GC34-0121

Figure 5-2 represents the system and partition storage organization for the

Realtime Programming System execution environment. o

System organization

Partition organization

Primary segment

F x e d

User task set a

(partition # 2) d d

~--~~~~~~~--~---

__ r e s e

64KB

Common area

Overlay area

Task set load module

Secondary segment

Common area

Overlay area

Auto called library subroutines

Control module

f

\

'\

,

Figure 5-2. System and Partition Storage Organization

Task Set Load Module. The task set load module is a structure that contains all resident segments, their associated common and overlay areas, and the control module, for a single task set. c

c

Resident Primary Segment. The resident primary segment is a segment that remains in primary storage for the duration of task set execution. (A program in a resident segment may call a program in another resident segment.) This resident segment contains the initial entry point of a task set. The entry point of a task set must be a primary program within the primary segment.

Common Area. The common area reserves an area of storage and can be referred to by resident and overlay segments that are associated with a given primary or secondary segment within a task set.

Overlay Area. The overlay area is where disk overlays are loaded and passed control. Each resident segment that calls overlays has its own disk overlay area.

Resident Secondary Segment. The resident secondary segment can be any resident segment other than the primary segment of a task set. It differs from a primary segment in that it does not contain the task set's entry point.

Resident Library Subroutines AutocaUed. These are modules whose purpose is to complete a resolution within the task set load module. These routines are obtained from a disk-resident autocall library and are added to the task set as if they were another resident secondary segment.

Control Module. A

control module is required by the operating system for task set execution. It consists of a set of tables and control blocks that the system needs in order to execute the functions requested. c o

The Application Builder 5 - 5

Application Builder Processing

The following sections describe the purpose and functions of each of the three phases of application builder processing. Throughout these sections, it is assumed that you are using the application builder to create a task set for execution under the operating system. Other execution environments are

not

considered.

Phase

1

Processing

Object modules produced by a language translator are not in a format that allows them to be loaded or executed. These object modules contain:

• An external symbol dictionary (ESD) containing information to be used in resolving symbolic references between control sections of different modules.

• Text data that is the actual program instructions and data areas.

• A relocation list dictionary (RLD) containing an entry for each relocatable address constant.

• An end of module record.

Phase 1 combines one or more object modules to form a single composite module, in relocatable format, that will be used as input to phase 3 processing.

(

"

5 - 6

GC34-0121

Figure 5-3. Application Builder phase 1 processing c

Figure 5-4 shows the basic functions performed during phase 1 processing. c

Phase I processing

• Combining object modules

• Assigning addresses

• Resolving external references c

Composite Module Output

Printed Output

Figure 5-4. Combining object modules

Composite modules produced by phase 1 can be simple or overlay structured.

Overlay structured modules consist of multiple segments. The first segment is the resident segment, and successive segments are the overlay segments.

A composite module can be placed in a consecutive data set or placed as a member of a partitioned data set. Composite modules grouped within a partitioned data set form a composite module library.

In

addition to the output composite module, phase 1 produces:

• A listing of your control statements.

• A composite module map identifying names and assigned addresses of control sections.

• Diagnostic messages indicating results of phase 1 processing. o

The Application Builder 5 - 7

Phase 1 Control Statements

The phase 1 control statements allow you to identify the contents, structure, and name of the output composite module. The following chart summarizes phase 1 control statements.

Control Statement

PHASE1

INCLUDE

OVERLAY

ENTRY

NAME

FORMAT

Purpose

Introduces phase 1 control statements and causes phase 1 to be invoked.

Specifies object modules to be included in the composite module.

Identifies the beginning of an overlay segment.

Identifies an entry point to a program in the primary resident segment.

Identifies the member name of the composite module.

Identifies the type of output module

(absolute or relocatable).

(

-~

,

Phase

2

Processing

Phase 2 creates the control module and, optionally, a prebind module to be used in the Realtime Programming System execution environment.

Control Module

A control module provides the tables and control blocks required by the system to execute the functions requested. This may include:

• The task set control block.

• A DSD list of data sets to be pre bound.

• Preallocated control block stacks.

• The variable control block area, which is an area of storage available for variable length control blocks (for the supervisor and data management).

• Sensor

110

tables.

The control module, which is required by the system for execution of task sets, is included in the task set produced by phase 3 processing and occupies storage in the partition in which the task set will execute.

( '\

,_ , c

5 - 8 GC34-0121

c

Prebind Module

A prebind module is used to specify the required resources to be pre bound to an application task set at installation time rather than at execution time. The pre bind module is optional and does not occupy storage in the user partition. Through the application builder control statements, you can specify pre binding to be performed in order to:

• Prebind tasks by allocating control blocks and task work stacks.

• Predefine queues by allocating control blocks and preopening disk data sets for disk queues.

• Establish the conditions under which scheduled task sets are to execute, by updating the system scheduler table.

• Preopen data sets.

Phase 2 processing also generates a list of your control statements and a list of error messages. Figure 5-5 illustrates phase 2 processing.

Control statements

Application builder

(optional)

c

Figure 5-5. Application builder phase 2 processing o

The Application Builder 5 - 9

Control Statements

Phase 2 control statements can be used to define the control module or both the control and prebind modules. The following chart summarizes phase 2 control statements.

Control Statement

PHASE2

TASKSET

TASK

SIO

CTBLKS

QUEUE

DATASETS

EXCOND

SHARING

Purpose

Introduces phase 2 control statements and causes phase 2 to be invoked.

Describes the task set

(name, partition, etc.).

Describes a task (entry point, dispatching priority, etc.).

Defines sensor I/O used by task set.

Pre allocates control blocks needed at execution.

Defines the queue to be prebound to the task set.

Defines data sets to be prebound to a task set.

Describes a condition under which the task set is to be executed.

Defines resource names that are otherwise not defined in the control module or task set. This lets you define names of resources (in a shared task set) that may be used by other task sets.

For Control Module

X

X

X

X

X

X

X

For Prebind

Module

X

X

X

X

(

,

,

, c

5 - 10

GC34-0121

c

Phase

3

Processing

Phase 3 combines the modules created in phases 1 and 2 to create a task set that is executable in the Realtime Programming System environment. The primary input to phase 3 consists of the modules produced by phases 1 and 2. These modules may be obtained from:

• Data sets containing the control module and pre bind module.

• An autocall library.

• A consecutive data set or a partitioned data set (library) that you specify through the phase 3 INCLUDE control statement.

Figure 5-6 illustrates phase 3 processing.

I

8

I c

Composite module

Control module

Prebind module

(optional)

Application builder

Control statements

Figure 5-6. Application builder phase 3 processing o

The Application Builder 5 - 11

Control Statements

Basically, phase 3 processing involves the following operations.

Control Statement and Composite Module Processing. Your input control statements are analyzed and processed. Composite modules are combined into a single task set, with all addresses resolved relative to a partition origin.

External Reference Resolution. External references from a composite module are resolved to definitions in other modules, a shared task set, or a module from the autocall library that is automatically included in the task set.

Global Processing. Global sections from the composite modules are combined into a task set global area.

Overlay Processing. Overlay segments from the composite modules are combined into a separate data set that will be used during task set execution. Space is allocated in the task set load module for each overlay area.

Task Set Creation. Resident programs, overlay areas, and the task set control module make up a task set load module with addresses assigned and references resolved. The task set load module is written to a data set in the task set library.

Indicating Results of Processing. A return code indicates whether or not phase 3 was completed successfully. You get a listing of control statements, a task set map, and diagnostic messages.

( .~

.~

Through phase 3 control statements, you can specify the contents, structure, and characteristics of the output task set. The following chart summarizes phase 3 control statements.

Control Statements

PHASE3

INCLUDE

PARTN

Purpose

Introduces phase 3 control statements and causes phase 3 to be invoked.

Identifies composite modules that are to be combined to form a task set.

Specifies characteristics of the task set and the partition in which it is to execute. c

5 - 12 GC34-0121

c c

Summary of Application Builder Data Sets

The following chart summarizes the DSD names and descriptions of data sets used by the application builder to obtain its input, perform the processing requested, and produce the appropriate output.

DSD Name

APBIN

AUTOI-AUT03

BUILDINI-BUILDIN5

CONTROL

LMODOUT

LOADI-LOAD5

PBMDS

PRINT

SYSLOG

TSLIB

TSLOAD

TSOVLY

TSRTDS

TSSHARE

WORKl, WORK2, WORK3

WORK4

WORKVOL

Description

Contains the control statements you specify.

Indicates libraries used for automatic call processing.

(Autocall processing allows modules to be obtained automatically from a program library.)

Identify data sets (partitioned or consecutive) containing object modules to be included as input to phase

1.

Identifies a partitioned data set to contain the control module and (optionally) the prebind module.

Identifies the data set (partitioned or consecutive) to contain the output module created in phase 1 processing.

Identify data sets (partitioned or consecutive) containing composite modules to be included as input to phase 3.

Identifies the data set that is to contain the resolved prebind module for a task set.

Identifies the output data set to contain listing information such as control statements and maps.

Identifies system message log device.

Identifies volume in which the unbound task set, disk overlay module, and resolved prebind module data sets are defined.

Identifies the data set that is to contain the output task set.

Identifies the data set to contain disk overlays.

Identifies the data set that is to contain the task set reference table.

Identifies the consecutive data set containing the task set reference table of the shared task set to be used for resolution when building your task set.

Identifies intermediate work data sets.

Identifies a data set to contain overflow queues.

Volume from which space for work data sets can be allocated. Any or all of the WORKI-WORK4 data sets can be allocated from that volume. o

Invoking the Application Builder

Assuming you have defined the required data sets and devices and have described the content and structure of the output module, the following example shows the minimum control statements needed to invoke the application builder.

APBl

STEPl

JOB ENVL=APBLST

EXEC TSN=CPD

EOJ where APB! is the name of your job, APBLST refers to the environment list containing the required DSDs, and CPD is the task set name of the application builder.

The Application Builder 5 - 13

Listing and Processing Options

You can specify certain listing and processing options to the application builder through the job stream processor P ARM statement. These parameters are passed to the application builder by the job stream processor.

The following chart summarizes the options. Defaults are underlined.

Options

LIST = YES

NO

MAP = ALL

LM

TS

NO

AUTO =YES

STS =

YES

Explanation

YES causes a listing of the specified input to be created.

NO suppresses the LIST option

The MAP option causes a map of the output data set to be created. The map indicates the structure and symbols, both resolved and unresolved.

ALL causes a map for the composite module and task set to be created.

LM causes a map to be created for only the composite module.

TS causes a map to be created for the task set only.

NO suppresses the MAP option.

YES causes a further attempt to resolve symbols that are unresolved from within a task set by checking a library you specify for the unresolved symbol.

NO suppresses this option.

YES causes a shared task set file to be checked to resolve unresolved symbols before an attempt is made using the

AUTO option.

NO suppresses this option. c c

5 - 14 GC34-0121

c

Summary of Application Builder Features

• The application builder performs the necessary processing operations-such as assigning storage addresses and resolving external references-to combine input object modules and create an absolute load module or a composite module.

• It allows for creating an absolute load module that is executable in an environment you provide.

• It allows for creating a composite module that will undergo further application builder processing to ultimately become part of a task set that will be executable in the Realtime Programming System environment.

• It allows modules to be obtained automatically from a program library.

• It provides for recycling to create multiple composite modules.

• It allows for creating a control module, which provides the control blocks that the system needs to execute such functions as data management, queuing, and tasking.

• It allows for creating a pre bind module, which contains specifications that can be used to prebind resources to a task set at installation time rather than at execution time.

• It allows you to create task sets that will be executable in the Realtime

Programming System environment. c o

The Application Builder 5 - 15

5 - 16 GC34-0121

Appendix A. Configuration Requirements

c

Hardware

Storage Reqlliremellts

The Program Preparation Subsystem uses the hardware required and supported by the Realtime Programming System. The minimum hardware (and optional hardware) to be used for the subsystem programs is described in chapter 1 of this publication.

To install the subsystem programs, you need a minimum of 48KB of processor storage. For installation, the entire 48KB is used by the starter system, but once the subsystem programs are installed, a minimum of 16KB is required for executing these programs.

Disk Reqllirements

The subsystem programs are installed by using the starter system provided by the

Realtime Programming System and copying the programs from diskettes to disk.

Once these programs are installed, the starter system is deleted from disk and therefore is not considered disk space that must be permanently reserved.

The subsystem programs will require the following estimated space.

Note.

The total number of cylinders on the disk is 302. c

Program Residency Space

The amount of space required for each subsystem program is:

Subsystem program

Job stream processor

Text editor

Macro assembler

Application builder

Total

Cylinders

0.7

1.0

5.0

3.0

9.7

Message Data Set Space o

The amount of space required for the subsystem programs that have defined a separate data set for their messages is:

Subsystem program

Job stream processor

Text editor

Macro assembler

Application builder

Total

Sectors

25

-

-

34

59 sectors (0.5 cylinders)

Note.

Message data set space for the macro assembler and application builder is included in the program residency space.

Configuration Requirements A-I

Work Data Set Space

The amount of space required to satisfy typical use of the subsystem program during its execution is:

Subsystem program

Job stream processor

Text editor

~acro assembler

Application builder

Total

Cylinders

00.5

57.0

50.0

41.0

57.0**

**Since only one batch program will be executing at any given time, it is expected that the same workspace will usually be used by all the subsystem programs. Therefore, only the largest workspace requirement is accounted for in determining workspace requirements.

Total Disk Space

Diskene Requirements

The estimated total disk space required for the subsystem programs is:

Disk space

Program residency space

~essage data set space

Work data set space

Total

Cylinders

09.7

00.5

57.0

67.2

(68)

Note.

This total amount does not account for control blocks/tables (i.e., data set definition table (DSDT) that is defined within each task set library), which will be required for subsystem components. However, any additional space is considered negligible compared to the total above.

The only requirement the subsystem programs have for diskettes is during installation. The Program Preparation Subsystem program product is on six diskettes.

1. The job stream processor, generation program, application builder, and verification compare program.

2. Job stream processor and text editor composite modules.

3. Macro assembler object modules.

4. Application builder composite modules.

5. Structured macros.

6. Structured macros.

The data copied to disk from the first diskette will not be retained after the

Program Preparation Subsystem is installed. If the subsystem programs must be reinstalled, the starter system and first diskette are again copied to disk, and the process is repeated.

(

'\

,-

, c

A - 2 GC34-0121

c

Timer Requirements

The timer is an optional feature. If available, the subsystem programs will use its services as follows.

Subsystem Program

Job stream processor

Text editor

Macro assembler

Use

Date/time stamping jobs (job accounting).

Date/time stamping editing sessions that are saved for restarting at a later time.

Dat~/tim~ stamping assembled output listing.

Printer Requirements

The Program Preparation Subsystem generation program generates job stream processor control statements of up to 80 characters in length. These control statements will be listed at the printer.

Each subsystem program will require a printer to display its output. Depending on the subsystem program in use, from 120 to 132 characters will be required for use from the 132-character printer line length.

The job stream processor and text editor do not necessarily require a printer for execution. c

Programming Requirements

In order to support the Program Preparation Subsystem program product, the only requirement in the SYSGEN of the Realtime Programming System is that a batch partition of a minimum of 16KB of processor storage be defined. The basic

Realtime Programming System provides all the support functions (that is, supervisor, data management, utilities) required for installation and for the subsystem programs to operate.

Compatibilities

The Base Program Preparation Facilities and the Program Preparation Subsystem

The Program Preparation Subsystem assembler language syntax is compatible with that of the Base Program Preparation Facilities assembler language. Any statement using the Base Program Preparation Facilities assembler syntax will assemble properly using the Program Preparation Subsystem macro assembler.

The commands of the Base Program Preparation Facilities and Program

Preparation Subsystem text editors are compatible. Although the subsystem text editor has additional commands, the commands common to both text editors have the same syntactical operands. The one exception to this is the data set references on the get (GE) and save (SA) commands for the subsystem text editor. o

Configuration Requirements A - 3

The Realtime Programming System and the Program Preparation Subsystem

The Program Preparation Subsystem uses the Realtime Programming System standard system and data management interfaces to perform the following types of operations:

• Space allocation.

• Task set transfer control and queuing.

• Data set creation.

• Accessing and deleting data sets.

• Parameter passing.

C

A - 4 GC34-0121 c

Appendix B. Using the Series/1 Programming Library

c c

BUILDING THE PROGRAM

PREPARATION SUBSYSTEM

From the time you plan and install your system until the time you are actually running your application programs on the Series/I, you will be involved in a variety of activities. In the course of these activities, you will be gathering information from various publications. Knowing which publication to use for which type of activity can make your job much easier.

To make it easier for you to find the publication you need, this appendix summarizes the steps involved in various types of programmer activities and ties them to the appropriate Series/l programming publication (or publications).

Note.

For an overview of Series/1 system functions and a comparison of how they are supported by different languages, operator commands, or macros, refer to the "Summary of System Functions" in the

IBM Series/1 Realtime

Programming System: Introduction and Planning Guide,

GC34-0102.

The following table shows the programmer activity, the associated system step, and the related publications. Order numbers are given for publications that are available at this time.

Refer to Publications ... For the following activity ... The associated system step is ...

PLANNING AND SYSTEM DESIGN

·

Understanding the Realtime

Programming System and the purpose of each of the program products in the

Series/l software system.

·

Understanding the purpose and features of:

The Program Preparation

Subsystem.

-

PL/l.

None.

-

FORTRAN IY.

The Mathematical and Functional

Subroutine Library (MFSL).

·

Understanding the total Series/l hardware and software offering.

BUILDING THE REAL TIME

PROGRAMMING SYSTEM

System generation.

System generation.

IBM Series/l Realtime Programming

System: Introduction and Planning Guide,

GC34-0102

IBM Series/l Program Preparation

Subsystem: Introduction,

GC34-0121

IBM Series/l PL/I: Introduction,

GC34-0084

IBM Series/l FORTRAN IV: Introduction,

GC34-0132

IBM Series/l Mathematical and

Functional Subroutine Library: Introduction,

GC34··0138

IBM Series/l System Summary,

GA34-0035

IBM Series/l Realtime Programming

System Generation and Installation

Procedures

IBM Series/l Program Preparation

Subsystem: Batch User's Guide

o

Using the Series/l Programming Library B-1

For the following activity ...

CODING YOUR PROGRAMS

·

Assembler language programs.

The associated system step is ...

None.

-

Using the routines in the

Mathematical and Funct ional

Subroutine Library.

Using the Realtime Programming

System macros.

·

FORTRAN IV language programs.

-

Using the routines in the

Mathematical and Functional

Subroutine Library.

·

PL/I programs

USING THE OPERATOR CONSOLE

USING THE JOB CONTROL

LANGUAGE

CREATING SOURCE MODULES

CREATING OBJECT MODULES

Job stream processor.

Text editor.

Assembler program.

CREA TING COMPOSITE MODULES

PL/I compiler.

FORTRAN IV compiler.

Application builder.

·

PL/I considerations.

·

FORTRAN considerations.

CREATING APPLICATION TASK

SETS

·

Planning application task sets.

Application builder.

·

Building application task sets.

-

PL/I considerations.

-

FORTRAN IV considerations.

USING THE REAL TIME

PROGRAMMING SYSTEM UTILITY

PROGRAMS

Utilities.

Refer to Publications ...

IBM Series/} Program Preparation

Subsystem: Macro Assembler User's Guide,

SC34-0124

IBM Series/} Program Preparation

Subsystem: Macro Assembler Reference

Summary

IBM Series/} Mathematical and

Functional Subroutine Library User's Guide

IBM Series/} Realtime Programming

System Macro User's Guide-Supervisor

IBM Series /} FOR TRAN IV Language

Reference,

GC34-0133

IBM Series/} Mathematical and

Functional Subroutine Library User's Guide

IBM Series/} PL/ I Language Reference

IBM Series/} Realtime Programming

System: Operator Commands and Utilities

IBM Series/} Program Preparation

Subsystem: Batch User's Guide

IBM Series/} Program Preparation

Subsystem: Text Editor User's Guide

IBM Series/} Program Preparation

Subsystem: Macro Assembler User's Guide,

SC43-0124

IBM Series/} PL/I User's Guide

IBM Series/} FOR TRAN IV User's Guide

IBM Series/} Program Preparation

Subsystem: Application Builder User's

Guide

IBM Series/} PL/I User's Guide

IBM Series/} FORTRAN IV User's Guide

IBM Series/} Program Preparation

Subsystem: Application Builder User's

Guide

IBM Series/} Realtime Programming

System: Introduction and Planning Guide,

GC34-0102

IBM Series/} Realtime Programming

System: Macro User's Guide-Supervisor

IBM Series/} Program Preparation

Subsystem: Application Builder User's

Guide

IBM Series/} PL/ I User's Guide

IBM Series/} FORTRAN IV User's Guide

IBM Series/} Realtime Programming

System: Operator Commands and Utilities

c

B-2 GC34-0121

c

For the following activity ...

CREATING A COMMUNICATIONS

SYSTEM

INSTALLING TASK SETS

EXECUTING TASK SETS

DEBUGGING TASK SETS

The associated system step is ... Refer to Publications ...

A series of steps using the utility DEFINE and COPY facilities and the install option on the start task set operator command.

Direct-start task operator command or supervisor macro.

IBM Series/' Realtime Programming

System: Macro User's

Guide-Communications

IBM Series/' Realtime Programming

System: Macro User's Guide-Supervisor

Batch-job stream processor

Error management.

Messages and codes (Realtime

Programming System).

Messages and codes (Program

Preparation Subsystem).

Messages and codes (PL/I).

Messages and codes (FORTRAN).

Debugging.

IBM Series/' Realtime Programming

System: Operator Commands and Utilities

IBM Series/' Realtime Programming

System: Macro User's Guide-Supervisor

IBM Series/' Program Preparation

Subsystem: Batch User's Guide

IBM Series/' Realtime Programming

System: Macro User's Guide-Supervisor

IBM Series/' Realtime Programming

System: Messages and Codes

IBM Series/' Program Preparation

Subsystem: Messages and Codes

IBM Series/' PL/I: Messages

IBM Series/' FORTRAN IV User's Guide

IBM Series/' Realtime Programming

System: Control Blocks and Debugging

Guide

c o

Using the Series/1 Programming Library B-3

B-4 GC34-0121 c

(

,

,

, c

o c o

Glossary

This glossary contains only those terms that are referenced in this manual, and all definitions given are Series/l-oriented. You may also want to refer to the glossary contained in the IBM Series/l Realtime Programming System:

Introduction and Planning Guide, GC34-0102. absolute load module. A combination of object modules having cross references resolved and prepared for loading into storage for execution at a specific address.

This load module is not executable in the Realtime Programming System environment, but may be executable in a user-provided execution environment.

It is an output of application builder phase 1 processing. app6cation buDder. The subsystem program (operating in conjunction with the job stream processor under control of the Realtime Programming System) that prepares the object module output of language translators for execution. To create output that is executable in a user-provided environment, it can be used to create an absolute load module (an output of phase 1 processing). To create output that is executable under the Realtime Programming System, it can be used to create a task set (the final output from processing performed in phases 1, 2, and 3). autocall 6brary. Disk-resident composite module library used by the application builder to obtain those modules that contain a program that can resolve a reference from another program in a task set. batch execution. Program execution initiated by the job stream processor in response to job control statements. batch partition. The user partition that is used by and managed by the job stream processor. batch program. Any of the subsystem programs or user task sets initiated by the job stream processor. bound task set load module. A task set load module that has been bound to its execution environment. The bound task set load module contains the image of the partition at the completion of task set installation. command. A character string that represents a request for action within the system from a source external to the system. common control section. A type of control section that reserves an area of storage. It can be referred to by resident and overlay segments that are associated with a given primary or secondary segment within a task set.

Glossary G - 1

G-2 GC34-0121 composite module.

Object modules (programs) structured into a resident segment and optional overlay segments. A composite module is in relocatable format; that is, its addresses can be modified to compensate for a change in its origin. It is the output of phase 1 and input to phase 3 of application builder processing. consecutive data set. A collection of data, having a consecutive arrangement, to which the system has access. control module. A set of tables and control blocks that contain control and parameter information pertaining to the task set. It is one of the modules produced by the application builder and subsequently included in the task set load module.

C

._~ data set. A named collection of data which resides on a device. data set definition (DSD).

Describes and locates a data set being used by a task set. It exists in the using program in a DSD table data set in the task set library.

The DSD is accessed when the data set is opened. data set definition name (DSD name). The external name of a DSD table entry used within a task set to reference the data set described by that entry. data set definition statement (DSD statement). A job stream processor control statement that allows the user to establish a connection between a data set or device and a DSD name used in a program. data set definition table (DSD table). A table that contains parameters for data sets. data set name (DS name). The term or phrase used to identify a data set. It is contained in the data set definition table of each task set referencing that data set. device. A piece of mechanical, electrical, or electronic equipment used to contain data that is input to or output from the processor. device line. The actual number of characters that can be displayed on one print line of the device. For example, the operator station line length is 72 characters, and the display station line length is 80 characters.

DSD

environment-See

environment.

DSD

name-See

data set definition name.

DSD

statement-See

data set definition statement.

DSDT or DSD table-See data set definition table.

( "

\ , editing session. A period of time beginning when the editor is invoked and ending when the editor has completed processing. c

c c o environment (data set environment). The data set definitions that are in effect at any point in time during a batch session. environment list. A data set (or member) containing a group of data set definitions which make up a DSD environment. external symbol dictionary (ESD). Control information, associated with an object or composite module, that identifies the external symbols in the module. fixed line number. The line number assigned to a text record and associated with that text record for the duration of the editing session (unless specifically altered by the user). fixed partition. A partition having a predefined beginning and ending storage address. generation input stream. An input stream created by the generation program which, when executed, produces a system tailored to the user responses to the generation program questions. generation program. The IBM-supplied program that is used at installation time in creating your Program Preparation Subsystem. global area. An uninitialized portion of a partition accessible by any program of a task set in the partition at a given time. The same area may be used by other task sets that execute in the same partition. The size of the global area is determined by the collective sizes for the largest uniquely named (or unnamed) global section definitions. These definitions are declared by programs that make up a task set. global control section. A type of control section that reserves an area of storage.

It can be referred to by any primary or secondary program and their associated overlays within a task set. See also global area. input stream. The sequence of job control statements and data submitted to an operating system through an input device designated for this purpose by the operator. Synonymous with input job stream, job input stream. interactive. A realtime interface between a user and a program system. job. A collection of related problem programs, identified in the input stream by a JOB statement followed by one or more EXEC and data set definition statements. job input stream.

See input stream.

job stream.

See input stream.

Glossary G - 3

G-4 GC34-0121 job stream processor. The Program Preparation Subsystem component that reads and interprets job control statements and processes the requests made by those statements. line. A string of characters accepted by the system as a single block of input from an operator station; for example, all characters entered before the carriage return key or the ENTER key is pressed. For the text editor, it represents the line number plus the text line. line display range. That portion of a line to be displayed or printed out when a line is listed. line length. Logical record length of lines being edited by the text editor. noninteractive. An indirect interface between a user and a program system; for example, through a disk or diskette data set. object module. The output of a single assembly or compilation containing one or more control sections-CSECTs. An object module is equivalent to a program. object module data sets. Disk resident data sets that contain object modules. object module library. A partitioned data set containing mUltiple object modules. operator station. A device through which the primary interaction between the user and a program system occurs. It can be either a display station or any device that can be used as an operator station and is attached to the system through the ASCII Teletypewriter Adapter Feature. overlay area. An area within a task set load module, associated with a given resident segment and used for execution of overlay segments that are located on disk. overlay module. A structure that contains all overlay segments in a single task set. It is one of the modules produced by the application builder as part of a task set library. overlay segment. A segment that resides on secondary storage and is loaded into the overlay area associated with its resident segment. All overlay segments in a composite module are associated with the resident segment in that composite module. A program in an overlay segment can call a program within the same overlay segment or a program in any resident segment.

(

\

"

, partition. A segment of physical and addressable storage which may contain one task set at a time. A partition begins and ends on a 2KB boundary and has a unique numeric ID from 0 to 15. See also fixed partition and user partition. c

c c o partitioned data set. A data set in direct access storage that is divided into partitions, called members, each of which can contain a program, part ofa program, or data. pre bind module. A module that contains the specifications used during task set installation to create the bound task set load module. It is one of the modules produced by the application builder as part of the task set library. prebinding. The connection of a task set's control blocks (both internal and external) and resources before task set execution. primary program. The first program executed under each task in the system. A primary program has a single entry point and must have a program header. A primary program is either reenterable, serially-reusable, or nonreusable and is only invoked by a start task request. primary segment. The resident segment that contains the initial entry point of a task set. The entry point of a task set must be a primary program within the primary segment. processor. (1) In hardware, the resource required to execute an instruction stream. (2) In software, a synonym for processing program. processor storage. The storage provided by one or more processing units. This term pertains to physical locations in hardware devices. program. (1) A named sequence of instructions that operates under the auspices of a task. (2) A program is the output of a single assembly or compilation, containing one or more control sections-CSECTs. A program is equivalent to an object module. program preparation facilities. The subsystem components that are used to create user task sets; These components are the text editor, macro assembler, and application builder. queue. A line or list formed by items in a system that are waiting for service. resident segment. A segment that remains in primary storage for the duration of task set execution. A program in a resident segment may call a program in one of its overlay segments or a program in another resident segment. resource. Any facility of the computing system or operating system required by a job or task, and including main storage, input/output devices, the central processing unit, data sets, and control or processing programs. return code. A code used to influence the execution of succeeding steps in a job in the input stream. An indicator, which is passed from a batch program to the job stream processor, that reflects the status of the batch program at the time of its termination.

Glossary G - 5

G-6 GC34-0121 scheduIing. The ability to imply that a task set should be started at a particular time of day or after a specified time interval. secondary program. Any program other than the primary program of a task. A secondary program may have multiple entry points and mayor may not have a program header. Secondary programs are invoked by a call request or by direct linkages, such as assembler branch instructions. secondary segment. Any resident segment other than the primary segment of a task set. segment. A structure containing one or more programs, which is a portion of a composite module or a task set load module. source module. A collection of source statements which constitute the input to a language translator for a particular translation. These source statements may be created, modified, and listed using the text editor. split screen. The division into sections of a display screen in a manner which allows two or more programs to use the display screen concurrently. spooling. Writing a data set that is found in the input stream to secondary storage. starter system. A supervisor in IPL format which supports the system generation process. step. A request to the job stream processor to execute a program and, optionally, any accompanying statements defining data sets used by the program.

I

\,

\.

; task. The dispatch able entity used by the supervisor to establish and track concurrent program execution within the system. Each task represents a single thread of execution through a program or set of programs. The first program executed under each task is a primary program. All others are secondary programs. task set. A named collection of programs, data, and control blocks designed to execute within a partition. The program of a task set perform a related set of work and execute under one or more tasks. task set library. A logical volume containing all of the data sets associated with a single task set. A task set library may also contain user data sets. task set load module. A structure that contains all resident segments, their associated common and overlay areas, and the control module, for a single task set. A task set load module is loaded from a consecutive data set in the task set library into a partition when the request for the task set becomes the highest priority element in the partition queue. It remains in primary storage for the duration of task set execution. A task set load module is in absolute format; that is, its origin cannot be changed. See bound task set load module and unbound task set load module.

C

-

'

c c text editor. The program preparation facility that is used to create, modify, and list text modules. Text prepared using the text editor may be in the form of source modules, which may be input to the macro assembler,

or

text data, which may be input to a user program or one of the subsystem programs. text module. A term used by the text editor to indicate the data (text) that may be created and maintained using the facilities of the text editor. This data is usually in the form of printable characters (for example, source modules or input data to a user program). timer. A mechanism for defining an interval of time. transient area. A main storage area used for temporary storage of transient programs. transient program. Self-relocating program permanently stored on a system residence device and loaded into the transient area when needed for execution. unbound task set load module. A task set load module that has not been bound to its execution environment. It is one of the modules produced by the application builder as part of a task set library, The unbound task set load module may be loaded into a partition without being prebound, or it may be used as input to task set installation to create a bound task set load module. user partition. A partition that contains a user task set when in execution. work data sets. The data sets and data set members used by the program preparation facilities as temporary work areas. work stack. A list that is constructed and maintained so that the next information to be retrieved is the most recently stored information in the list; that is, a last-in-first-out or pushdown list. It is an area of unprotected main storage allocated to each task and used by the programs executed by that task. o

Glossary G - 7

G - 8 GC34-0121 c

C.

"

·~·'

• c absolute load module creating 5-3 general information 1-6

ACTR instruction 4-6 address assignment application builder processing 5-7 assembler processing 4-7

AGO instruction 4-6

AIF instruction 4-6

ALIGN instruction 4-4

ALTER statement example 2-5 function 2-6 altering location counter setting 4-4

ANOP instruction 4-6

APBIN data set 5-13 application builder data sets and devices 5-13 execution environments supported 5-1 features 5-15 functions 1-6 in program preparation 1-8 invoking 5-13 listing and processing options 5 -14 phase 1 processing 5-6 phase 2 processing 5-8 phase 3 processing 5-11 processing 1-7

ASMGO statement example 1-12,2-3 function 2-6 assembler see macro assembler assembler instructions 4-3 assembly listings 4-9 assigning addresses application builder processing 5-7 assembler processing 4-7 assigning values to variable symbols 4-6

AUTO option 5-14 auto call library in application builder processing 1-6 in phase 3 processing 5-11 purpose 5-5

AUTOI-AUT03libraries 5-13 o

Base Program Preparation Facilities compatibilities A-3 base register 4-4 batch partition 1-13 batch processing 1-1 batch programs invoking 1-13 running 1-11 binding resources 5-9 blank line insertion (assembly listing) 4-4

BLDDSD macro 2-2 bootstrap loader 1-10

BUILDINI-BUILDIN5 data sets 5-13 change field command (CF) 3-6 change text command (CT) 3-6 changing coding format 4-4 clear command (CL) 3-6

CMDIN device 3-5 coding features, assembler 4-7 coding format change 4-4 coding programs in sections 4-7

COM instruction 4-4 commands, text editor capabilities 1-4 summary of 3-6 comment generation, assembler comment indicator-* 2-6 common area 5-5

4-6 common control section 4-4 communications support 1-17 compatibilities

Base Program Preparation Facilities A-3

Realtime Programming System A-4 compile, load, and go example 2-3 for problem solving 1-12 statements 2-3 complex (overlay) structured task set 5-3 composite module creating phase 1 output 5-6 general description 5-2 input to phase 3 5-11 library 5-7 map 5-7 multiple segment 5-7 overlay structured 5-7 conditional assembly language 4-5 conditional assembly loop counter 4-6 configuration requirements A-I

CONTROL data set 5-13 control module control statements 5-10 creating 5-8 definition 5-2 functions 5-8 purpose 1-6 control statements, job stream processor 2-6 copy command (CO) 3-6

COpy instruction 4-4 copying predefined source statements 4-4

CPA-assembler task set name 4-2

CPD-application builder task set name 5-13

CPE-editor task set name 3-5

Index

Index X-I

CPJ-job stream processor task set name 1-13 creating new text

see

insert command cross reference listing options 4-9

CSECT instruction 4-4

CTBLKS statement 5-10 current status command (CS) 3-6 data constants, defining 4-4 data representation 4-7 data sets and devices for subsystem job stream processor 1-13 summary of data sets for application builder 5-13 for macro assembler 4-1 for text editor 3-5 work data sets for application builder 5-13 for job stream processor 1-14 for macro assembler 4-1 for text editor 3-5 general information 1-15

DATASETS statement 5-10 date/time stamping jobs A-3

DC instruction 4-4 default data set definitions 1-14

DEFDSD macro 2-2

DEFINE utility 2-2 defining a register symbol 4-4 defining assembler data sets 4-1 defining data constants 4-4 defining data sets 2-2 delete command (DE) 3-6 devices and data sets for subsystem 1-14 diagnostic messages, phase 3 5-12 dictionary, external symbol 5-6 dictionary, relocation list 5-6 disk IPL bootstrap loader 1-10 disk overlay area 5-5 disk requirements A-I diskette requirements A-2 display station in hardware configuration 1-16 text editor use 3-2

DROP instruction 4-4

DS instruction 4-4

DSD environment application builder DSDs 5-13 default DSDs 1-14 definition 2-2 macro assembler DSDs 4-1 overriding DSDs 2-2 required DSDs 1-14 statement function 2-6 text editor DSDs 3-5 using job control statements to establish 1-3 work data sets 1-15

DSECT instruction 4-4 dummy control section 4-4 editor commands capabilities 1-4 summary of 3-6

X-2 GC34-0121 editor workspace 3-1

EJECT instruction 4-4 end, macro definition 4-6 end command (END) 3-6

END instruction 4-4

ENTR Y instruction 4-4

ENTRY statement for absolute load module 5-3 for composite module 5-8 environment lists

DSD environment 2-2 example 1-3,1-12,2-3 function and use of 1-16 overriding DSD 2-2 purpose 1-2

ENVL parameter

ASMGO example 2-3 example 1-4 use of 2-2

EOF statement 2-6

EOJ statement 2-6

EOS statement 2-6

EQU instruction 4-4

EQUR instruction 4-4 error message generation, assembler 4-6

ESD (external symbol dictionary) 5-6

ESD/NOESD listing option 4-9

EXCOND statement 5-10

EXEC control statement example of use 2-1 function 2-6 executing the subsystem programs 1-13 execution environments other than Realtime Programming System 1-10 application build requirements 5-2 phase 1 processing 5-3

Realtime Programming System 1-7 application build requirements 5-3 phase 1 processing 5-6 phase 2 processing 5-8 phase 3 processing 5-11 exit, macro definition 4-6 external reference resolution phase 1 5-7 phase 3 5-12 external symbol dictionary listing option 4-9 external symbols, identifying 4-4

EXTRN instruction 4-4 features summary application builder 5-15 job stream processor 2-7 macro assembler 4-10 text editor 3-7 find command (PI) 3-6

FORMAT statement for absolute load module 5-3 for composite module 5-8 formatting capabilities, text editor 3-3

FORTGO statement 2-3

FULLXREF option 4-9

(

\

" J

o

GBLA instruction 4-6

GBLB instruction 4-6

GBLC instruction 4-6 generation program 1-18 get command (GE) 3-6 global control section 4-4 global variables 4-6

GLOBL instruction 4-4 hardware configuration specifications A-I minimum hardware configuration 1-16 optional hardware supported 1-17 hardware instructions 4-3 header, macro definition 4-6 heading, assembly listing 4-4 c

ICTL instruction 4-4

INCLUDE statement for absolute load module 5-3 for composite module 5-8 increment, line number 3-2 indentation levels, text editor 3-4 initiating control section 4-4 input stream

see job input stream insert command (IN) 3-6 inserting blank lines (assembly listing) 4-4 installation requirements A-I installing the subsystem programs 1-18

INSTREAM device 1-14 interactive text editing 3-2 invoking and executing the subsystem programs 1-13 invoking the application builder 5-13

IPL bootstrap loader 5-3

ISEQ instruction 4-4 job accounting A-3 job input stream definition 1-1 example 1-3,2-2

JOB statement 2-6 job stream processor compile, load, and go 2-3 data set definition statements 2-2

DSD environment 2-2 environment lists 2-2 functions 1-2 in program preparation 1-8 input stream source to use 2-6 job input stream 1-1 jobs and steps 2-1 redirecting the input stream 2-5 sources of the input stream 2-5 starting 2-1 summary of control statements 2-6 summary of features 2-7 user input data 2-4

JSPWORK data set 1-14 o

LCLA instruction 4-6

LCLB instruction 4-6

LCLC instruction 4-6 library, autocall in application builder processing in phase 3 processing 5 -11 purpose 5-5 library, task set 5-3 library, using Series/l B-1

LIBl, LIB2 data sets 4-1 line display range 3-3 line format command (LF) 3-6

1-6 line length 3-3 line wraparound 3-3

LINECOUNT option 4-9 lines and line numbers 3-2 linkage symbols 4-8 list command (LI), text editor 3-6

LIST/NOLIST option, assembler 4-9

LIST option, application builder 5-14 listing, assembler 4-9 listing options, application builder 5-14 listings, phase 1 5-7 listings, printing assembly 4-4

LMODOUT data set 5-13 loader, disk IPL bootstrap 1-10

LOADI-LOAD5 data sets 5-13 local variables 4-6 location counter setting 4-4 loop counter, conditional assembly 4-6 machine instructions 4-3 macro assembler assembler instructions 4-3 assembler language 4-3 assembler program 4-1 coding features 4-7 defining assembler data sets 4-1 functions 1-5 in program preparation 1-8 invoking the assembler 4-2 machine instructions 4-3 macro instructions 4-5 processing 4-2 purpose 1-5 summary of features 4-10 macro definitions 4-5

MACRO instruction 4-6 macro instructions definition of 4-5 summary of 4-6 macro name 4-6

MACRO/NOMACRO option 4-9 macro processing option 4-9 macros, structured 4-9

MAP option 5-14

MEND instruction 4-6 message data set space A-I

MEXIT instruction 4-6 minimum hardware configuration 1-16

MNOTE instruction 4-6

Index X-3

move command (MO) 3-6

MSGLOG device job stream processor use 1-14 text editor use 3-5

NAME statement for absolute load module 5-3 for composite module 5-8 no-operation instruction 4-6

NOESD option 4-9

NOEXEC statement 2-6

NOLIST option 4-9

NOMACRO option 4-9 noninteractive text editing 3-2

NOOBJECT option 4-9

NORLD option 4-9

NOTEXT option 4-9

NOXREF option 4-9 object module creating 1-5 definition 1-5 input to phase 1 5-6 output of language translator 5-1 relocatable 4-7

OBJECT/NOOBJECT option 4-9 object program listing 4-9

OBJOUT data set 4-1 operator station as input stream source 2-5 in hardware configuration 1-16 options application builder 5-14 assembler 4-9

ORG instruction 4-4 origin address, load module 5-3 overlay area 5-5 overlay processing 5-12

OVERLAY statement 5-8 overlay structure 5-3 overriding DSDs 2-2 parameter passing see PARM statement

PARM statement for application builder options 5-14 for assembler options 4-9 function 2-6 partition, batch 1-13 partition storage organization 5-4

PARTN statement 5-12

PBMDS data set 5-13 permanent data sets 2-2 phase 1, application builder control statements 5-8 functions performed 5-7 object module input 5-6 output 5-7 phase 2, application builder control module 5-8 control statements 5-10 prebind module 5-9 processing 5-9

X-4 GC34-0121 phase 3, application builder control statements 5 -12 processing 5-12

PHASE1 statement 5-8

PHASE2 statement 5-10

PHASE3 statement 5-12

PLl GO statement 2-3

POP instruction 4-4 prebind module control statements 5-10 crea ting 5 -9 definition 5-2 functions 5-9 purpose 1-6

PREF instruction 4-4 preserving editing sessions 3-4 primary segment, resident 5-5

PRINT device application builder use 5-13 assembler use 4-1 job stream processor use 1-14 text editor use 3-5 printer requirements A-3 printing assembly listing 4-4 problem solving with compile, load, and go 1-12 processing options, application builder 5-14 program preparation facilities application builder 1-6 macro assembler 1-5 text editor 1-4 program residency space (subsystem) A-I program section types

COM 4-8

DSECT 4-8

GLOBL 4-8

STAR T or CSECT 4-8 program sections 4-7 programming requirements (subsystem) A-3 prototype name 4-6 ptn parameter 1-13

PUSH instruction 4-4 qprty parameters 1-13

QUEUE statement 5-10 queues, predefining 5-9 queuing priority 1-13 realtime programming system compatibilities A-4 defining data sets 2-2 execution environment 5-3 hardware configuration 1-16 in Series/l software system 1-1 in subsystem installation process relation to subsystem 1-13 task set execution under 1-6 register symbol definition 4-4 register use 4-7 relocatable format 5-6 relocatable object modules 4-7 relocation dictionary listing 4-8 representing data 4-7 reserving storage area 4-4

1-18 c

(

, i

" c

o resident library subroutines 5-5 resident primary segment 5-5 resident secondary segment 5-5 resolving external references 5-12 resource allocation 1-3 restarting an editing session 3-4 retrieving text

see get command return codes 2-1

RLD (relocation list dictionary) 5-6

RLD/NORLD option 4-9

• c sample hardware configurations 1-17 save command (SA) 3-6 searching for text see find command secondary segment, resident 5-5 sections, program 4-8 segment, resident primary 5-5 segment, resident secondary 5-5 sensor I/O support 1-17 sensor I/O used by task set 5-10 sequence-checking source statements 4-4

SET A instruction 4-6

SETB instruction 4-6

SETC instruction 4-6 setting tabs 3-4

SHARING statement 5-10 simple structured task set 5-3

SIO statement 5-10

SOURCIN data set 4-1

SP ACE instruction 4-4

SPOOL volume

SPOOL DSD 1-15 spooling example 2-4

START instruction 4-8 starter system A-I starting the job stream processor 1-13 stopping assembly processing 4-4 stopping job stream processor 2-1 storage requirements A-I structured macros 4-9

STS option 5-14 summary of features application builder 5-15 job stream processor 2-7 macro assembler 4-10 text editor 3-7 suppress printing options 4-10 switching source of input stream 2-5 symbol use 4-7 symbolic linkages 4-8

SYSLOG device application builder use 5-13 assembler use 4-1 text editor use 3-5

SYSP ARM option 4-9 system and partition storage organization 5-4 system global 4-8 system scheduler table 5-9 o tab character 3-4 tab command (T A) 3-6 tab feature 3-4 tailoring an editing session 3-3 task set creating 1-6,1-7,5-11 defining contents and structure 5-12 definition 5-2 library 5-3 overlay processing 5 -12 partition information 5-3 simple and complex structures 5-3 system and partition organization 5-4 task set global 4-8 task set load module 5-4 task set start co mmand 1-13

TASK statement 5-10

T ASK SET statement 5-10 temporary data sets 2-2 terminate USING domain 4-4 text editor commands 1-4 defining editor data sets 3-5 functions 3-1 in program preparation 1-8 interactive and noninteractive use 3-2 invoking the editor 3-5 line display range 3-3 line length 3-3 lines and line numbers 3-2 preserving an editing session 3-4 setting tabs 3-4 summary of editor commands 3-6 summary of editor features 3-7

TEXT /NOTEXT option 4-9 timer requirements A-2

TITLE instruction 4-4 translating, building, executing 2-3

TSLIB volume 5-13

TSLOAD data set 5-13

TSOVLYdataset 5-13 in application builder processing 5-13 in assembler processing 4-1

TSRTDS data set 5-13

TSSHARE data set 5-13 unconditional branch 4-6

USING instruction 4-4 using the Series/1 software library B-1 utilities

DEFINE 2-2

DISK IPL bootstrap loader 1-10 used with subsystem 1-2 variable symbols 4-6 work data sets disk space A-2 for application builder 5-13

Index X-5

work data sets (continued) for job stream processor 1-14 for macro assembler 4-1 for text editor 3-5 general information allocating workspaces 1-15

DSD statements 1-15 maximizing workspace efficiency 1-15

WORKVOL volume application builder use 5-13 assembler use 4-1 general information 1-15 text editor use 3-5

WORKl, WORK2, WORK3 see work data sets

WXTRN instruction 4-4

XREF/NOXREF/FULLXREF options 4-9 l c

X-6 GC34-0121

c

Program Preparation Subsystem:

Introduction

GC34-0121-0

YOUR COMMENTS, PLEASE ...

Your comments assist us in improving the usefulness of our publications; they are an important part of the input used in preparing updates to the publications. All comments and suggestions become the property of IBM.

Please do not use this form for technical questions about the system or for requests for additional publications; this only delays the response. Instead, direct your inquiries or requests to your I BM representative or to the I BM branch office serving your locality.

CQi"rections or clarifications needed:

Page Comment

READER'S

COMMENT

FORM

c

()

S

'T1 o

c::

»

5"

:J to

C

:J

CI) o

Please indicate your name and address in the space below if you wish a reply.

Thank you for your cooperation. No postage stamp necessary if mailed in the U.S.A.

(Elsewhere, an IBM office or representative will be happy to forward your comments.)

GC34-0121-0

Your comments, please ...

This manual is part of a library that serves as a reference source for IBM systems.

Your comments on the other side of this form will be carefully reviewed by the persons responsible for writing and publishing this material. All comments and suggestions become the property of IBM.

(")

S

Fold

Fold

Business Reply Mail

No postage stamp necessary if mailed in the U.S.A.

I BM Corporation

Systems Publications, Dept 27T

P.O. Box

1328

Boca Raton, Florida 33432

First Class

Permit 40

Armonk

New York

Fold

Fold

en

'<

.....

(1)

3

"'tJ

a

~

Q)

3

"'tJ

@

~

~

0'

::J en c:

OJ s:: en

~

[

C)

(") w

~

~

~

6 c

en

?>

~

5'

(1) a.

5'

~

a

a. c:

~

0'

::J

t

\.

\. ,

-

-

- -

-

-

- - -

---

®

I nternational Business Machines Corporation

General Systems Division

57750 Glenridge Drive N.E.

P.O. Box 2150, Atlanta, Georgia 30301

(U.S.A. only)

C

·~···

"

Program Preparation Subsystem:

Introduction

GC34-0121-0

YOUR COMMENTS, PLEASE . ..

Your comments assist us in improving the usefulness of our publications; they are an important part of the input used in preparing updates to the publications. All comments and suggestions become the property of IBM.

Please do not use this form for technical questions about the system or for requests for additional publications; this only delays the response. Instead, direct your inquiries or requests to your I BM representative or to the I BM branch office serving your locality.

Cmrections or clarifications needed:

Page Comment

READER'S

COMMENT

FORM

c

(")

So

Please indicate your name and address in the space below if you wish a reply.

Thank you for your cooperation. No postage stamp necessary if mailed in the U.S.A.

(Elsewhere, an IBM office or representative will be happy to forward your comments.)

GC34-0121-0

Your comments, please ...

This manual is part of a library that serves as a reference source for I BM systems.

Your comments on the other side of th is form will be carefu Ily reviewed by the persons responsible for writing and publishing this material. All comments and suggestions become the property of IBM.

(")

S

(1

Fold

Fold

Business Reply Mail

No postage stamp necessary if mailed in the U.S.A.

I BM Corporation

Systems Publications, Dept

27T

P.O.

Box 1328

Boca Raton, Florida 33432

-

-

- - -

- ---

-

-----

®

International Business Machines Corporation

General Systems Division

57750 Glenridge Drive N.E.

P.O. Box 2150, Atlanta, Georgia 30301

(U.S.A. only)

First Class

Permit 40

Armonk

New York

Fold

Fold

"'tI

(3

CQ

OJ

3

"'tI

Cil

'0

~

~

0'

::I

en

c g-

~

(1)

3

0; s::

en

~

[

~

~

(1) c..

:;' c en

~

G)

(") w

.j::o,

6

.....

6

~

(3 c.. c

C')

.....

0'

::I

_. t

,

I

c

-

-

-

- -

-

-

- - -

-

- - ' -

®

International Business Machines Corporation

General Systems Division

57750 Glenr i dge Drive N. E .

P . O . Box 2150

Atlanta , Georgia 30301

(U.S.A. only)

GC34-0121-0

t

(3 a. c:

~ o

·

:l

C)

r-J

(') w

~

6

6

~

~

(I) a.

5 ' c en

?>

3

~

(I)

'0

III o·

:l

en

c:

0'

~

(I)

3

[D s:

en

!!l

~

'll

(3 cc

Ql t