SC34 0638 0_EDX_5.0_Communications_Guide_Dec84 0 EDX 5.0 Communications Guide Dec84
SC34-0638-0_EDX_5.0_Communications_Guide_Dec84 SC34-0638-0_EDX_5.0_Communications_Guide_Dec84
User Manual: SC34-0638-0_EDX_5.0_Communications_Guide_Dec84
Open the PDF directly: View PDF 
.
Page Count: 274
| Download | |
| Open PDF In Browser | View PDF |
-- ---
-- --- - ----------_
.-
Series/1
•
SC34-0638-0
Event Driven Executive
Communications Guide
Version 5.0
Library Guide and
Common Index
Installation and
System Generation
Guide
Operator Commands
and
Utilities Reference
SC34·0645
SC34-0646
SC34-0644
Language
Reference
Communications
Guide
Messages and
Codes
SC34-0643
SC34-0638
SC34'()636
Operation Guide
Event Driven
Language
Programming Guide
Reference
Cards
SC34-0642
SC34-0637
SBOF-1625
Problem
Determination
Guide
Customization
Guide
Internal
Design
SC34-0639
SC34-0635
LY34.()354
--..-- --- . --- ---- - --
----
Series/1
-~-,-
SC34-0638-0
Event Driven Executive
Communications Guide
Version 5.0
c
Communications
Guide
SC34-0638
o
o
First Edition (December 1984)
This is a revision of, and obsoletes, SC34-0443-0.
Use this publication only for the purposes stated in the following section, "About
This Book."
Changes are made periodically to the information herein; any such changes will be
reported in subsequent revisions or Technical Newsletters.
This material may contain reference to, or information about, IBM products
(machines and programs), programming, or services that are not announced in your
country. Such references or information must not be construed to mean that IBM
intends to announce such IBM products, programming, or services in your country.
Publications are not stocked at the address given below. Requests for copies of IBM
publications should be made to your IBM representative or the IBM branch office
serving your locality.
This publication could contain technicalJDaccuracies or typographical errors. A form
for readers' comments is provided at the back of this publication. If the form has
been removed, address your comments to IBM Corporation, Information
Development, Department 28B, P. O. Box 1328, Boca Raton, Florida 33432. IBM
may use or distribute any of the information you supply in any way it believes
appropriate without incurring any obligation whatever. You may, of course, continue
to use the information you supply.
© Copyright International Business Machines Corporation 1983
o
0 ',
"I
Summary of Changes for Version 5
The only changes made to this document for Version 5 are miscellaneous editorial
enhancements.
o
c
Summary of Changes for Version 5
iii
o
o
iv
SC34-0638
o
About This Book
The information in the Communications Guide pertains to the Event Driven Executive
Version 5, modification level O. The book describes the use of various forms of data
communications that are available with Series/ I and the Event Driven Executive. It covers
several methods of Binary Synchronous Communications (BSC), operation of a host system
with a Series/I, communications between two Series/Is, and communications between Series/I
and multiple peripheral devices. It tells the reader how to prepare for data communications
operations, how to use Event Driven Language (EDL) instructions to perform communications
functions, and how to use Event Driven Executive communications utilities.
o
In conjunction with the Communications Guide, the following books provide information to help
perform data communications:
Language Reference provides syntax and descriptions of EDL instructions.
•
Messages and Codes lists the error messages and codes issued for communications.
•
Operator Commands and Utilities Reference provides information on the use of
communications utilities.
Audience
Readers of the Communications Guide should have the following:
Knowledge of data communications concepts in general
Experience in communications programming for either IBM or non-IBM products
o
About This Book
v
o
Contacting IBM about Problems
You can inform IBM of any inaccuracies or problems you find when using this book by
completing and mailing the Reader's Comment Form provided in the back of the book.
If you have a problem with the Series/l Event Driven Executive services, fill out an authorized
program analysis report (APAR) form as described in the IBM Series/l Software Service Guide,
GC34-0099.
o
o
About This Book
vii
o
o
viii
SC34-0638
o
Contents
Introduction to Communications Guide CO-l
Part 1. Binary Synchronous Communications CO-3
Chapter 1. Binary Synchronous Communications Access Method (BSCAM) CO-5
Terms Used in this Chapter CO-6
Planning for BSCAM Operations CO-6
U sing Data Links CO-7
Selecting HSC Line Connection Types CO-7
Meeting Hardware Requirements CO-8
Including BSCAM Support in the Supervisor CO-12
Selecting Type of Data to Transmit CO-14
Selecting Mode of Transmission CO-IS
Programming for BSCAM Applications CO-16
Basic Programming Functions for BSCAM CO-16
Acquiring Use of a BSC Line CO-17
Coding Control Block for Read and Write Operations CO-17
Sending Data CO-19
Receiving Data CO-26
Providing for Errors During BSCAM Operations CO-29
BSCAM Sample Programs CO-29
WRITE Sample Program CO-29
READ Sample Program CO-31
Interacting with BSCAM (Using BSC Utilities) CO-32
Tracing I/O Activities on a BSC Line (Using $BSCTRCE) CO-33
Formatting Trace Files for Print or Display (Using $BSCUTl) CO-34
Testing BSCAM Operations (Using $BSCUT2) CO-38
Monitoring BSC Lines with the Communications Indicator Panel CO-4S
o
Contents
ix
Contents
Using X.2l Switched Network Support CO-48
Attaching and Jumpering the 2080 Card CO-48
System Generation for X.2l Support CO-48
The $$X2lDS Connection Record Data Set CO-49
Convert BSC Program for X.2l CO-51
X.2l Error and Call Progress Signal Logging CO-52
o
Chapter 2. Remote Management Utility ($RMU) CO-57
Planning for the Remote Management Utility Operations CO-59
Types of Line Connections CO-59
Mode of Transmission CO-60
Storage Considerations CO-60
Remote System Requirements CO-60
Host System Requirements CO-6l
Remote Management Utility Defaults CO-62
Host Programming for the $RMU Application CO-66
Using Event Driven Language BSC Instructions CO-66
Receiving $RMU's Responses to Host Requests CO-67
Coding the Required Field for Requests to $RMU CO-70
Managing Disk/Diskette Data Sets CO-70
Controlling Data Transfers between Host and Remote Systems CO-78
Remote System Echoing Host Data (WRAP) CO-84
Controlling Program Execution on the Remote System CO-86
Verifying Identities between Systems (IDCHECK) CO-94
Interacting Between Host and Remote Systems (PASSTHRU) CO-96
Considerations for Using PASSTHRU CO-96
Establishing a PASSTHRU Session CO-99
Conducting a P ASSTHR U Session CO-l02
PASSTHRU Record Types CO-l04
P ASSTHRU Blocking CO-l08
Sample Programs CO-l09
Multifunction Program CO-l09
RECEIVE Sample Program CO-Ill
SEND Sample Program CO-lIS
PASSTHRU Sample Program CO-117
Example of Conducting a PASSTHRU Session CO-125
Chapter 3. Host Communications Facility CO-127
Planning to Use the Host Communications Facility CO-128
Installation Requirements CO-128
Host Data Sets CO-128
Opening Host Data Sets CO-130
System Status Data Set CO-130
Host Storage CO-132
Data Transfer Rates CO-132
Tasks Common to Programming and Using $HCFUTI CO-132
Programming for the Host Communications Facility Application CO-132
Event Driven Language Instruction Set CO-132
o
x
SC34-0638
o
Controlling Data Transfers between Series/l and Host CO-133
Submitting Background Jobs to the Host CO-135
Performing Status Functions CO-135
Obtaining Time and Date from the Host CO-136
Sample Programs CO-136
Sample Program to Receive a Host Data Set CO-138
Interacting with the Host Communication Facility ($HCFUTl) CO-139
Transferring Host Data to Series/l CO-139
Performing Status Functions CO-141
Submitting Jobs to the Host Job Stream CO-141
Sending Data to the Host CO-141
Part 2. Channel Attach CO-143
o
Chapter 4. Channel Attach Program CO-145
Planning for the Channel Attach Application CO-145
Channel Attach Program ($CAPGM) CO-145
Channel Attach Device (4993) CO-146
Software Considerations CO-146
Hardware Considerations CO-146
Tailoring the Channel Attach Program CO-147
Powering On The Channel Attach Device CO-148
Programming for the Channel Attach Application CO-148
Event Driven Executive Instruction Set CO-148
Detecting and Handling Errors CO-149
BT AM Considerations CO-149
Assembling the Application Program CO-150
Link-Editing the Application Program CO-150
Starting a Channel Attach Device CO-151
Opening a Channel Attach Port CO-152
Coding the Control Block for a Channel Attach Port CO-152
Issuing I/O CO-152
Closing a Channel Attach Port (CACLOSE) CO-154
Stopping the Channel Attach Device (CASTOP) CO-154
Tracing Series/1 I/O during Channel Attach (CATRACE) CO-155
Printing Channel Attach Trace Data (CAPRINT) CO-155
Interacting with Channel Attach (Using $CHANUT1 Utility) CO-155
$CHANUTI Commands CO-155
Channel Attach Sample Programs CO-157
Configuration Requirements for Sample Programs CO-157
General Guide for Execution of Sample Programs CO-158
Host Sample Program CO-165
Part 3. Specialized Series/1 Event Driven Executive Communications
Methods CO-173
Chapter 5. Series/l-to-Series/l Attachment Support CO-175
o
Contents
xi
Contents
o
Planning the Series/1-to-Series/1 Application CO-175
Processor Relationships CO-176
Initiating Data Transfers CO-176
Responding to External Events CO-176
Programming for Series/ 1-to-Series/ 1 Attachment CO-179
Event Driven Language Instruction Set CO-179
Basic Programming Tasks CO-179
Programming Considerations CO-181
Programming Examples CO-183
Interacting with the Series/1-to-Series/1 Attachment (Using $SlSlUTl) CO-194
Chapter 6. General Purpose Interface Bus - IEEE Standard 488-1975 CO-199
Planning for the GPIB Application CO-199
System Generation for GPIB CO-199
Relationship between Series/land GPIB Devices CO-200
Assigning Device Addresses CO-200
Initializing and Configuring the Bus CO-201
Programming for the GPIB Application CO-203
Event Driven Language Instruction Set CO-203
Programming Considerations CO-204
Coding GPIB Functions CO-212
GPIB Sample Program CO-216
Interacting with the GPIB Application (Using $GPIBUTl) CO-220
Debugging Applications with $GPIBUT1 CO-227
$GPIBUT1 Utility Example CO-228
Detecting Errors During GPIB Operations CO-233
Examining Interrupt Status Byte CO-233
Examining Cycle Steal Status Block CO-234
Retrieving Cycle Steal Status CO-234
Retrieving Residual Status Block CO-235
Glossary of Terms and Abbreviations CO-237
Index CO-247
xii
SC34-0638
r,;1--~"I
-'--.J
Figures
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.
24.
25.
26.
27.
28.
29.
30.
31.
32.
33.
34.
35.
36.
Specifying BSCLINE TYPE= Operand CO-13
Event Driven Language BSC Instructions CO-16
Example of Coding BSCOPEN and BSCCLOSE Instructions CO-17
Example of Coding BSCIOCB Instruction CO-18
Buffers Required for Write Operations CO-18
Buffers Required for Read Operations CO-19
Initial Write Types CO-20
Control Character Flow for Initial Write Instructions CO-21
Control Character Flow for Initial Conversational Write Instructions CO-21
Control Character Flow for Initial Transparent Write Instructions CO-21
Control Character Flow for Initial Transparent Block Write Instructions CO-22
Control Character Flow for Initial Conversational Transparent Write Instructions CO-22
Continue Write Types CO-23
Control Character Flow for Continue Write Instructions CO-23
Special Write Types CO-24
Control Character Flow for Special Write Type Instructions CO-25
Programming Sequences for Sending Data CO-26
Read Types CO-27
Dumping Trace File Records CO-35
Dump of the LAST RECORD of Trace File CO-36
Trace Record Fields CO-37
Communications Indicator Panel CO-47
Mapping Procedures for BSC X.21 Circuit Switched Support CO-49
Connection Record Format Fields CO-50
X.21 BSCOPEN Coding Example CO-51
Example of the X.21 Printed Log Information for a Read Error CO-52
Example of the X.21 Printed Log Information for a Device Error CO-54
Device Error Codes CO-55
Call Progress Signal Counter Usage CO-56
Communication Between Host and Remote Systems CO-59
$RMU Status Failure Codes CO-68
Required Fields for ALLOCATE Request CO-72
Communications Flow for ALLOCATE CO-74
Required Fields for DELETE Request CO-75
Communications Flow for DELETE CO-76
Required Fields for DUMP Request CO-77
o
Figures
xiii
Figures
o
37. Communications Flow for DUMP CO-78
38. Required Fields for RECEIVE Request CO-80
39. Communications Flow for RECEIVE CO-8l
40. Required Fields for SEND Request CO-83
41. Communications Flow for SEND Request CO-84
42. Required Fields for WRAP Request CO-85
43. Communications Flow for WRAP CO-86
44. Required Fields for EXEC Request CO-88
45:' -Communications Flow for EXEC CO-90
46. Required Fields for SHUTDOWN Request CO-92
47. Communications Flow for SHUTDOWN CO-94
48. Required Fields for IDCHECK Request CO-95
49. Communications Flow for IDCHECK CO-95
50. Required Fields for PASSTHRU Request CO-99
51. Communications Flow for PASSTHRU CO-1Ol
52. Example of PASSTHRU Records Received by Host CO-l07
53. Multifunction Sample Program CO-l09
53. $RMU Multifunction Program CO-l09
54. RECEIVE Sample Program CO-Ill
54. RECEIVE Sample Program CO-Ill
55. SEND Sample Program CO-115
56. PASSTHRU Sample Program CO-118
57. Example of Conducting a PASSTHRU Session CO-125
58. EDL TP Instructions CO-133
59. System Status Data Set Sample Program CO-136
60. Sample Program to Send Data Set to the Host CO-137
61. Sample Program to Receive a Host Data Set CO-138
62. $HCFUTI Commands CO-139
63. Listing of USERPGM Data Set CO-lSI
64. Series/l Sample Program CO-159
65. Host Sample Program CO-165
66. Program for Posting an Event Control Block CO-l77
67. EDL Instructions for Communication between Series/Is CO-179
68. TERMCTRL Functions for Series/l-to-Series/l Communications CO-180
69. Usage of READTEXT/PRINTEXT without Direct I/O CO-182
70. Primary Processor Sample Program CO-184
71. Secondary Processor Sample Program CO-188
72. Synchronization Sample Program CO-l92
73. Listen and Talk Addresses for GPIB Devices CO-20l
74. GPIB Sample Program CO-2l6
75. GPIB Utility Example CO-228
xiv
SC34-0638
(---~\
\",-:~
Introduction to Communications Guide
The Communications Guide discusses the data communications methods that are available as
part of the Event Driven Executive system, and in conjunction with Installed User Programs
(IUPs).
"Part 1. Binary Synchronous Communications" on page CO-3 covers three methods of
communications that use binary synchronous protocol:
Binary Synchronous Communications Access Method (BSCAM)
Remote Management Utility ($RMU)
•
Host Communications Facility (HCF)
"Part 2. Channel Attach" on page CO-143 discusses communications between the Series/l and
a larger host system.
"Part 3. Specialized Series/l Event Driven Executive Communications Methods" on page
CO-173 covers two methods of communications unique to Series/l under the Event Driven
Executive:
•
Series/ I-to-Series/ 1 Attachment
•
General Purpose Interface Bus (GPIB)
o
Introduction to Communications Guide
CO-l
In addition to the methods mentioned above, several licensed programs offer forms of
communications with the Event Driven Executive:
o
Multiple Terminal Manager
Systems Network Architecture/Synchronous Data Link Control
Communications Facility
Licensed programs can be purchased separately from the basic system, along with
documentation on their use.
~-'''''\'
I
"oC::'
co- 2
SC34-0638
o
Part 1. Binary Synchronous Communications
Part 1 covers the following forms of binary synchronous communications:
Binary Synchronous Communications Access Method (BSCAM)
o
•
Remote Management Utility ($RMU)
•
Host Communications Facility (HCF)
o
Part 1. Binary Synchronous Communications
CO-3
Notes
o
o
CO-4
SC34-0638
Chapter 1. Binary Synchronous
Communications Access Method (BSCAM)
o
The Binary Synchronous Communications Access Method (BSCAM) provides I/O access at a
read/ write level using a BSC protocol similar to that of BTAM. It allows the Series/Ito
communicate with local and remote processors and terminals. The BSCAM access method is
also the basis for the Remote Management Utility ($RMU), which runs on the Series/l and
allows it to be controlled by a host system. $RMU is discussed in Chapter 2, "Remote
Management Utility ($RMU)" on page CO-57.
BSCAM supports the attachment of multiple BSC lines to the Series/I. Data can be either
transparent or nontransparent. Stations acknowledge transmissions either with standard BSC
control characters or with conversational responses. The transmission code that BSCAM uses is
EBCDIC.
Hardware features and BSC protocol that BSCAM does not support are:
ASCII mode
Leading graphics support
Transparent ITB and ENQ transmission.
BSCAM provides I/O at the READ/WRITE access level. It does not insert or delete control
character sequences from the data you place in your buffers. When sending data, you must
place the proper start and end-of-transmission control characters (STX, DLE STX, and ETX) in
your output buffer. The only case in which you must not place characters in your output buffer
is when you are sending the transparent end-of-transmission and end-of-block (DLE ETX and
DLE ETB) sequences. Do not place these control characters in your buffer. When you receive
data, your input buffer will contain all the control characters that it received in the transmission.
o
Chapter 1. Binary Synchronous Communications Access Method (BSCAM)
CO-5
Binary Synchronous Communications Access Method
(BSCAM)
For a general introduction to binary synchronous communications and details of line protocol
used by the Event Driven Executive, refer to General Information - Binary Synchronous
Communications, GA27-3004.
Application programs that run under BSCAM consist of special Event Driven Language BSC
instructions. These programs send and receive data from one or more stations. In addition,
several BSC utilities check the way BSCAM is working by monitoring and simulating its
operations.
This chapter tells how to:
•
Plan to use BSCAM.
•
Write application programs with the special set of BSC instructions.
Use the BSC utilities to check for potential problems.
Use the X.21 digital communications capabilities.
Terms Used in this Chapter
Below are some definitions of terms used throughout this chapter.
The computers that are communicating are called stations.
The data records sent and received are called messages.
The station sending messages (writing) is called the sending or transmitting station.
The station receiving messages (reading) is called the receiving station.
Planning for BSCAM Operations
Before you can begin to use BSCAM, your system must have certain hardware and software
support. The combination of support on your system determines the type of programs you
should write and the way you can use BSCAM.
CO-6
SC34-0638
o
o
Planning for BSCAM Operations (continued)
The sections that follow will help you to:
Select the hardware and software you need to use BSCAM and define the support during
system generation.
Determine what hardware and software your system already supports, if system generation
has already been done.
Decide which of the BSCAM features you will use.
Using Data Links
BSCAM supports transmission over switched and nonswitched (leased) data links. The data
link is the line provided by a common carrier over which data is transmitted from your station to
another station. BSCAM supports half-duplex transmission only.
Only remote connections between stations need a data link. (Local connections use
direct-connect.) If you plan to communicate with a remote station, make sure your system is
linked to either a switched or a nonswitched line.
Selecting BSC Line Connection Types
o
One of the most important things you must decide about a BSC line is the type of station it will
function as. BSCAM supports connection of multiple BSC lines to a Series/I. Think of each
BSC line as a separate physical entity, functioning independently of the others. As far as each
BSC line knows, it has an exclusive connection with the Series/I. One BSC line may function
as a point-to-point station communicating over a switched data link. Another line (installed on
the same processor) may function as a multipoint tributary on a leased link. Still another may
be a multipoint control station.
Every BSC line that you have attached to your Series/1 can form one of several types of
connection with the processor. Select the type of connection you want to establish for each
BSC line on Series/I. Then refer to "Defining a BSC Line to the Supervisor" on page CO-12
for details on defining your selections to the system. If system generation has already been
done, use the $IOTEST utility LS (list supervisor configuration) command to determine the
assignment of each BSC line.
The type of connection each BSC line forms with your Series/1 affects the way you program
that line to send and receive data.
Point-to-Point Connection
If a BSC line forms a point-to-point connection with your Series/I, it will handle
communications between your processor and one other station. The connection between the
two stations can be either local or remote. In remote connections, the data link can be either
switched or leased. Local connections use a direct connection. In a point-to-point connection,
each station contends with equal priority for the right to send data across the line.
o
Chapter 1. Binary Synchronous Communications Access Method (BSCAM)
CO-7
Binary Synchronous Communications Access Method
(BSCAM)
Planning for BSCAM Operations (continued)
o
Multipoint Connection
If a BSC line forms a multipoint connection with your Series/I, it handles communications
between your processor and one or more other stations. You can designate your Series/Ito act
either as the control station or as a tributary station in the multipoint connection.
A control station is in charge of which of the multiple stations has the right to transmit at any
given time. It governs the other stations by polling (asking the tributary if it is ready to send
data) and selecting (asking the tributary if it is ready to receive data). The tributary has direct
communication only with the control station, and then only when the control station polls or
selects it. To send data to another tributary that is under the same control station, the first
tributary sends the data directly to the control station, which in turn sends it to the specified
tributary.
For more information on polling and selecting, refer to the section "Sending Poll/Select
Sequences" on page CO-20.
Note: The hardware does not use the correct selection sequence if you specify cluster addresses
'C1' and '50' for a device emulating a 3270 on a BSC line.
Meeting Hardware Requirements
Before you can actually use BSCAM to communicate with other stations, you must ensure that
the following hardware is installed on your Series/I:
•
BSC lines are attached with control provided for each of them.
Modem or modem eliminator is attached to the BSC line(s) (if applicable).
The attachment (physical connection) and control (interface with BSCAM) of a BSC line can
be provided by one of several Series/1 communications features. These features are actually
hardware cards installed in the processor or I/O expansion unit of your Series/I. Some types of
cards attach a single BSC line to the Series/I, while other cards can attach multiple lines.
Determining Existing Hardware Configuration and BSC Line Addresses
To determine the hardware address and feature type of each communications card already
installed on your system, load the $IOTEST utility, and issue the LD (List Devices) command.
To determine the address of each BSC line defined to the supervisor, again use $IOTEST and
issue the LS (List Supervisor Configuration) command.
o
CO-8
SC34-0638
o
Planning for BSCAM Operations (continued)
Series/1 Communications Features
Here is a list of the communications features that control and attach BSC lines to the Series/1.
For details on the functional characteristics and installation of these features, refer to the IBM
Series/l Binary Synchronous Communications Feature Description, GA34-0244.
IBM 2074 BSC Single-Line Control, Medium Speed: This communications feature card
makes the physical connection of one BSC line to the Series/1. It also provides control of the
line. You can use this feature for BSC lines that you will use to form either point-to-point or
multipoint connections. The point-to-point connections can be either local or remote; for
remote operation, the data link can be either switched or leased. Multipoint connections must
use a leased data link. For details on the functional characteristics and installation of this card,
refer to the IBM Series/l Binary Synchronous Communications Feature Description,
GA34-0244.
The single-line control feature requires an electrical interface compatible with RS-232C (CCITT
V.24). Its maximum data transfer rate is 9600 bits per second. In addition, it supports the
following calling features: manual call, manual answer, and automatic answer (the last feature
applies to switched connections only). The single-line control allows IPL from another system
through use of its BSC line.
o
IBM 2075 BSC Single-Line Control, High Speed: This communications feature card
attaches and controls one BSC line. Its characteristics are similar to the medium-speed control
(2074) described above, but with the following differences:
It is for use in remote operations only, since it has no internal clocking and, therefore,
cannot be used in direct connections.
It operates in point-to-point leased and multipoint connections.
It requires a Western Electric 303 modem (or equivalent), or an electrical interface
compatible with CCITT V.35.
Its maximum data transfer rate is 56K bits per second.
For details on the functional characteristics and installation of this card, refer to the IBM
Series/l Binary Synchronous Communications Feature Description, GA34-0244.
o
Chapter 1. Binary Synchronous Communications Access Method (BSCAM)
CO-9
Binary Synchronous Communications Access Method
(BSCAM)
Planning for BSCAM Operations (continued)
o
IBM 2080 Synchronous Communications Single-Line Control, High Speed: This
communications feature card attaches and controls one BSC line. It is required if you want
X.21 digital data communications capabilities for your Series/I. It has the following
characteristics:
•
It operates in point-to-point connections only for BSC switched mode and point-to-point
and multipoint for BSC leased mode.
•
It can be jumpered for switched or leased mode.
•
It requires an electrical interface compatible with CCITT V.35 (leased) or an X.21 electrical
interface (switched or leased).
•
Its maximum data transfer rate is 48K bits per second.
For details on the functional characteristics and installation of this card, refer to the IBM
Series/l Synchronous Communication Single-Line Control Attachment Feature Description,
GA34-0241.
IBM 2093/2094 BSC 8-Line Control and BSC 4-Line Adapter(s): These features,
used together, can attach and control up to 8 BSC lines. The 8-line control is for use with one
or two 4-line adapters (which provide only attachment of lines). The characteristics of these
features are similar to those of the BSC Single-Line Control.
/,-'-~,
<,j
For details on the functional characteristics and installation of this card, refer to the IBM
Series/l Binary Synchronous Communications Feature Description, GA34-0244.
IBM 1310 Multifunction Attachment: This feature can attach one BSC line to the
Series/l and conforms to RS-232C interface standards. The use of this feature requires special
system definitions during system generation for your Series/I.
For details on the functional characteristics and installation of this card, refer to the IBM
Series/l Multifunction Attachment Feature and 4975 Printer Description, GA34-0144.
o
CO-I0
SC34-0638
o
Planning for BSCAM Operations (continued)
IBM RPQ 002349 Direct BSe Attachment: This feature controls the serial transfer of
data to and from remote terminals or systems using direct-connect cabling for half-duplex,
single-line capability. It has the following characteristics (for more information, refer to IBM
Series/l Direct Binary Synchronous Communication Attachment RPQ D02349 Custom Feature,
GA34-I577:
•
It conforms to EIA RS-422 electrical interface standards.
Data transmission is serial-by-bit using BSC transmission method.
It can be used as either a primary or a secondary station.
It is able to send and receive transparent data for EBCDIC only.
Its maximum data transfer rate is 38,400 bits per second if you jumper for internal clocking
and 56,000 bits per second if you jumper for data terminal equipment clocking to another
system.
Special Considerations for Multipoint Tributary Stations
If you plan to use a BSC line as a multipoint tributary station, you must ensure that its feature
card is jumpered with DTR (data terminal ready) permanently enabled. This means that the
electrical interface or modem always leaves the line open to receiving data from its multipoint
control station.
Special Considerations for Local (Direct Connect) Operation
If you are using a Multifunction Attachment card to attach a BSC line to your Series/I, and you
plan to use that line in a local (direct) connection, then you must use a modem eliminator, to act
as the electrical interface in the direct connection. The modem eliminator must meet the
electrical interface requirements of the feature cards to which it connects.
If you are using a single-line, medium speed control or the 8-line control with 4-line adapter,
then you do not need to use a modem eliminator. The direct connection is made between the
communicating lines. However, ensure that internal clocking is jumpered on the card(s) to
provide direct connection.
As stated previously, the 2075 single-line control, high speed feature card cannot be used for
direct connections.
Optional Hardware
The Communications Indicator Panel (model #2000) is an optional piece of hardware that is
useful in program debugging and hardware troubleshooting.
Refer to the section "Monitoring BSC Lines with the Communications Indicator Panel" on
page CO-45 for information on using the panel.
o
Chapter 1. Binary Synchronous Communications Access Method (BSCAM)
CO-II
Binary Synchronous Communications Access Method
(BSCAM)
Planning for BSCAM Operations (continued)
o
Including BSCAM Support in the Supervisor
You must ensure that your supervisor supports the BSC hardware and operation of the BSCAM
access method. This is done during system generation, when you must include a statement to
define each BSC line to the supervisor. You must also include the supervisor module that
supports BSCAM.
Note: For X.21, you must include the BSCX21 module.
The statement that defines BSC lines is called BSCLINE. The supervisor module that includes
BSCAM support is called BSCAM. For step-by step directions on performing system
generation, refer to the Installation and System Generation Guide.
If system generation is already complete, you can find out what the supervisor supports. Load
the $IOTEST utility and issue the LS (List Supervisor Configuration) command.
Defining a BSe Line to the Supervisor
Each BSC line attached to the Series/l needs a BSCLINE statement to define it to the
supervisor. Code the statements in the system definition data set, which defines hardware
support. For each line, you must.define the following:
•
Hardware address (in hexadecimal) of the line
•
Type of connection (point-to-point, multipoint) it is part of
Number of retries before a timeout occurs on the line
•
Communications feature that attaches the line.
Specifying SSC Line Type (TYPE=Operand of SSCLINE): The TYPE= operand of the
BSCLINE statement is where you tell the system what type of station the line functions as.
Here is a list of the available station types and how to code them in a BSCLINE statement.
Note: For a complete mapping of connection types for X.21, see "Using X.21 Switched
Network Support" on page CO-48.
CO-12
SC34-0638
("'(-~\
\0
o
Planning for BSCAM Operations (continued)
Type
Connection
What to code
PT
point-to- point
local
remote (leased)
BSCLINE TYPE=PT
SM
point-to- point
remote (switched)
manual call
BSCLINE TVPE=SM
SA
point-to- point
remote (switched)
automatic answer
BSCLINE TVPE=SA
MC
multipoint
control station
remote (switched)
BSCLINE TVPE=MC
MT
multipoint
tributary station
remote (switched)
BSCLINE TVPE=MT
For X.21 only
AC
pOint-to-point
switched
auto call
BSCLINE TVPE=AC
DC
pOint-to-point
switched
direct call
BSCLINE TVPE=DC
Figure 1. Specifying BSCLINE TYPE= Operand
When a BSC line is attached with a Multifunction Adapter (MFA), you must code the
parameter ADAPTER=MFA in the BSCLINE statement for the line. In addition, you must
code an ADAPTER statement, specifying the address of the line in the ADDRESS= parameter.
Note: The address specified in the BSCLINE and ADAPTER statements must be identical.
Refer to the Installation and System Generation Guide for details on the BSCLINE and
ADAPTER statements.
When a BSC line acts as a Multipoint Tributary Station, you must specify the poll/select
addresses (up to 4) that the line should respond to during polling/selection by its control station.
o
Chapter 1. Binary Synchronous Communications Access Method (BSCAM)
CO-I3
Binary Synchronous Communications Access Method
(BSCAM)
Planning for BSCAM Operations (continued)
o
Defining BSCAM Supervisor Module Support
You must tell the supervisor to support BSCAM operations. During system generation, edit the
link control data set, which defines software support to the supervisor, to include the BSCAM
module.
Note: For X.21, you must include the BSCX21 module.
Refer to the Installation and System Generation Guide for details on defining BSCAM software
support.
Selecting Type of Data to Transmit
You can transmit data in several forms during BSCAM operations. The type of data affects the
way you write programs to send it.
Standard Data (Nontransparent)
When BSCAM transmits nontransparent data, the receiving station interprets the bits according
to the EBCDIC code. If the data contains bit combinations that represent BSC control
characters, the receiving station will recognize and act on the meaning of the characters.
Nontransparent data is commonly used to transmit text. You must be sure that the data you
wish to send does not contain bits that look like BSC control characters. If the data does
contain control characters, the receiving station will not receive the transmission correctly.
Transparent Data
Transparency allows you to transmit data with bit combinations that look like BSC control
characters, without the receiving station interpreting them. It allows you to send raw binary
data regardless of what the data looks like. It also allows you to store control character
sequences in a buffer at the receiving station.
The data-link-escape (DLE) is the control character used to transmit transparent data. The
sequence DLE STX tells the station that is going to receive transparent data, and to ignore any
control characters in the data. The sequence DLE ETX or DLE ETB signals the end of a
transmission of transparent data, and tells the station to begin recognizing control characters
again.
While receiving transparent data, a station will only recognize control character sequences
preceded by the DLE.
o
CO-14
SC34-0638
o
Planning for BSCAM Operations (continued)
Sending Transparent Data in Blocks
You may want to break up a long transmission of transparent data into blocks and send each
separately. Each block of data is checked for transmission errors, and only those blocks not
properly received must be sent again. This is more efficient than sending all the data in one very
long transmission. In that case, if one error occurred, then the entire body of data would have
to be retransmitted, wasting time and tying up resources.
Selecting Mode of Transmission
Transmissions are possible in two different modes under BSCAM.
Standard Transmission Mode
With standard transmission under BSCAM, acknowledgements and responses between stations
consist of predefined BSC control characters which are not stored at the receiving station.
Limited Conversational Response Transmission Mode
o
Under BSCAM, you can transmit control characters or text data in response to a message by
using limited conversational mode of transmission. You can send a conversational response only
as a positive acknowledgement to a complete message (one that ended with ETX or DLE ETX).
You cannot send conversational replies when receiving block messages (ending with DLE ETB
or ETB).
You can begin your conversational reply with either SOH or STX, which the other station
interprets as a positive acknowledgement to its last transmission. You can also send transparent
data (beginning with DLE STX) as a conversational response. However, after you send one
transparent conversational response, the next response you send cannot be transparent as well.
Conversational responses are stored in the input buffer of the receiving station. BSCAM checks
buffer contents and reports any transmission errors that the response may indicate. The first
station can send its next message only after it gets the proper conversational response.
o
Chapter 1. Binary Synchronous Communications Access Method (BSCAM)
CO-IS
Binary Synchronous Communications Access Method
(BSCAM)
Programming for BSCAM Applications
o
To perform BSCAM communications between your Series/1 and any station(s) connected to it,
you write application programs using a set of Event Driven Language (EDL) BSC instructions.
Listed below are the BSC instructions and their basic uses.
Refer to the Language Reference for details on syntax and operands for each of the BSC
instructions.
Instruction
BSCCLOSE
Function
Frees a BSC line for use by other
tasks.
Code at the end of each task or
program.
BSCIOCB
Specifies BSC line address and
buffers for all BSC operations
A nonexecutable instruction, referred
to in every other BSC instruction.
BSCOPEN
Prepares a BSC line for use by a
task.
Code at the beginning of each
program or task.
BSCREAD
Reads data from a BSC line.
Consists of several variations,
called "types," each used to read
data in a different way.
Code to receive data from another
station.
BSCWRITE
Writes data to a BSC line.
Consists of several variations,
called "types," each used to write
data in a different way.
Code to initiate data transfer to
another station.
Comments
Figure 2. Event Driven Language BSe Instructions
Each instruction requires certain BSC control character sequences to be transmitted between
stations. The sections that follow, which discuss the use of the BSC instructions, also contain
information on the control characters associated with each instruction.
Basic Programming Functions for BSCAM
The two basic BSCAM functions are:
•
Write operations to send data to another station
Read operations to receive data from another station.
o
CO-16
SC34-0638
o
Programming for BSCAM Applications (continued)
In addition, your program must acquire the use of a BSC line and must provide buffers and
include other control information.
This section shows how to use the BSC instructions to perform BSCAM functions.
Acquiring Use of a BSC Line
You must gain the exclusive use of a BSC line before beginning a read or write operation, and
release it when the operation is over. The BSCOPEN instruction gets the line, and the
BSCCLOSE instruction gives up the line. Both instructions require the label of the BSCIOCB
instruction associated with the particular operation. The BSCIOCB instruction is discussed in
the next section.
OPEN BSCOPEN
CLOSE BSCCLOSE
BSCIOCB,ERROR=END
BSCIOCB,ERROR=END
Figure 3. Example of Coding BSCOPEN and BSCCLOSE Instructions
Coding Control Block for Read and Write Operations
c
BSCIOCB provides control information used by the other BSC instructions to perform read and
write operations. Each BSC instruction must refer to the label of a BSCIOCB instruction.
When you code BSCIOCB, specify the following:
BSC line address to be used throughout the operation
Address and length of any buffer(s) to be used
Polling or selection sequence to be used by a control station.
When you code BSCIOCB, you need to know:
•
BSC line type (control, tributary, point-to point) in use
•
Write type you are using (determines buffer requirements)
•
Read type you are using (determines buffer requirements)
Length of records (messages) to be sent or received
•
Tributary station device type (determines poll/select sequence used by control station).
Consult the tributary device description manual for correct poll and select sequences.
o
Chapter 1. Binary Synchronous Communications Access Method (BSCAM)
CO-17
Binary Synchronous Communications Access Method
(BSCAM)
Programming for BSCAM Applications (continued)
o
Below is an example of a BSCIOCB instruction that specifies line 19, and one buffer 80 bytes in
length.
I
lOCB
BSCIOCB
19,BUFFER,80
Figure 4. Example of Coding BSCIOCB Instruction
Code the BSCIOCB instruction outside the executable area of your programs.
Note: For an X.21 example, see "Using X.21 Switched Network Support" on page CO-48.
Specifying Buffers
The number of buffers required during a BSCAM operation depends on the read or write type.
Most write types need at least one buffer. However, the conversational writes need two buffers,
and the types D, E, EX, and N, do not need any buffers at all.
Write type
(code)
C
CV
CVX
ex
CXB
D
E
EX
I
IV
IVX
IX
IXB
N
Q
U
UX
Number of
buffers
1
2
2
1
1
0
0
0
1
2
2
1
1
0
1
1
2
Write type
(name)
Continue
Continue Conversational
Continue Conversational Transparent
Continue Transparent
Continue Transparent Block
Delay
End
End Transparent
Initial
Initial Conversational
Initial Conversational Transparent
Initial Transparent
Initial Transparent Block
NAK
Inquiry
User
User Transparent
Figure 5. Buffers Required for Write Operations
Most read types need only one buffer. However, the types D and Q do not require any buffers.
o
CO-18
SC34-0638
o
Programming for BSCAM Applications (continued)
Read type
(code)
C
D
E
I
P
Q
R
U
Number of
buffers
Read type
(name)
1
0
1
1
1
0
1
1
Continue
Delay
End
Initial
Poll
Inquiry
Repeat
User
Figure 6. Buffers Required for Read Operations
Sending Data
Under BSCAM, the instruction that sends data is BSCWRITE. Control character sequences are
generated when a BSCWRITE instruction executes, and certain acknowledgements are
exchanged between the sending and receiving stations. You must specify which type of write
operation you need to perform, according to the situation. These write types, and the reasons
for using each, are covered in the sections that follow.
In your program to send data, you will:
Define line address and buffers (BSCIOCB).
Acquire the BSC line for use by your program (BSCOPEN).
•
Transmit data with one or more BSCWRITE instructions (one instruction for each
message).
•
Give up the use of the BSC line (BSCCLOSE).
Selecting BSCWRITE Types
There are several different types of write operation, each used to transmit data in a different
form or situation, and each coded a different way with the BSCWRITE instruction. The factors
that determine which type to use are:
•
Type of data (transparent, nontransparent)
•
Mode of transmission (standard, conversational)
Order of transmission of messages
•
Special conditions that occur during transmission.
The sections that follow tell how and when to code the various types of BSCWRITE instruction.
o
Chapter 1. Binary Synchronous Communications Access Method (BSCAM)
CO-19
Binary Synchronous Communications Access Method
(BSCAM)
Programming for BSCAM Applications (continued)
o
Sending the First Message
Code an initial write instruction to send the first message in a transmission. Different types of
initial write instructions exist for each of the modes of transmission, for each of the data types,
and for combinations of the two.
In the following table, find the type of data you are sending and the mode of transmission you're
using. The table will tell you which type of initial write instruction to code, and how to code it.
Each write type consists of BSCWRITE followed by a suffix.
Data
Type
Transmission
Mode
Write
Type
What to code
Standard
Standard
Initial
BSCWRITE I
Standard
Conversational
Initial Conversational
BSCWRITE IV
Transparent
Standard
Initial Transparent
BSCWRITE IX
Transparent
Conversational
Transparent
Initial Conversational
Transparent
BSCWRITE IVX
Transparent Block
Standard
Initial Transparent Block
BSCWRITE IXB
Figure 7. Initial Write Types
Sending Po!!/Ss!sct Sequences
If your station is acting as the control station on a multipoint line, then it must poll and select its
tributaries. To send each poll/ select sequence, code any initial write instruction. The
poll/ select sequence consists of the following characters:
EOT (poll or selection address) ENQ--------- >
You must place the ENQ and the poll or selection address in your output buffer, as specified in
your BSCIOCB statement. For more information on the poll/select sequence, refer to General
Information - Binary Synchronous Communications.
Control Characters Associated with Initial Write Instructions
When an initial write instruction executes, certain BSC control characters must go across the line
to the receiving station. The tables that follow show the flow of characters that must
accompany each initial write instruction. The access method generates the ENQ and ACK
sequences, but you must supply all other control characters in your output buffer.
o
CO-20
SC34-0638
o
Programming for BSCAM Applications (continued)
Instruction
BSCWRITE I
Sending Station
Type of Connection
point-to- point
BSCWRITE I
multipoint
control station
BSCWRITE I
multipoint
tributary
Control Character Flow
Sending
Receiving
ENQ------------>
<------------ACK
ETX (Text) STX--->
< - - - - (Response character)
EOT------------>
ENQ (Address)------->
<------------ACK
ETX (Text) STX------>
<-----(Response character)
ETX (Text) STX----->
<-----(Response character)
Figure 8. Control Character Flow for Initial Write Instructions
Instruction
BSCWRITE IV
c
Sending Station
Type of Connection
point-to- point
BSCWRITE IV
multipoint
control station
BSCWRITE IV
multipoint
tributary
Control Character Flow
Sending
Receiving
ENQ-------------->
<----------- -ACK
ETX (Text) STX----->
<----(Response Text)
EOT------------>
ENQ (Address)----->
<------------ACK
ETX (Text) STX---->
<-----(Response Text)
ETX (Text) STX----->
<-----(Response Text)
Figure 9. Control Character Flow for Initial Conversational Write Instructions
Instruction
BSCWRITE IX
Sending Station
Type of Connection
point-to- point
BSCWRITE IX
multipoint
control station
BSCWRITE IX
multipoint
tributary
Control Character Flow
Sending
Receiving
ENQ------------>
<------------ACK
OLE ETX (Text) OLE STX----->
<-----(Response Character)
EOT------------>
ENQ (Address)------>
<------------ACK
OLE ETX (Text) OLE STX----->
<-----(Response Character)
OLE ETX (Text) OLE STX----->
<-----(Response Character)
Figure 10. Control Character Flow for Initial Transparent Write Instructions
o
Chapter 1. Binary Synchronous Communications Access Method (BSCAM)
CO-21
Binary Synchronous Communications Access Method
(BSCAM)
Programming for BSCAM Applications (continued)
Instruction
BSCWRITE IXB
Sending Station
Type of Connection
point-to- point
BSCWRITE IXB
multipoint
control station
BSCWRITE IXB
multipoint
tributary
o
Control Character Flow
Sending
Receiving
ENQ-------- ---->
<------------ACK
OLE ETB (Text) OLE STX----->
<----(Response Character)
EOT------------>
ENQ (Address)----->
<--- ---------ACK
OLE ETB (Text) OLE STX----->
<-----(Response Character)
OLE ETB (Text) OLE STX----->
<-----(Response Character)
Figure 11. Control Character Flow for Initial Transparent Block Write Instructions
Instruction
BSCWRITE IVX
Sending Station
Type of Connection
point-to- point
BSCWRITE IVX
multipoint
control station
BSCWRITE IVX
multipoint
tributary
Control Character Flow
Sending
Receiving
ENQ------------>
<------ ------ACK
OLE ETX (Text) OLE STX----->
<-----(Response Text)
EOT------------>
ENQ (Address)----->
<------------ACK
OLE ETX (Text) OLE STX----->
<----(Response Text)
OLE ETX (Text) OLE STX----->
<-----(Response Text)
rr~\
i~..:7.f/
Figure 12. Control Character Flow for Initial Conversational Transparent Write Instructions
Sending Subsequent Messages
Code a continue write to send the second message and any further messages in a transmission.
Code a continue write only after coding an initial write. Also, always make sure that the
continue write type matches the initial write type (standard, conversational, transparent,
transparent block, or conversational-transparent type). Refer to the table that follows to see
which continue write type to code.
o
co- 22
SC34-0638
o
Programming for BSCAM Applications (continued)
Data
Type
Transmission
Mode
Write
Type
What to Code
Standard
Standard
Continue
BSCWRITE C
Standard
Conversational
Continue Conversational
BSCWRITE CV
Transparent
Standard
Continue Transparent
BSCWRITE CX
Transparent
Conversational
Continue Conversational
Transparent
BSCWRITE CVX
Transparent Block
Standard
Continue Transparent Block
BSCWRITE CXB
Figure 13. Continue Write Types
Control Characters Associated with Continue Write Instructions
When a continue write instruction executes, certain BSC control characters must be sent to the
receiving station. The tables that follow show the control character flow for each continue write
type.
o
Instruction
Sending Station
Type of Connection
Control Character Flow
Sending
Receiving
BSCWRITE C
all types
ETX (message 1+n text) STX--->
<-----Response character
BSCWRITE CV
all types
ETX (message 1+n text) STX--->
<-----Response Text
BSCWRITE CX
all types
OLE ETX (message 1+n text) OLE STX--->
<-----Response character
BSCWRITE CXB
all types
OLE ETB (Message 1+n Text) OLE STX--->
< - - - - - Response Character
BSCWR ITE CVX
all types
OLE ETX (Message 1+n text) OLE STX--->
<-----Response Text
Figure 14. Control Character Flow for Continue Write Instructions
Coding Special Write Types
Besides sending messages, you may need to control data transmissions in special ways during a
write operation. The write types listed below cause BSCAM to perform specific functions. You
will need to determine where and when these functions are useful in your program.
o
Chapter 1. Binary Synchronous Communications Access Method (BSCAM)
CO-23
Binary Synchronous Communications Access Method
(BSCAM)
Programming for BSCAM Applications (continued)
Write
What to Code
Explanation
Delay
BSCWRITE D
Delays transmission of next
message. You can code multiple
delays before transmission resumes.
Inquiry
BSCWRITE Q
Requests retransmission of response
(text or acknowledgement sequence)
to a previously sent message.
NAK
BSCWRITE N
Transmits the Negative
Acknowledgement (NAK) character.
A tributary can write NAK if not
ready during polling / selection.
User
BSCWRITE U
Transmits a character stream.
User Transparent
BSCWRITE UX
Transmits character stream in
transparent mode.
o
T~pe
Figure 15. Special Write Types
Delaying Transmission
You can inform the receiving station that transmission of the next message will be delayed with
a delay write instruction. You can code multiple delays before resuming transmission.
Sending a Negative Acknowledgement
When you need to transmit a negative acknowledgement (NAK) character, code a NAK write.
This instruction simply sends the NAK character. Tributary stations can send it to signify
"device not ready" in response to polling or selection by the control station.
Sending an ENQ Character
To send an ENQ character, code an inquiry write instruction. This instruction is most commonly
used to request retransmission of the receiving station's response to the last message sent.
Sending a Data Stream
In special situations you may want to send a data stream, generating no control characters. This
is possible with either a user write (to send standard data) or a user transparent write (to send
transparent data).
o
CO-24
SC34-0638
o
Programming for BSCAM Applications (continued)
Unlike other write instructions, the user and user transparent types do not generate the
transmission of any predefined control characters or require any acknowledgement from the
receiving station. In addition, BSCAM does not perform error recovery for the data stream.
The data stream consists of the contents of the first buffer you specify in a BSCIOCB
instruction. With the user write instruction, once the contents of the buffer are sent, the
operation is over. However, with the user transparent write, you must signal the end of the
operation by transmitting the contents of a second buffer specified in BSCIOCB. The buffer
can contain any of these control character pairs: DLE ETX, DLE ETB, or DLE ENQ.
Control Characters Associated with Special Write Instructions
The following control characters are sent by the special write instructions.
Instruction
Sending Station
Type of Connection
Control Character Flow
Sending
Receiving
BSCWRITE D
all types
TTD------------>
<------------NAK
BSCWRITE Q
all types
ENQ------ ------>
<----Response Character or Text
BSCWRITE N
c
all types
NAK------------>
Figure 16. Control Character Flow for Special Write Type Instructions
Ending a Write Operation
Once you have written all your data, you need to tell the other station not to expect any more.
Two write types signify the end of a write operation.
The end write instruction (BSCWRITE E) sends an EOT to end write operations in any form of
transmission.
The end transparent write instruction (BSCWRITE EX) sends a DLE EOT character to indicate
the end of a write operation. Use this instruction if you are transmitting over a switched line.
Programming Sequence for Write Operations
Now that you know about the various write types, you'll want to be sure to code them in the
right order. You'll also want to make sure that all the write types "match up" in your program.
Refer to the chart below and find the mode of transmission you plan to use in your program. It
shows the basic sequence of write instructions to use.
o
Chapter 1. Binary Synchronous Communications Access Method (BSCAM)
CO-2S
Binary Synchronous Communications Access Method
(BSCAM)
Programming for BSCAM Applications (continued)
Mode of
Trarismission,
Writing
First
Writing
Next
Optional
o
Ending
Write
O~eration
DataT~e
Messa~e
Messa~e
Standard, Standard
data
I
C
D,Q,U,N
E or EX
Conversational
Standard data
IV
CV
D,Q,U,N
E or EX
Standard,
Transparent data
IX
CX
D,Q,U,N
E or EX
Standard,
Transparent Block
data
Conversational,
Transparent data
IXB
CXB
D,Q,U,N
E or EX
IVX
CVX
D,Q,U,N
E or EX
Figure 17. Programming Sequences for Sending Data
Receiving Data
A read operation retrieves data from a BSC line. Each time another station sends data to your
Series/I, you must have a read operation programmed to receive it.
In your read program you will do the following:
Define line address and buffers (BSCIOCB)
Prepare the BSC line for use by your program (BSCOPEN)
Receive data with one or more BSCREAD instructions (one instruction for each message)
•
Give up the use of the BSC line (BSCCLOSE).
Selecting BSCREAD Types
Several different types of read operation are available. Each is associated with a different
BSCREAD instruction. Each type is used in certain situations, similar to the way the various
write types are used. However, with read types it doesn't matter what mode of transmission you
are using. With read types, it is when you issue the instruction that is important. For example,
will the instruction read the first message? Or will it read the second message, or the last
message? These are some of the questions you must ask when preparing to code read types.
The chart on the next page lists all the read types, and how and when to code them. They are in
alphabetical order, not in the order you would code them in a program.
()
CO-26
SC34-0638
o
c
Programming for BSCAM Applications (continued)
Read
Type
What to Code
Explanation
Continue
BSCREAD C
Reads subsequent message after
first message read by Read Initial.
Issue until EOT received.
Delay
BSCREAD D
Acknowledges correct receipt of
message. Requests sender to wait
before sending the next message.
Multiple delays can be issued before
resuming transmission.
End (Reverse
Interrupt)
BSCREAD E
Positive acknowledgment that
requests sender to end current
transmission and reverse the
direction of data transfer.
Initial
BSCREAD I
Reads first message in a
transmission.
Poll
BSCREAD P
Reads the poll / select sequence sent
by a control station to a Series/1 that
is a tributary on a multipoint line.
Inquiry
BSCREAD Q
Reads the ENQ character.
Repeat
BSCREAD R
Requests retransmission of the last
message sent.
User
BSCREAD U
Reads data stream. Does not
perform error recovery.
Figure 18. Read Types
Receiving the First Message
Regardless of its mode of transmission, you will always read the first message with an initial read
instruction, BSCREAD I.
Receiving Subsequent Messages
To read subsequent messages, code a continue read, BSCREAD C. Issue continue read
instructions until the transmitting station sends the end-of -transmission (EOT) sequence.
Delaying Transmission of Data
After successfully reading a message you may wish the sender to pause before sending the next
one. A delay read instruction, BSCREAD D, causes this pause. You can issue as many delays as
o
Chapter 1. Binary Synchronous Communications Access Method (BSCAM)
CO-27
Binary Synchronous Communications Access Method
(BSCAM)
Programming for BSCAM Applications (continued)
o
needed before telling the sender to resume transmission. (After the last delay, transmission
resumes automatically.)
Responding to a Poll/Select Sequence
If your Series/lis a tributary station on a multipoint line, code a poll read (BSCREAD P)
instruction to receive polling and selection sequences from the control station. Once your
station is polled or selected, it should issue the appropriate read or write initial instruction.
Reading an ENQ Character
To read an ENQ from the sending station, code an inquiry read instruction, BSCREAD Q.
Requesting Repeat of a Message
If you are unsuccessful in reading the last message that was sent, you can ask the sender to
retransmit it with a repeat read instruction, BSCREAD R.
Reading a Data Stream
The sender can transmit a data stream, which consists of the contents of a buffer. To receive
this data, code a user read instruction, BSCREAD U. BSCAM does not perform error recovery
during this type of read operation.
Ending the Read Operation (Reverse Interrupt)
The RVI (reverse interrupt) control sequence is a positive response used in place of ACK 0 or
ACK 1. The receiving station transmits an RVI to request the sender to end current
transmissions because the receiver now wishes to send. The sending station treats the RVI as a
positive acknowledgment and responds by transmitting all data that prevents it from becoming a
receiving station. This may require more than one block transmission. For the RVI, code the
end read instruction, BSCREAD E.
o
CO-28
SC34-0638
o
Programming for BSCAM Applications (continued)
Providing for Errors During BSCAM Operations
All the BSC instructions (except BSCIOCB, which is non-executable) allow you to code
routines to take over during error or end conditions. BSCOPEN arid BSCCLOSE have the
ERROR= operand; BSCREAD and BSCWRITE have both ERROR= and END= operands. It
is useful to provide for error recovery in situations such as:
Errors during opening or closing of the BSC line
Errors in starting the program
•
Errors in doing the initial read or write
Errors in continuing reads or writes
Errors in ending the read or write operation.
Common routines are to print error messages and BSC return codes in response to errors, or to
restart operations at the previous phase or at the beginning.
o
BSCAM Sample Programs
The following sample programs perform BSCAM operations. Note that both programs include
routines that take over when an error occurs during any phase of the operation.
WRITE Sample Program
This program performs a write operations in transparent mode of transmission. The program
does the following:
1. Communicates with the READ sample program
2. Opens the BSC line
3. Performs initial write of data
4. Performs calculations to build the next message to send
5. Performs continue writes until all data is sent
o
Chapter 1. Binary Synchronous Communications Access Method (BSCAM)
CO-29
Binary Synchronous Communications Access Method
(BSCAM)
BSCAM Sample Programs (continued)
o
6. Ends the write operation
7. Prints error messages and return codes if a failure occurs during any phase of the program
8. Closes the BSC line.
WRITEX
START
RESTART
PROGRAM
BSCOPEN
BSCWRITE
START
IOCB,ERROR=PRINTERR
IX,IOCB
****************************************************
OPEN THE LINE AND BEGIN INITIAL TRANPARENT WRITE
****************************************************
IF
IF
DO
ADD
CONVTB
(WRITEX,EQ,10) ,GOTO,RESTART
(WRITEX,NE,-1) ,GOTO,PRINTERR
29,TIMES
I, 1
MSG#,1
****************************************************
CONTINUE THE WRITE OPERATION
****************************************************
BSCWRITE
ENDDO
CX,IOCB,ERROR=PRINTERR
****************************************************
END THE WRITE OPERATION
****************************************************
BSCWRITE
GOTO
E,IOCB,ERROR=PRINTERR
ALLDONE
****************************************************
ERROR ROUTINE: PRINT ERROR MESSAGE AND BSC RETURN CODE
****************************************************
PRINTERR
MOVE
PRINTEXT
PRINTNUM
ERRCODE,WRITEX
'WRITE ERROR:' ,SKIP=1
ERRCODE
****************************************************
CLOSE THE LINE
****************************************************
ALLDONE
BSCCLOSE
PROGSTOP
IOCB
****************************************************
CONTROL INFORMATION: WRITE DATA TO BSC LINE 19
USE A BUFFER LENGTH OF 82 CHARACTERS
****************************************************
IOCB
BUFFER
MSG#
I
ERRCODE
BSCIOCB
DC
DC
DC
DC
DC
ENDPROG
END
19,BUFFER,82
x'1002'
CL74'TEST MESSAGE'
CL6'
l'
F'1'
F'O'
o
CO-30
SC34-0638
o
BSCAM Sample Programs (continued)
READ Sample Program
This program reads the transparent data sent in the preceding WRITE program. The program
does the following:
1. Gains use of the system printer
2. Opens the BSC line
3. Performs initial read of data
4. Prints data on printer
5. Reads subsequent data and prints it
6. Prints error messages and return codes if failure occurs during any phase of the program
7. Ends the read operation
8. Closes the BSC line.
c
o
Chapter 1. Binary Synchronous Communications Access Method (BSCAM)
CO-31
Binary Synchronous Communications Access Method
(BSCAM)
BSCAM Sample Programs (continued)
READX
START
PROGRAM
ENQT
BSCOPEN
o
START
$SYSPRTR
IOCB,ERROR=PRINTERR
**************************************************
OPEN THE'LINE AND BEGIN INITIAL READ
**************************************************
RESTART
PRINTIT
BSCREAD
IF
IF
MOVE
PRINTEXT
I,IOCB
(READX,EQ,10) ,GOTO,RESTART
(READX,NE,-1) ,GOTO,PRINTERR
MSG,INPUT+2, (80,BYTE)
MSG, SKIP=1
**************************************************
CONTINUE THE READ OPERATION
**************************************************
BSCREAD
GOTO
C,IOCB,END=ALLDONE,ERROR=PRINTERR
PRINTIT
**************************************************
ERROR ROUTINE:
PRINT ERROR MESSAGE AND BSC
RETURN CODE, HAVE SENDER REPEAT MESSAGE
**************************************************
PRINTERR
ALLDONE
MOVE
PRINTEXT
PRINTNUM
BSCREAD
GOTO
DEQT
RETCODE,READX
ERRMSG,SKIP=1
RETCODE
R,IOCB,ERROR=ALLDONE,END=ALLDONE
PRINTIT
**************************************************
CLOSE THE LINE
,~
U
**************************************************
BSCCLOSE
PROGSTOP
IOCB
**************************************************
CONTROL INFORMATION: READ FROM BSC LINE 29,
USE A BUFFER 83 CHARACTERS IN LENGTH
**************************************************
IOCB
INPUT
MSG
ERRMSG
RETCODE
BSCIOCB
DC
TEXT
TEXT
DC
ENDPROG
END
29,INPUT,83
CL83'
LENGTH=80
'READ ERROR:'
F'O'
Interacting with BSCAM (Using BSC Utilities)
The BSCAM utilities ($BSCTRCE, $BSCUT1, $BSCUT2) help you check out the way
BSCAM is working and point out any problems that may exist. This section shows what the
BSC utilities allow you to do, and what types of information you can gather about BSCAM
operations.
()
CO-32
SC34-0638
o
Interacting with BSCAM (Using BSC Utilities) (continued)
Tracing I/O Activities on a BSC Line (Using $BSCTRCE)
The $BSCTRCE utility traces activity on the BSC line you specify. The trace information goes
into a trace file, which you must allocate before beginning the trace. (The data in the trace file
is unformatted. To format the data for a printout or to display it on a screen, use the $BSCUTI
utility.)
Since 110 activity on a BSC line is controlled by an application program, you must have one of
your programs loaded and running at the same time you use $BSCTRCE. The program must be
the one controlling the line you specify to be traced.
$BSCTRCE writes trace file records at the completion of a BSC operation. Therefore, when
testing a conversational write, if you specify the same buffer address for both input and output,
the trace file does not show the data that was transmitted; it shows only the conversation
responses received.
Multiple BSC lines may be traced concurrently with multiple loads of $BSCTRCE using
different trace files. Each copy of $BSCTRCE must use a different trace data set. Each trace
data set name should reflect a unique line number.
When $BSCTRCE terminates, it displays the relative record number of the last trace record
written.
o
Allocating the Trace File Data Set
You must allocate the data set that will contain the trace information before using the
$BSCTRCE utility. It must be a "data" type data set. You can allocate the data set at any size
you wish. Use the $DISKUTI utility to allocate the data set.
When the end of the output file is reached, it is reused from the beginning, since $BSCTRCE
displays the relative record number of the last trace record written upon termination. The trace
file can then be displayed or listed using the $BSCUTI utility.
Invoking $BSCTRCE
You must load $BSCTRCE in the same partition as the application program that is controlling
the line you want to trace.
Note: If you want to use the $BSCTRCE utility with X.21, you must load the utility first.
o
Chapter 1. Binary Synchronous Communications Access Method (BSCAM)
CO-33
Binary Synchronous Communications Access Method
(BSCAM)
Interacting with BSCAM (Using BSC Utilities) (continued)
Use the $L command or option 8.1 of the session manager. When you have loaded
$BSCTRCE, it prompts you for the disk or diskette file where you want to place the trace
output. $BSCTRCE then prompts you for the line number you want to trace. You can end the
trace action with the attention command STOP.
Specifying BSe Line to Trace
In response to the utility's prompt, enter the number of the BSC line you want to trace. Make
sure it is the same line that the loaded application program is controlling.
Terminating the Trace
To end the trace at any point, press the attention key and enter STOP. The utility displays the
number of the last record it traced.
Tracing Multiple BSe Lines
You can perform traces on multiple lines at the same time. For each trace, do the following:
Load the application program that controls the line.
•
Load $BSCTRCE in the same partition as the program.
•
Specify the BSC line number.
Direct each trace file to a different data set (the volumes can be the same).
Formatting Trace Files for Print or Display (Using $BSCUT1)
Once you have run $BSCTRCE and wish to see what is in the trace file, use the $BSCUT1
utility to format the file and send it to a printer or terminal. You can select the record for the
trace file to dump. You will be prompted, as necessary, for information required by the
functions of $BSCUT 1.
CO-34
SC34-0638
o
o
Interacting with BSCAM (Using BSC Utilities) (continued)
Invoking $BSCUT1
You invoke $BSCUT1 with the $L command or option 8.2 of the session manager.
$BSCUT1 Commands
To display the $BSCUT1 commands at your terminal, enter a question mark in response to the
prompting message COMMAND (?):.
$L $BSCUT1
LOADING $BSCUTl
>
21P,00:04:21, LP= 9200, PART=l
COMMAND(?):
CV - CHANGE VOLUME
DP - PRINT TRACE FILE ON PRINTER
DU - DUMP TRACE FILE ON TERMINAL
(CA WILL CANCEL)
EN - END PROGRAM
COMMAND
(1):
After $BSCUT1 displays the commands, it prompts you with COMMAND (?):. Then you can
respond with the command of your choice (for example, CV).
o
Example: Figure 19 shows dumping records in a trace file to the terminal.
COMMAND (?): DU TRACE9
FIRST RECORD: 32
LAST RECORD: 33
DUMP OF TRACE FILE TRACE9 ON EDX002
***** RECORD 32 ***** START OF CHAINED OPERATION
CC = 0002 ISW = A009 STATUS = 98DA 0001 c080
RESULT: EXCEPTION - WRONG LENGTH RECORD (SHORT)
DeB = 8004 0000 0000 0000 0000 2B1C 0002 2AE4
OPERATION: CHAINED TRANSMIT
DATA LENGTH =
1061
1
2
Figure 19. Dumping Trace File Records
Chapter 1. Binary Synchronous Communications Access Method (BSCAM)
CO-35
Binary Synchronous Communications Access Method
(BSCAM)
Interacting with BSCAM (Using BSC Utilities) (continued)
o
The following screen shows the display for the LAST RECORD selected in the previous
example, which was record number 33.
'; ~***~.•'. :.• ;.~ECQRD::,;33··.:!* ~,~~;~ Cb.N:Td NUAr:tbN:OF' ;CHP;I, NED? OP E: RA1
,bCB' •. =: ;;::~ ()O:8:!'06().():;QP()OO~:9'O ,~6~6:'~~~9' :6Z~q/96f6 \,
OPERATI:ON i' ·R~:CEl.\lE . WtT~':I!. MEQUT:";
,....,
DATA {fNGTH= . ':4S:S ' : ' ." :'J: ':
Q227615BF1f6\'l{'BF5f9,4B:F3F;.4QDl"D6C2 ', •• 1$16,'59.34 JOBI
17 ~040 F4F2F#.4PD.7~9F3FQ :FJP9 f5F6,~oc~ 1 424 PR301656 EI
33 E7C5 C3E4E3'C9 oSt7 40D4,40[)7:09C9 ;0640 lXECUTlN~MPR 101
49 ';Qf7 JE27615BF1 F6 4BF5,F94B F3F~4001 J:T.. I$:l6;S,9~34JJ'
65 D6C24040 :F4'P2F340C8D8: :A1 f2:'F 1:P6:{S.E6 ,lOB ,423., H~f2l656'1
,$1 4,Ot5E7C~C3E4E3C90SC?~o():4':4o'Q7;':O~C9 L EXECUTI NGM>PRII
91.06;0;4QF7-1E27615B;F1 F646F5 F94B~f'3~4,;1 0 7 .. 1$16 •.59.341
113 4001 ·06C2:.4.040 ;F3FO:FQ40,·. ,C9E2 FOF3,PtF4 ::1.,; JO~: •..,300 JSQ3141.'
12'9 'F4F54QC5:{7C5:'.C~~k·J3C9,;;f)?C7,40E,$~d,Dl~ 14~ E~EC!JT;t N:G:ll :Jlt:
145 'D9C9D640UOF5 ,'lEZ761S8';Fl:,~6'4:~j:5"F9'~ij; I:~J.o<5~./$16.:~,9,.,J '
161 F3F4,4001p6C2 1043 T4F~:;4~;7a,p;7E;2D7P5' 134'JO,B~.4~ #G~PE:I,
177:'J=:Q,FIF04bD'6D5:4007D~C9;D5:E3'D9F2 ,4040' Iq~poN,;PR;lNTlt21';
,J 93 . . 0709,C9J)64040 F51EZ1,(>.J '. 58',r 1.,FQ:4~ :·~:5F9IPRIO<5·~1$16 .591
209 4BFJF4'ltO:0 lD6C'24040FJ:F:2f040C~C)P:6 1:34 ,JOB' '320FG61
'~~Sfl( D4051 ~?{>:~.'
"I~:N •. '· ":"":,', ",:1' "
,,1
,'OUMp:;:CGMPLETE
ANOTHER. AREA?
Figure 20. Dump of the LAST RECORD of Trace File
CO-36
SC34-0638
,rf - \,
I
,
~
o
Interacting with BSCAM (Using BSC Utilities) (continued)
Reading Trace File Records
Trace records can be up to 256 bytes long. They consists of several fields, as shown in
Figure 21.
Field
Size
(bytes)
Explanation
CC
2
Condition code
ISW
2
Interrupt status word
STATUS
6
Cycle status words: 3 words, 2 bytes
each
DCB
16
Device Control Block
LGTH
2
Length of data sent or received
DATA
up to 224
Data in main storage.
LAST4
4
Last four bytes of data if total data is
longer than 224 bytes
Figure 21. Trace Record Fields
Notes:
1. The CC, ISW, and STATUS fields are zero when the DCB has been chained from the
previous record's DCB.
2. $BSCTRCE always reports an error on a chained DCB to the first DCB in a chain.
Refer to the IBM Series/l Communications Features Description, GA34-0028 for descriptions of
the interrupt condition code, interrupt status word, cycle status words, and device control block.
o
Chapter 1. Binary Synchronous Communications Access Method (BSCAM)
CO-37
Binary Synchronous Communications Access Method
(BSCAM)
Interacting with BSCAM (Using BSC Utilities) (continued)
Testing BSCAM Operations (Using $BSCUT2)
With the $BSCUT2 utility you can test these BSCAM capabilities:
Read and write operations
standard transmission of transparent and standard data
conversational transmission of transparent and standard data.
Polling and selection by control station on a multipoint line
Response to polling and selection by tributary station on a multipoint line.
The $BSCUT2 utility prompts you for information such as:
BSC line addresses
Device addresses of communications feature cards
Record length, also called buffer size, in bytes
Number of records to be transmitted or received.
The utility examines the information you supply in response to its prompts. If you supply
incorrect information, the utility cannot perform its test and issues an error message.
By examining the information you supply, $BSCUT2 also checks the BSCLINE statements
included in the supervisor, and the customized jumper assignments in BSC hardware features.
You can use $BSCTRCE to trace the exercising activities of $BSCUT2. You can format and
print the records with $BSCUT 1.
Hardware Considerations When Using $BSCUT2
You can use $BSCUT2 to test BSCAM on just one Series/lor between two Series/ 1'so When
testing with just one Series/I, you must have two BSC lines and wrap a connection between
them. Assign one line to do the "read" and the other to do the "write."
If you are running a test between two processors (one performing a read, the other a write
operation), load $BSCUT2 on both processors and enter one BSC line address at the "read"
processor and another BSC line address at the "write" processor. If you specify an invalid
address for one of the processors, the test will fail.
CO-38
SC34-0638
o
o
Interacting with BSCAM (Using BSC Utilities) (continued)
Invoking $BSCUT2
You invoke $BSCUT2 with the $L command or option 8.3 of the session manager.
$BSCUT2 Commands
To display the $BSCUT2 commands at your terminal, enter a question mark in response to the
prompting message COMMAND (?):.
$L $BSCUT2
lOADING $BSCUT2
>
76P,00:05:31, lP= 9200, PART=l
COMMAND (1): 1
RWI ---- READ/WRITE - NONTRANSPARENT
RWIX --- READ/WRITE - TRANSPARENT
RWIXMP - READ/WRITE - MULTIDROP l)NE TRANSPARENT
RI ----- READ - TRANSPARENT/NONTRANSPARENT
WI ----- WRITE - NONTRANSPARENT
WIX ---- WRITE -TRANSPARENT
EN ~---- END TH~ PROGRAM
CH ----- CHANGE ~ARD-COPY DEVICE
RW IVX -- READ/WR ITE - TRANSPARENTCONVERSATI ONAl
RWIV -- READ/WRITE - NONTRANSPARENT CONVERSATIONAL
o
After $BSCUT2 displays the commands, it prompts you with COMMAND: (?):. Then you can
respond with the command of your choice (for example, RI).
Testing Read and Write Capability Simultaneously
With BSCAM you can test read and write operations at the same time. You can run the tests
between two processors, or between two lines on one processor. If you are using one processor,
make sure you specify separate lines, one to read and the other to write. The read/write tests
available are:
•
Read/write of standard data, standard transmission: RWI command
Read/write of standard data, conversational transmission: RWIV command
Read/write of transparent data, standard transmission: RWIX command
Read/write of transparent data, conversational transmission: RWIXV command.
o
Chapter 1. Binary Synchronous Communications Access Method (BSCAM)
CO-39
Binary Synchronous Communications Access Method
(BSCAM)
Interacting with BSCAM (Using BSC Utilities) (continued)
o
For these read/write tests, the utility prompts for the following information:
READ ADDRESS and WRITE ADDRESS refer to the device address of the BSC hardware
feature. If the test is to be run between two processors (one to read and one to write), load
$BSCUT2 on both processors and enter the correct address for read on one processor and the
correct address for write on the other processor. One of the addresses can be invalid and the
task for the invalid address on each processor will fail due to an undefined line. However, the
read/write task will function properly. This is true for all $BSCUT2 commands.
The RECL prompts refer to the buffer size to be used and, therefore, the number of bytes
transferred in one transmission over the BSC line. The maximum buffer size permitted is 512
bytes. READ (RECL) should always be equal to or greater than WRITE (RECL) or errors will
occur.
NUMBER OF RECORDS determines the number of transmissions to be made before the test
ends.
The MONITOR function causes each task to report its progress to the terminal. If the monitor
function is enabled, messages such as TASK ENTERED and TASK EXITED are written to the
terminal.
Example: RWI command
CQMMAND. {~}:.
RWJ
~Wl ----.READlwRJrE - NONTRANSPARENT
READ ADDR~SS?·5A
WRITE ~.DPRESST 5B
READRE·CL?80
WRI TE RECI./l 80
NUMBER·OF RECORDS?
READ MONITOR? ~
WRiTE MONITORty
Example: RWIV command
COMM.AND ;•.<7:);: .•. . R\.HV. ...
. .• RWI ~.""' ':":' •READ/WR I TE· .~. .•
REAtiADDRESS75B
. WRJ TE.ADPRESS? SA
BUFFER LENGTH? 80
NUMflER. OF. RECORDS?
REAP .·MON I rOR 7 y.
WRf TEMONITOR ? Y
o
CO-40
SC34-0638
o
Interacting with BSCAM (Using BSC Utilities) (continued)
Example: RWIVX command
COMMAND (?): RWIVX
RWIVX -- READ/WRITE - TRANSPARENT CONVERSATIONAL
READ ADDRESS? 5A
WRITE ADDRESS? 5B
BUFFER LENGTH? 5
NUMBER OF RECORDS? 10
READ MONITOR? Y
WRITE MONITOR? Y
Example: RWIX command
COMMAND (?): RWIX
RWIX --- READ/WRITE - TRANSPARENT
READ ADDRESS? 5A
WRITE ADDRESS? 5B
READ RECL?80
WRITE RECl? 80
NUMBER OF RECORDS? 10
READ MONITOR? Y
WRITE MONITOR? Y
o
Testing Read and Write on a Multipoint Line (RWIXMP)
This command tests the polling/selection capabilities between stations and also reads and writes
transparent data. One BSC line acts as the control station, and one or more other stations act as
tributary stations.
When you issue the RWIXMP command, you must answer prompts for:
Control station device address
Number of tributaries
Tributary station device address and tributary address
Loop count for the control station
Buffer length and number of records to be exchanged.
The control station device address refers to the address of the BSC hardware feature. The
tributary station address refers to the jumpered tributary address on each hardware feature card.
You must jumper the adapter in tributary mode for this test to function properly. Loop count
refers to number of times you want to send a block of messages.
o
Chapter 1. Binary Synchronous Communications Access Method (BSCAM)
CO-41
Binary Synchronous Communications Access Method
(BSCAM)
o
Interacting with BSCAM (Using BSC Utilities) (continued)
To perform this test with $BSCUT2 running on two processors:
Processor 1 uses a valid control station (MC) address and dummy tributary (MT) addresses.
It acts as the control station.
Processor 2 uses a dummy control station address and valid tributary (MT) addresses. It
acts as the tributary station.
Specify the same number of tributaries on both processors.
Specify the same loop count on both processors.
Example: RWIXMP command
COMMAND (?): RWIXMP
RWIXMP - READ/WRITE - MULTIDROP LINE TRANSPARENT
MC DEVICE ADDRESS? 50
BUFFER LENGTH? 80
NUMBER OF RECORDS? 5
LOOP COUNT?: 1
MONITOR? Y
NUMBER OF TR IBUTARI ES?
PARAMETERS FOR TRIBUTARY?
MT DEVICE ADDRESS? 51
MT rrHSOrARY ADDRESS? 02
BUFFER LENGTH? . 80
1
l~~~~~~R~F ~ECORDS?5
)
DEVICE ADDRESS for this command refers to the device address of the BSC hardware
feature. TRIBUTARY ADDRESS refers to the jumpered tributary address on each hardware
feature card. LOOP COUNT refers to the number of times $BSCUT2 sends the block of
messages that you have specified.
Note: The adapter must be jumpered in tributary mode for this test to function properly.
Testing Read Capability
The RI command tests the read capability of both standard and transparent data. You don't
have to specify the number of records to read since it this test continues to read either type of
data until EOT is received. This test is useful for monitoring any BSC line sending data to the
processor. For example, the RI test can receive data from the $RJE2780 or $RJE3780 utility
operating in the same Series/lor in another Series/I.
o
CO-42
SC34-0638
o
Interacting with BSCAM (Using BSC Utilities) (continued)
Example: RI command
COMMAND (?): RI
RI ----- READ - TRANSPARENT/NONTRANSPARENT
READ ADDRESS? 5A
READ RECL? 80
READ MONITOR? y
Testing Write Capability
The WI command tests the write of nontransparent data. The utility prompts you for device
address, record length, and number of records.
The WIX command tests the write of transparent data. You specify device address, record
length, and number of records.
Example: WI command
o
COMMAND (?): WI
WI ----- WRITE - NONTRANSPARENT
WRITE ADDRESS? 58
WRITE RECL? 80
NUMBER OF RECORDS? 10
WRITE MONITOR? Y
Example: WIX command
COMMAND (?): WIX
WIX ---- WRITE - TRANSPARENT
WRITE ADDRESS? 58
WRITE RECl? 80
NUMBER OF RECORDS? 5
WRITE MONITOR? Y
Ending $BSCUT2 Utility (EN)
The EN command ends the $BSCUT2 utility.
Example: EN command
COMMAND (?): EN
$BSCUT2 ENDED AT 01:14:40
Changing Hard-Copy Device (CH)
The CH command reassigns the hard-copy device where the test messages and results are
printed or displayed. If the hard-copy device you enter is not defined to the system, output goes
to the terminal that loaded $BSCUT2.
o
Chapter 1. Binary Synchronous Communications Access Method (BSCAM)
CO-43
Binary Synchronous Communications Access Method
(BSCAM)
Interacting with BSCAM (Using BSC Utilities) (continued)
o
Example: CH command
Interpreting Test Results
The results of a test will print out or display at your output terminal. The utility issues a test
pattern message for every record it read or wrote in a test.
The first line of a test pattern message gives the task name, record number, and record length.
The second line shows the alphabet repeated to fill up the number of characters specified for
record length.
TASK READ ENTERED RECORD NUMBER= 1 RECORD LENGTH= 72
ABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRST
The meanings of the task names are as follows:
READ - read of standard or transparent data in standard mode
RXVI - read of transparent data in conversational mode
•
RNVI - read of standard data in conversational mode
•
WRTN - write of standard data in standard mode
•
WRIT - write of transparent data in standard mode
•
WXVI - write of transparent data in conversational mode
•
WNVI - write of standard data in conversational mode
•
MTX 1 - read of transparent data by a tributary station
•
MCXl - write of transparent data by a control station.
The output message in the previous example repeats for the number of records transmitted.
o
CO-44
SC34-0638
o
Interacting with BSCAM (Using BSC Utilities) (continued)
A test can fail if the utility detects an internal error in BSCAM. In that case, the utility issues a
BSC return code that points out the cause of the problem. Refer to the Messages and Codes for
explanations of the BSC return codes. However, a test can also fail because you supplied wrong
information to the utility. It could be that you gave invalid BSC line addresses or specified too
small a buffer for a read test. Retry the test and specify valid information to the utility.
Whenever an error is detected, either in BSCAM or in the information you entered, the test
ends, the utility is cancelled, and a program check message is issued to the logging terminal for
the system.
Monitoring BSC Lines with the Communications Indicator Panel
The communications indicator panel is an aid in program debugging and machine
troubleshooting during BSCAM operations. It lets you select a BSC line and the activity on
function to monitor.
Installing and Attaching the Communications Indicator Panel
The panel can be installed on the frame of full-width processors and 110 expansion units by
screwing it into the upper left part of the unit. It is possible to use the panel on half-width
processors because it is not necessary to install it on the unit itself.
c
To monitor a BSC line you must attach the panel connector to the card where the line is
assigned. Attach the panel connector to the appropriate set of pins on the card you want to
monitor. Be sure the card itself is properly seated and that the connector and pins fit together
snugly. Do not force the connector onto the pins.
Selecting BSC Line to Monitor
When using the panel on a 4-line adapter card, you must select which of the BSC lines to
monitor. Using the toggle switches labeled "LINE SELECT," set the last three bits of the line's
device address, in binary form.
When using the panel on a single-line card, you do not need to set the line select switches. The
panel will monitor the line automatically.
o
Chapter 1. Binary Synchronous Communications Access Method (BSCAM)
CO-4S
Binary Synchronous Communications Access Method
(BSCAM)
Interacting with BSCAM (Using BSC Utilities) (continued)
o
Selecting Function to Monitor
The "DISPLAY /FUNCTION SELECT" switches allow you to select what activity or function
to monitor on the line. The settings are different for the single-line adapter and the 4-line
adapter. The following is an overview of the functions and activities you can monitor with the
panel.
DCB control word
•
DCB chain address
•
DCB byte count
•
DCB data address
Storage data register
Interrupt condition code
Interrupt status byte
•
Cycle-steal status word
(-\
I
Cyclic redundancy check character
j
~,J
Modem or modem eliminator states
Jumper assignments
•
Multipoint station address
Control character transmission
•
Errors in block checking.
The information supplied with the communications indicator panel can help you isolate problems
or confirm proper functioning of BSCAM and its associated hardware.
o
CO-46
SC34-0638
Interacting with BSCAM (Using BSC Utilities) (continued)
Example of Using the Communications Indicator Panel
Figure 22 shows the communications indicator panel. Assume that it is being used to test one of
the lines on a 4-line adapter. The "line select" switches are set at "111," indicating the last
three digits, in binary form, of the line address being tested. The "display/function select"
switches are set at "10111," which causes the panel to monitor when the line goes into select or
control mode, and when VRe or Bee errors occur on the line. (For detailed information on
the exact switch settings to test both single and 4-line cards, refer to the IBM Series/l
Communications Features Description, GA34-0028. For X.21 display/function select switch
settings, refer to the IBM Series/l Synchronous Communications Single-Line Control Attachment
Feature, GA34-0241.)
o
2
3
4
5
6
7
00000'000
0 16
c'
8
4
2
1
4
2
10
~~QQQQoQ
L
I
L
DISPLAY/FUNCTION
I
SELECT
~
LINE
SELECT~
Figure 22. Communications Indicator Panel
o
Chapter 1. Binary Synchronous Communications Access Method (BSCAM)
eO-47
Binary Synchronous Communications Access Method
(BSCAM)
Using X.21 Switched Network Support
The X.2I circuit switched network support is the basis for the BSC link with the digital Public
Data Network used by many countries outside the United St~tes. The information in the
preceding sections is still valid for the X.2I network; the exceptions are noted in this section.
For X.2I to function on your Series/I, you must:
Jumper the IBM 2080 synchronous communications single-line control, high speed feature
card for switched operation.
•
Perform system generation for X.2l circuit switched support.
-
Define the connection type you want.
Edit the $$X2IDS data set on your IPL volume and build a connection record.
•
Know the network information codes for your country.
Convert BSC program for X.21.
Activate $LOG for tracking X.2l errors and call progress signals.
Note: For general hardware information about IBM implementation of X.2l, refer to IBM
Implementation of X.21 Interface General Information Manual, GA27-3287.
Attaching and Jumpering the 2080 Card
You must jumper the 2080 card for switched operation if you want X.2I switched network
support capabilities, and you must jumper BSC if you want to use BSC.
For details on the functional characteristics and installation of this card, refer to IBM Series/l
Synchronous Communication Single-Line Control Attachment Feature Description, GA34-024I, or
the Maintenance Logic Diagrams and the Customer Site Preparation Manual, GA34-00S0.
System Generation for X.21 Support
During system generation, you must tell the supervisor to support X.2l by defining the
BSCLINE definition statement and connection type, and by including the BSCX2l module.
(Refer to Installation and System Generation Guide for system generation information.)
o
CO-48
SC34-0638
o
Using X.21 Switched Network Support (continued)
Determining the Connection Type You Need
The following figure shows the four connection types defined for BSC X.21 circuit switched
support, their connection method, and their protocol after connection.
esc
connection type
supplied by user
X.21
method
Auto answer
Auto call
Auto call
Direct call
Switched auto (SA)
Switched manual (SM)
Auto call (AC)
Direct call (DC)
esc
protocol
after connection
Pt-to-pt switched
Pt-to-pt switched
Pt-to-pt switched
Pt-to-pt switched
Figure 23. Mapping Procedures for BSC X.21 Circuit Switched Support
Use the connection type when you code the TYPE= operand of the BSCLINE statement. You
must code this parameter because there is no default for TYPE= with X.21 circuit switched
support. Code this operand at system generation time.
The $$X21 DS Connection Record Data Set
c'
You have an IBM-supplied one-record data set allocated on your IPL volume with the reserved
name $$X21DS. It contains no information. If you are using TYPE=DC, you can edit this data
set to create your own connection records. With TYPE=AC or SM, you can either create your
own connection records, or you can create and use the default record named X21RECyy, where
"yy" is the hexadecimal address of your attachment card. If you are specifying TYPE=SA
(auto answer), the system requires no connection record, but don't delete the $$X21DS data set
or X.21 will fail.
o
Chapter 1. Binary Synchronous Communications Access Method (BSCAM)
CO-49
Binary Synchronous Communications Access Method
(BSCAM)
o
Using X.21 Switched Network Support (continued)
Building a Connection Record
You can build as many connection records as you need. To format a connection record, use the
$FSEDIT utility or option 1 of the session manager. (For information on the $FSEDIT utility
and the session manager, refer to the Operator Commands and Utilities Reference.)
Every connection record that you build MUST begin in column 1. Figure 24 shows the format
for each connection record, followed by an explanation of each field.
Columns:
72
10
Name
Retry count
Delay value
Network information field
1-8 characters
0-3 characters
0-5 characters
0-61 characters
Figure 24. Connection Record Format Fields
•
Name - a 1 to 8 alphanumeric character name. The system uses this record name to
identify the connection record it should use for a particular request. If you are going to use
the default record with auto call (AC or SM) or direct call (DC), one of your record names
must be X21RECyy (where yy is the hex address of the 2080 card).
•
Retry Count - decimal number from 0 to 255 to indicate the maximum number of times the
system should retry this same request. This field MUST begin in column 10. Use a comma to
separate this field from the delay value field. If you use a comma by itself, the number of
retries defaults to 1.
•
Delay Value - decimal number from 0 to 65535 to indicate (in milliseconds) the time
between the receipt of an error status from a call and the time when the network should
reissue that call. Use a comma to separate this field from the network information field. If
you use a comma by itself, the delay time defaults to 0 milliseconds.
Network Information Field - up to 61 characters for a total record length of 72. This field
contains your facility requests and the address selections the network should use for a call
request. All information in this field must conform to the requirements of your network,
including all special characters. (Refer to the network information technical report for your
country to find this information.) If you have specified DC (direct call), the network will
not use this field, but it will use the name, retry, and delay fields. Neither the hardware nor
the software verifies that the data in the network information field is valid.
o
CO-50
SC34-0638
o
Using X.21 Switched Network Support (continued)
The following example shows a sample connection record data set. The fourth sample record,
X21 RECOA, illustrates the default record. Its retry count is 2 and its delay value is 1. You have
to fill in the network information field with valid data for your country. The last sample record,
GEORGE, is an example of a connection record for DC (direct call); no network information is
needed for DC.
Example: A connection record data set.
CONNREC1
CONNREC2
CONNREC3
X21RECOA
GEORGE
255,65000,NETWORK INFORMATION GOES INTO THIS FIELD
156,100,01234567+
,,01234567890+
2,1,0123456789012345+
25,255,
Convert BSC Program for X.21
The only change you need to make for BSC programs to run with X.21 is to code the X21RN
operand on the BSCOPEN instruction in your program if you want the system to use your own
connection records. (Refer to Language Reference for further coding information.)
If you are using auto call (AC or SM) and you don't code X21 RN, X.21 will look for the default
record named X21 RECyy, where yy is the hexadecimal address of your attachment card. As
stated earlier, you must insert X21RECyy into the $$X21DS data set. However, if you specify
DC and you don't code X21RN, the retry and delay values default to 1 and 0 respectively.
Figure 25 shows a coding example for the BSCOPEN statement. For example, if you name your
connection record "CONNRECl," the BSCOPEN statement contains the pointer, X21RN, to
that record.
Note: In the DC statement below, if your record name has fewer than 8 characters, it's a good
idea to pad the name with blanks to equal 8 characters in length.
label
recrdptr
BSC:rOC!?',·X2.1 RN~Tecrdptr
c18 'CONNREC1' member name
Figure 25. X.21 BSCOPEN Coding Example
o
Chapter 1. Binary Synchronous Communications Access Method (BSCAM)
CO-51
Bin-ary Synchronous Communications Access Method
(BSCAM)
Using X.2rSwitched Network Support (continued)
o
X.21 Error and Call Progress Signal logging
You should activate $LOG when using X.21 circuit switched support. Then use the LL or LP
command of the $DISKUT2 utility to list your error log record. The system will tell you when you
have an X.21 switched error. Then you need to check the error log record to determine what
the error is.
Figure 26 shows an example of the printed output created by the $DISKUT2 utility when you
have X.21 circuit switched support. In this case, the X.21 return code field (word 19) equals-9
(FFF7), indicating a read instruction error. An explanation of the numbered items follows the
example.
..
COMMAND ( ?): LL
LOG DS NAME: LOGDS
B
DEVICE ADDRESS (NULL FOR ALL): 0002
I/O LOG ERROR COUNTERS (BY DEVICE ADDR):
REQUESTED HEX DUMP OF LOG RECORD:
_II
0000
~OO
0010
0000 0000 0000 0000 0002 02DO 0402 8000
0020
0030
0040
0050
0060
0070
0080
0090
OOAO
OOBO
OOCO
OODO
OOEO
OOFO
0000 0055 7EOO 0000 0222 0000 0000
II
II II
FFFF 0005 FFF7
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
(r~
I,
"'t
:I
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
LOG LISTING ENDED
Figure 26. Example of the X.21 Printed Log Information for a Read Error
o
CO-52
SC34-0638
o
Using X.21 Switched Network Support (continued)
. . This is the name of the log data set you created with $LOG. In this example, the log data
set is LOGDS.
II
This is what you will see on the usual log information. The dots (.) replace the list of device
addresses and I/O error indications that $DISKUT2 provides. These device addresses range
from X'OO'to X'FF', or 0 to 255.
II
This is the start of your X.21 log record output. The first 28 bytes contain the log header
information that is reserved for system use.
II
This byte contains the X.21 record type, X'04'. It marks the beginning of the X.21
statistical log.
II
This byte contains your device address, in this case X'02'.
II
This word contains the X.21 error flags reserved for system use. In this case, it indicates
that there are X.21 log entries.
II
This word indicates that there is a read instruction error when equivalent to -1 (FFFF hex).
Refer to this byte only when the word indicated by II equals -9 (FFF7 hex).
EJ
This word contains the error return code from the read instruction. Refer to this word only
when the word indicated by II equals -9 (FFF7 hex). (Refer to Messages and Codes for the
meanings of these error codes.)
II When this word equals -9 (FFF7 hex), you must consult the two words indicated by
II and EJ· In this case, the remainder of the log record will contain zeroes.
o
Chapter 1. Binary Synchronous Communications Access Method (BSCAM)
CO-53
Binary Synchronous Communications Access Method
(BSCAM)
Using X.21 Switched Network Support (continued)
o
Figure 27 shows a second example of the printed output created by $DISKUT2 when you have
X.21 circuit switched support. In this case, the X.21 return code field (word 19) equals -27
(FFES) and indicates a device error. An explanation of the numbered items follows the
example.
..
COMMAND(?): LL,
LOG DSNAME: LOGDS
II
DEVICE ADDRESS (NULL FOR ALL): 0002
I/O LOG ERROR COUNTERS (BY DEVICE ADDR):
REQUESTED HEX DUMP OF LOG RECORD:
0000
~OO
0010
0000 0000 0000 0000. 0002 02DO
0000 0055 7EOO 0000 0222 0000 0000
II
FFE5
-
~11c10
0020
0000 0000
03FA 0000 0000 0000 0000
0030
0040
0050
0000 0000 0000 0000 0000 0000 0002 0000
0000 0000 0000 0000 0000 0000 0000 0000
0000 0000 00000000 0000 0000 0000 0000
0060
0070
0000 0000 0001 0000 0000 0000 0000 0000
0000 0000 0000 0000 0000 0000 0000 0000
0080
0090
OOAO
OOBO
OOCO
OODO
OOEO
OOFO
0000
0000
0000
0000
0000
0000
0000
0000
IE
~\,
!
',?
III
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
001
0600
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
LOG LISTING ENDED
Figure 27. Example of the X.21 Printed Log Information for a Device Error
o
CO-54
SC34-0638
o
Using X.21 Switched Network Support (continued)
. . This is the name of the log data set you created with $LOG. In this example, the log data
set is LOG DS.
II
This is what you will see on the usual log information. The dots (.) replace the list of device
addresses and I/O error indications that $DISKUT2 provides. These device addresses range
from X'OO'to X'FF', or 0 to 255.
11
This is the start of your X.21 log record output. The first 28 bytes contain the log header
information that is reserved for system use.
II
This byte contains the X.21 record type, X'04'. It marks the beginning of the X.21
statistical log.
II
This byte contains your device address, in this case X'02'.
II
This word contains the X.21 error flags reserved for system use. In this case, it indicates
that there are X.21 log entries, and that a device error has occurred.
II
This word is the X.21 return code field. When it equals -27 (FFE5 hex), consult the device
error code field ( II).
II
c
This byte shows you how many times the call was retried before it failed. In this case, the
retry count equals 3.
II
This byte will give you the device error code, in this case -6 (FA hex). Use the data in this
byte only when the word indicated by II equals -27. The error codes are as follows:
/..:,:.:'.' .... ;.;
DEVI:0EERROR CODES
:~:::-~1 :(FF)
Buffer9ye;t:'run. '. . '
--2 (FE)
UnSuQcessfulDCEcleitr •.. . , ..... .
,...3 (FD)
Tnterface code
~5 (FB)
lriv:alid inte~rupt statu~'by;t~
__ 6 (FA)
•... Inv:alid . I!Ocop.dLt,:ioncode
--7 {F9)
. Start cycle stea·l status issued
.:;/~,8 (FS):
;,~:peQificat.io.:ri. ch~.ck> .
Figure 28. Device Error Codes
Note: Refer to the hardware manual IBM Series/l Communications Theory Diagrams,
SY34-0059, for the meanings of these messages.
o
Chapter 1. Binary Synchronous Communications Access Method (BSCAM)
CO-55
Binary Synchronous Communications Access Method
(BSCAM)
Using X.21 Switched Network Support (continued)
o
The next 100 bytes (00 to 99) are the call progress signal counters. They record call progress
signals and hardware errors. The following example shows the meaning of the significant bytes.
The number within the byte indicates how many times the error occurred. For example, II
shows you a call progress signal of 21 because it's the 21st. byte after II; the number 02 within
the byte tells you that it occurred twice. III shows you a call progress signal 61 because it's the
61st. byte after II; the number 01 within the byte tells you that it occurred once. The byte
number column gives the byte number relative to the beginning of the log ( II ).
Call
progress
signal
Byte
number
Meaning of signal
What X.21 does
00
01
02
03
28
29
2A
28
Reserved
Terminal called
Redirected call
Connect when free
Does not clear. Waits for attempt to
complete.
20
21
22
23
3C
3D
3E
3F
No connection
Number busy
Selection signals procedure error
Selection signal transmission error
Clears due to short-term conditions.
Tries again up to retry limit.
41
42
43
44
45
46
47
48
49
51
52
51
52
53
54
55
56
57
58
59
58
5C
Access barred
Changed number
Not obtainable
Out of order
Controlled not- ready
Uncontrolled not-ready
DCE power off
Invalid facility request
Network fault in local loop
Call information service
Incompatible user class of service
Clears due to long-term conditions.
Call unsuccessfully completed.
61
65
Network congestion
Clears due to network short-term
conditions. Tries again up to retry
limit.
71
72
6F
70
Long-term network congestion
RPOA out of order
Clears due to long-term network
conditions. Call unsuccessfully
completed.
81
82
83
79
7A
78
Registration / cancellation confirmed
Redirection activated
Redirection deactivated
Clears due to DTE network
procedure.
(-\:
\~--_/
Figure 29. CaD Progress Signal Counter Usage
IE
This byte marks the end of the statistical log.
o
CO-56
SC34-0638
o
Chapter 2. Remote Management Utility ($RMU)
When the Remote Management Utility ($RMU) is loaded on a Series/I, it allows another
system, called the host, to control the Series/1. The Series/l with $RMU loaded on it is called
the remote system.
o
The host starts and controls functions that $RMU performs on the remote system. $RMU waits
for an application program running on the host to ask it to perform some function, and then
does the work. No operator action at the remote system is needed. $RMU sends responses to
the host that tell if it completed the function successfully, and to provide other information
about the function.
The $RMU-controlled (remote) system is always a Series/l. The host system can be a
Series/I, too. This chapter talks about the host system being a Series/I. It tells how to write
host programs to communicate with $RMU. The Binary Synchronous Communications Access
Method (BSCAM) controls I/O during $RMU operations. Because of this, $RMU operation
requires the use of binary synchronous communication (BSC) lines. In addition, the host
program must consist of Event Driven Language BSC instructions and must follow rules for
BSCAM programs in general.
If your Series/l is the Host system making requests of another Series/I, then you must write
the application programs that send requests to $RMU.
o
Chapter 2. Remote Management Utility ($RMU)
CO-57
Remote Management Utility ($RMU)
Your host program can ask $RMU to perform the following functions:
c
Manage data sets on the remote system
ALLOCATE function
DELETE function
DUMP function.
Transfer data between the two systems
SEND function
RECEIVE function
WRAP function.
Control the running of programs on the remote system
EXEC function
SHUTDOWN function.
Establish interactive sessions between the two systems
•
P ASSTHR U function.
Verify the IDs of the two systems
-
IDCHECK function.
If your Series/lis the remote system, there is no work that you must do to respond to host
requests, since the utility takes care of that automatically. However, before $RMU operations
can begin, you must load the utility into your system with the command $L $RMU. The only
other work that can be done at the remote system is changing $RMU default values. The
section, "Remote Management Utility Defaults" on page CO-62 tells about these values and
how to change them.
Figure 30 on page CO-59 shows how the host and remote systems communicate by means of
the host program and $RMU.
·-·-"~··
C
,.)
CO-58
SC34-0638
0
/!
1
Host
system
Series/1
.'
Host
program
$RMU
Figure 30. Communication Between Host and Remote Systems
o
Planning for the Remote Management Utility Operations
Types of Line Connections
$RMU operations can take place over several types of BSC line connections.
The host and remote systems can be connected on either point-to point or multipoint lines
during $RMU operations. Point-to-point connections can be over leased or switched lines,
depending on which type of service you have bought from the common carrier. Multipoint
connections require the host system to be the control station and the remote system to be a
tributary station. Remember, $RMU operates in point-to-point only for X.21.
Find out what type of line connection your Series/lis part of, and whether it is acting as the
host or the remote system. Keep this information in mind since you will use it in other areas of
planning for $RMU operations.
o
Chapter 2. Remote Management Utility ($RMU)
CO-59
Remote Management Utility ($RMU)
Planning for the Remote Management Utility Operations (continued)
Mode of Transmission
o
Transmissions during $RMU operations are in transparent mode. Although BSCAM, which
controls I/O for $RMU, supports other modes of transmission, only the transparent mode is
available with $RMU. This is important when you write host programs to send requests to
$RMU.
Storage Considerations
$RMU needs a maximum of 7.25K bytes of storage, plus buffer space, to perform all its
functions. However, $RMU can perform its data set management functions with only 5.5K
bytes of storage. In that case, $RMU gets any additional storage it needs from the partition in
which it is executing.
The section, "Remote Management Utility Defaults" on page CO-62 tells how to use the
reduced storage size and how to change it.
Remote System Requirements
For $RMU operations the remote Series/l must meet certain hardware and software
requirements.
Hardware Requirements
Minimum hardware requirements for the remote Series/l are as follows:
Processor: 4952, 4954, 4955, or 4956.
Storage: must be sufficient to handle the supervisor, $RMU (maximum of 7.25K bytes), and
the programs that run under $RMU (see notes).
•
BSC Hardware Connection Features: must be one of the following:
single-line control, medium speed
single-line control, high speed
8-line control and one or two 4-line adapters
multifunction attachment.
•
Disk or Diskette: 4962, 4963, or 4967 (disk); 4964,4965, or 4966 (diskette).
o
CO-60
SC34-0638
o
Planning for the Remote Management Utility Operations (continued)
Notes:
1. The section "Storage Considerations" on page CO-60 tells you how $RMU uses storage.
2. For additional information on storage considerations, refer to the Installation and System
Generation Guide.
Software Requirements
Since the Binary Synchronous Communications Access Method (BSCAM) controls the transfer
of data during $RMU operations, the system generation for the remote Series/1 must include
one BSCLINE statement per copy of $RMU you plan to use. You must define each BSC line to
be used by $RMU as either a point-to-point (BSCLINE TYPE=PT, SM or SA), or multipoint
tributary station (BSCLINE TYPE=MT). You must include enough storage to accommodate
$RMU and the programs that run under it in the partition where you plan to load it.
If you plan to set up P ASSTHRU sessions between the remote Series/l and the host, $RMU
requires two virtual terminals. You must include two TERM IN AL statements in your system
generation. On one statement, code the parameter ADDRESS=CDRVTA, and on the other,
code ADDRESS=CDRVTB. These are the only addresses that are valid.
You must also include support for the BSCAM supervisor module.
o
Refer to the Installation and System Generation Guide for details on performing system
generation.
Host System Requirements
In this discussion, the host system is a Series/I. It too must meet certain requirements to
successfully communicate with $RMU. The following support must be defined during system
generation for the host Series/I:
BSCLINE TYPE=PT, SM, SA, or MC
•
BSCAM supervisor module support.
Besides the Series/I, the host can be any system that meets these requirements:
•
provides binary synchronous protocol compatible with BSCAM
•
transmits in transparent EBCDIC
supports the form of record exchange that $RMU performs.
o
Chapter 2. Remote Management Utility ($RMU)
CO-61
Remote Management Utility ($RMU)
Planning for the Remote Management Utility Operations (continued)
o
Remote Management Utility Defaults
Certain values associated with $RMU operations have predefined defaults. These default values
are:
Host system ID is set at HOSTRMUX.
•
Remote system ID is set at REMTRMUX.
•
BSC line is set at X'09'.
•
$RMU storage size is set at 7.25 K bytes.
•
Buffer size is set at 1024 bytes.
At the remote system, you can modify these default values by using the $DISKUT2 utility. This
utility allows you to get at main storage for $RMU and patch your changes.
After you load the $DISKUT2 utility, respond to its prompts to make changes to the default
values. In general, the utility prompts for the following information:
a $DISKUT2 command
the storage address containing the default value
type of code the default value is in
new data to replace the default value.
The storage addresses listed in this book are subject to change. Consult the PID directory for
the latest storage addresses for $RMU.
The sections that follow tell what information to enter to change each of the defaults.
o
CO-62
SC34-0638
o
Planning for the Remote Management Utility Operations (continued)
Changing Host System 10
The default value for the host system ID (used in the IDCHECK function) is HOSTRMUX.
You can change this to another name if you wish. In response to the utility's prompts, enter the
following information:
•
Command: P A $RMU
Address: 0864 (*)
Code type: E (for EBCDIC)
Data: the new host system ID (8 characters).
* The address listed for the host system ID is subject to change. Consult the PID directory for
the latest storage addresses for this default value.
Changing the Remote System 10
The default value for the remote system ID (used in IDCHECK function) is REMTRMUX.
You can change this to another name if you wish. In response to the utility's prompts, enter the
following information:
c
•
Command: P A $RMU
•
Address: 085C (*)
•
Code type: E (for EBCDIC)
Data: the new remote system ID (8 characters).
* The address listed for the remote system ID is subject to change. Consult the PID directory
for the latest storage addresses for this default value.
()
Chapter 2. Remote Management Utility ($RMU)
CO-63
Remote Management Utility ($RMU)
Planning for the Remote Management Utility Operations (continued)
Changing the BSC Line Address
o
The default value for the BSC line address is X'09'. You can change this to another line address
if you wish, but if you do, make sure that the BSC line definitions for the remote system (made
during system generation) reflect the change. In response to the utility's prompts, enter the
following information:
•
Command: PA $RMU
Address: 086E (*)
•
Code type: H (for hexadecimal)
Data: new BSC line address.
* The address listed for the BSC line address is subject to change. Consult the PID directory for
the latest storage addresses for this default value.
Changing Storage Size
The default value for storage required by $RMU is 7.25K bytes. However, you can change the
size of storage from 7.25 to 5.5K bytes. In response to the utility's prompts, enter the following
information:
•
Command: SS $RMU
New Storage Size in Bytes: nnnn, which specifies the new storage size.
o
CO-64
SC34-0638
o
Planning for the Remote Management Utility Operations (continued)
Changing Buffer Size
The default value for buffer size on the remote system is 1024 bytes. You can change buffer
size within the minimum value of 512 and the maximum value of 32,512 bytes. Buffer size
should be in multiples of 256. In addition, buffer size depends on the size of the blocks $RMU
is storing in the buffer. Two factors determine the size you should change buffer size to:
•
data set type to be stored in the buffer
•
number of blocks sent in each record, according to data set type.
First decide what data set type you will be storing in the buffer.
•
Standard data set - meant to contain standard data
•
Source data set - meant to contain source data
•
PASSTHRU data set - meant to be used in a PASSTHRU session.
Now determine the blocking factor for your type of data set. The blocking factor refers to the
number of logical records contained in each block of data. If you want to send a certain number
of records in each block, then your buffer must be able to accommodate those records. The
calculations to determine blocking factor are described in the sections that follow.
Determining Blocking Factor for Standard Data Sets: To determine the blocking
factor for a standard data set, make the following calculation:
(buffer size - 6) / 256
= blocking factor
Discard the remainder.
For example, assume a buffer size of 768 (256 x 3); subtract 6 to get the value 762. Divide 762
by 265; the quotient is 2. Discard the remainder. The blocking factor is 2.
o
Chapter 2. Remote Management Utility ($RMU)
CO-65
Remote Management Utility ($RMU)
Planning for the Remote Management Utility Operations (continued)
Determining the Blocking Factor for Source Data Sets: To determine the blocking
o
factor for a source data set, make the following calculation:
(buffer size - 262) / 80
= blocking factor
Discard the remainder.
For example, assume a buffer size of 2048 (256 x 8); subtract 262 to get the value 1786.
Divide 1786 by 80; the quotient is 22. Discard the remainder. The blocking factor is 22.
Determining Blocking Factor for PASSTHRU Data Sets: To determine the blocking
factor for a PASSTHRU data set, make the following calculation:
buffer size - 264 = blocking factor
Discard the remainder.
For example, assume a buffer size of 512 (256 x 2); subtract 264. The result is 248. The
blocking factor is also 248.
To change the buffer size, enter the following information in response to the utility's prompts:
•
Command: PA $RMU
Address: 0892 (*)
Data: nnnn, which specifies the new buffer size.
* The address listed for the buffer size is subject to change. Consult the PID directory for the
latest storage addresses for this default value.
Host Programming for the $RMU Application
If your Series/lis acting as the host, you must write application programs to communicate with
$RMU on the remote Series/I. Your program sends requests to $RMU and receives responses
from $RMU.
Using Event Driven Language
sse Instructions
Since BSCAM controls transmissions between the host and remote systems, your host program
must contain EDL BSC instructions. To send requests, code BSCWRITE instructions, and to
receive $RMU's responses, code BSCREAD instructions.
You may want to review BSCAM programming techniques before going further with
programming for the $RMU application. Chapter 1 contains information on BSCAM
programming using the BSC instructions.
CO-66
SC34-0638
o
o
Host Programming for the $RMU Application (continued)
Since $RMU transmissions are in transparent mode, the BSC write instructions in your program
must be of the transparent type. For example, to send a request, code a BSCWRITE IX (initial
transparent write). To signify the end of a request, code a BSCWRITE E instruction. To send
data, code BSCWRITE IX for the first record and BSCWRITE CX (continue transparent write)
for subsequent records.
To review the syntax of the BSC instructions, refer to the Language Reference.
Receiving $RMU's Responses to Host Requests
During the course of performing any function, $RMU sends various types of messages to the
host. These messages provide the following information to the host:
•
Status messages that indicate success or failure of a function
•
Count messages that show the number of records sent or received by $RMU
•
Data messages that $RMU uses to send data.
All of these messages start with three fields that make up the header, as shown below:
c
•
RMHBSCC contains the BSC control characters DLE STX.
•
RMHID identifies a message from $RMU.
•
RMHTYP identifies the type of message: 'S' for status, 'C' for count, or 'D' for data.
Status Message
$RMU sends a status message to the host to indicate the success or failure of a requested
function. A status record is 18 bytes in length. Besides the three fields that make up the
header, it contains several fields that provide the following information:
•
RMSREQ specifies the request that the status message pertains to. For example, if it is in
response to an allocate request, the RMSREQ field shows the value 2, which represents the
allocate request.
•
RMSFN indicates the success or failure of the particular request. This field contains a -1 to
indicate the success of a request. Any other value (a positive value) indicates failure of the
request. The number refers to a specific error condition, as shown in the chart below:
o
Chapter 2. Remote Management Utility ($RMU)
CO-67
Remote Management Utility ($RMU)
Host Programming for the $RMU Application (continued)
Status
Code
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
21
22
24
25
26
27
31
32
33
34
41
Condition
IDCHECK Function Failed
Buffer area is too small for the record
Short record (less than 4 bytes)
Header ID is 'H' (invalid)
Invalid header ID (not 'X' or' H')
Request expected
Invalid request
Request short (missing information)
Invalid SEND/RECEIVE type
Invalid blocking factor
Invalid message received during request
Invalid PASSTHRU record type
Invalid DUMP partition number
Request received while another was running
EOT expected and not received
Virtual terminal busy
READ disk/ diskette failed
WRITE disk/ diskette
Load failed
Load of overlay failed
BSC I/O failure
PRINTEXT failed for virtual terminal
ALLOCATE/DELETE failed
OPEN failed
SETEOD failed
Parameters to build LOAD instructions are invalid
Overlay function missing
Figure 31. $RMU Status Failure Codes
RMSST appears when the number in RMSFN indicates that an Event Driven Executive
function failed. This field appears in a status message only if one of the following numbers
appears in the RMSFN field:
21 or 22: contains disk (READ/WRITE) return code
24 or 25: contains LOAD return code
26: contains BSC (binary synchronous communications) return code
27: contains virtual terminal I/O return code
31,32 or 33: contains $DISKUT3 return code
34: contains LOAD return code.
For explanations of the return codes, refer to the Messages and Codes.
•
CO-68
SC34-0638
RMSRID appears only in the status message of a successful IDCHECK request. It specifies
the ID of the remote Series/I.
o
o
Host Programming for the $RMU Application (continued)
Count Message
$RMU sends a count message to the host when it detects an end-of-data condition during a data
set transfer (from either a SEND or RECEIVE request). This message shows the number of
records that $RMU sent. The count message also indicates if records were padded (blanks
inserted) during the data set transfer. The host should use the count message to verify whether
a complete data transfer occurred. For example, if the host program sent 30 messages, then the
count message from $RMU should indicate that the utility received 30 messages.
The count message can be up to 12 bytes long. Besides the header, it contains several fields that
provide the following information:
= SEND, 1 =
•
RMCREQ identifies the request type that the count message pertains to (0
RECEIVE).
•
RMCFLG indicates if record padding occurred during a data set transfer. A value of '1' in
this field indicates padding; a value of '0' indicates no padding.
RMCCNT specifies the number of records transmitted. This number reflects the number of
logical records (80-byte or 256-byte) that $RMU transmitted, regardless of how the records
were blocked.
Data Message
o
$RMU sends data messages to transmit data to the host in response to a SEND request. This
type of message contains the 80-byte or 256-byte records from the data set specified in the
SEND request.
Besides the header, the data record contains the field RMDDATA. RMDDATA contains the
data that $RMU is sending to the host. The length of this field will be a multiple of 80 or 256,
depending on the specifications of the host in its SEND request.
Error Handling During $RMU Operations
If a communications error occurs while $RMU is executing, the terminal that loaded $RMU (on
the remote system) receives an error message. If a communications error occurs while $RMU is
performing a function, it generally terminates. However, the SEND, RECEIVE, and
P ASSTHRU functions may continue executing because these functions require multiple message
exchanges between the host and the Series/1 before the function is complete. If the error is
recoverable, $RMU sends the host a status record followed by a termination (EOT). After this
sequence of messages is over, the host can issue a new request.
()
Chapter 2. Remote Management Utility ($RMU)
CO-69
Remote Management Utility ($RMU)
Host Programming for the $RMU Application (continued)
Both $RMU and the host program can detect errors while an $RMU function is executing. If
$RMU detects such an error, it sends the host a status record indicating the error condition,
followed by an EOT to terminate the function. After this sequence is complete the host can
issue a new request. If the host program detects an error, it should terminate the function in the
same sequence as $RMU. However, the status record the host sends to the remote system
requires only the 4-byte header of a status record (RMHBSCC, RMHID, and RMHTYP fields).
o
$RMU detects errors during all phases of operations and sends failure status messages to the
host. Refer to "Status Message" on page CO-67 for details of these failure messages. Status,
count and data messages were discussed previously in "Receiving $RMU's Responses to Host
Requests" on page CO-67. The type and sequence of responses $RMU sends varies according
to the request type. The sections below, which tell how to code each type of request in a host
program, also show the way $RMU responds to each request.
You must code a BSCREAD instruction to receive each of $RMU's responses to a request. To
receive $RMU's first response to a request, code a BSCREAD I (initial read) instruction. To
receive the rest of $RMU's responses, code BSCREAD C (continue read) instructions.
Coding the Required Field for Requests to $RMU
For each request the host sends to $RMU, you must code certain fields of information in your
program. Each set of fields identifies a different type of request, and tells $RMU exactly what
the host wants it to do.
The sections that follow identify the required fields for each type of request and show what
information to enter in each field.
Managing Disk/Diskette Data Sets
The host can ask $RMU to work with disk or diskette data sets on the remote system. The three
such functions that $RMU can perform are:
ALLOCATE a disk or diskette data set
DELETE a disk or diskette data set
DUMP storage to a disk or diskette data set.
o
CO-70
SC34-0638
o
Host Programming for the $RMU Application (continued)
Allocating Disk/Diskette Data Sets (ALLOCATE)
The host can ask $RMU to allocate a disk or diskette data set on the remote system with the
ALLOCATE request. The data set can contain either standard data or a program.
To send $RMU your ALLOCATE request, code a BSCWRITE IX instruction along with the
required information fields. Then code a BSCWRITE E or EX instruction to signify that you
are finished sending the ALLOCATE request.
After $RMU gets the host's ALLOCATE request, it sends a status message. Code a
BSCREAD I instruction to receive this message. After performing the requested function, or
after encountering a failure condition, $RMU terminates the function by sending an EOT (endof -transmission) sequence to the host. Code a BSCREAD C instruction to receive the notice of
termination.
IMPORTANT: The ALLOCATE function uses the $DISKUT3 utility. Do not allocate a data
set named $EDXNUC, $$EDXVOL, or $$EDXLIB.
Allocating a Program Data Set: If you are going to allocate a data set that is to contain a
program from the host system, you must have the following information available:
o
•
The load address of the program
•
the size (in bytes) of the program
•
the entry point of the program
•
the RLD (relocation dictionary) count of the program.
Obtain the information by opening the host program data set and examining the data set control
block.
o
Chapter 2. Remote Management Utility ($RMU)
CO-71
Remote Management Utility ($RMU)
Host Programming for the $RMU Application (continued)
Coding the Required Fields for ALLOCATE
o
The chart that follows shows all the fields to code in your program for an allocate request. The
fields identified with an asterisk (*) contain variable values. You can code any appropriate
value in these fields. However, the other fields can contain only the values shown in the chart.
Code these fields exactly as the chart specifies.
Field
Size,
Type
Explanation
What to Code
RMHBSCC
2 hex
Starts transmission of a request
RMHBSCC DATA X'1002'
RMHID
1 alpha
Identifies message to $RMU
RMHID DATA C'X'
RMHTYP
1 alpha
Identifies request to $RMU
RMHTYP DATA C'R'
RMREQ
2 num
Specifies ALLOCATE request
RMREQ DATA F2'
RMADSN (*)
8 alpha
Name of the data to be allocated
RMADSN DATA CL8'DATASET
RMAVOL (*)
6 alpha
Name of the volume containing
data set. Default = IPL volume.
RMAVOL DATA CL6'VOLUMF
RMANREC (*)
4 num
Number of 256-byte records
allocated for data set
RMANREC DATA D'nn'
RMADST (*)
2 num
Type of data set allocated (1
3 = program)
RMALAD (*)
2 num
Load address of program data set
(see note)
= data;
RMADST DATA Fn'
RMALAD DATA Fnn'
Figure 32 (Part 1 of 2). Required Fields for ALLOCATE Request
o
co- 72
SC34-0638
o
Host Programming for the $RMU Application (continued)
Field
Size.
Type
Explanation
What to Code
RMAPSZ (*)
2 num
Program size in bytes (see note)
RMAPSZ DATA Fnn
RMAENT (*)
2 num
Program entry point (see note)
RMAENT DATA Fnn'
RMARLD (*)
2num
RLD count of program (see note)
RMARLD DATA Fnn'
Figure 32 (Part 2 of 2). Required Fields for ALLOCATE Request
Note: The RMALAD, RMAPSZ, RMAENT and RMARLD fields are required only if the data
set you are allocating is a program. In this case, the RMASDT field must contain the value 3.
Figure 33 shows an example of the ALLOCATE function. The host requests a data set named
"MYDATA" to be allocated on volume "MYVOL." The data set type is 1 (data) and ten
256-byte records are allocated. $RMU sends a status record with -1 (successful completion) to
the host.
o
Figure 53 on page CO-I09 shows a sample program that can send an ALLOCATE request.
Chapter 2. Remote Management Utility ($RMU)
CO-73
Remote Management Utility ($RMU)
Host Programming for the $RMU Application (continued)
Host Program
Host
BSCWRITE IX
ENQ
------->
RMHBSCC DATA X'1002'
RMHID DATA C'X'
RMHTYP DATA C'R'
RMREQ DATA F'2'
RMADSN DATA CLS'MYDATA'
RMAVDL DATA CL6'MYVDL'
RMANREC DATA D'10'
RMADST DATA FT
RMALAD DATA FO'
RMAPSZ DATA FO'
RMAENT DATA FO'
RMARLD DATA FO'
TEXT
------->
BSCWRITE E
EDT
------->
o
Remote
<------- ACK*
<------- ACK*
<------- ENQ
ACK*
------->
<------- TEXT
BSCREAD I
(status)
RMHTYP='S'
RMSREQ=2
RMSFN=-1
ACK*
BSCREAD C
------->
<------- EDT
(termination)
Figure 33. Communications Flow for ALLOCATE
Deleting a Disk/Diskette Data Set (DELETE)
You can ask $RMU to delete a disk or diskette data set on the remote system with a DELETE
request.
To send $RMU your DELETE request, code a BSCWRITE IX instruction along with the
required information fields. Then code a BSCWRITE E or EX instruction to signify that you
are finished sending the DELETE request.
After $RMU gets the host's DELETE request, it sends a status message. Code a BSCREAD I
instruction to receive this message. After performing the requested function, or after
encountering a failure condition, $RMU terminates the function by sending an EaT (endof-transmission) sequence to the host. Code a BSCREAD C instruction to receive the notice of
termination.
IMPORTANT: The DELETE function uses the $DISKUT3 utility. Do not delete data sets
$EDXNUC, $$EDXVOL, and $$EDXLIB.
o
co- 74
SC34-0638
o
Host Programming for the $RMU Application (continued)
Coding the Required Fields for DELETE
The chart that f0110ws shows all the fields to code in your program for a delete request. The
fields identified with an asterisk (*) contain variable values. You can code any appropriate
value in these fields. However, the other fields can contain only the values shown in the chart.
Code these fields exactly as the chart specifies.
Field
Size,
Type
Explanation
What to Code
RMHBSCC
2 hex
Start of message
RMHBSCC DATA X'1002'
RMHID
1 alpha
Identifies message to $RMU
RMHID DATA C'X'
RMHTYP
1 alpha
Identifies request to $RMU
RMTYP DATA C'R'
RMREQ
2 num
Specifies DELETE function
RMREQ DATA F'3'
RMDDSN (*)
a alpha
Data set to be deleted
RMDDSN DATA CLa'DATASET
RMDVOL (*)
6 alpha
Volume containing data set to be
deleted. Default = IPL volume
RMDVOL DATA CL6'VOLUME'
o
Figure 34. Required Fields for DELETE Request
Figure 35 on page CO-76 shows an example of the DELETE function. The host specifies a
data set named "MYDATA" to be deleted from volume "MYVOL." $RMU sends a status
record with -1 (successful completion) to the host.
Figure 53 on page CO-I09 shows a program that can send a DELETE request.
o
Chapter 2. Remote Management Utility ($RMU)
CO-75
Remote Management Utility ($RMU)
Host Programming for the $RMU Application (continued)
Host Program
BSCWRITE IX
Host
ENQ ------->
RMHBSCC DATA X'1002'
RMHID DATA C'X'
RMHTYP DATA C'R'
RMREQ DATA F'3'
RMDDSN DATA CL8'MYDATA'
RMDVOL DATA CL6'MYVOL'
TEXT
------->
BSCWRITE E
EOT
------->
()
Remote·
<-------
ACK*
<------- ACK*
<-------
ENQ
------->
<------- TEXT
ACK*
BSCREAD I
(status)
RMHTYP='S'
RMSREQ=3
RMSFN=-1
ACK*
BSCREAD C
------->
<------- EOT
(termination)
Figure 35. Communications Flow for DELETE
Dumping Storage to a Disk/Diskette Data Set (DUMP)
You can ask $RMU to dump a storage partition to a disk or diskette data set on the remote
system with a DUMP request.
To send $RMU your DUMP request, code a BSCWRITE IX instruction along with the required
information fields. Then code a BSCWRITE E or EX instruction to signify that you are finished
sending the DUMP request.
After $RMU gets the host's DUMP request, it sends a status message. Code a BSCREAD I
instruction to receive this message. After performing the requested function, or after
encountering a failure condition, $RMU terminates the function by sending an EOT
(end-of-transmission) sequence to the host. Code a BSCREAD C instruction to receive the
notice of termination.
Coding the Required Fields for DUMP
The chart that follows shows all the fields to code in your program for a dump request. The
fields identified with an asterisk (*) contain variable values. You can code any appropriate
value in these fields. However, the other fields can contain only the values shown in the chart.
Code these fields exactly as the chart specifies.
( "';\
CO-76
SC34-0638
o
C'
Host Programming for the $RMU Application (continued)
Field
Size,
Type
Explanation
What to Code
RMHBSCC
2 hex
Start of transmission
RMHBSCC DATA X'1002'
RMHID
1 alpha
Identifies message to $RMU
RMHID DATA C'X'
RMHTYP
1 alpha
Identifies request to $RMU
RMHTYP DATA C'R'
RMREQ
2num
Specifies DUMP request
RMREQ DATA F'4'
RMDPDSN (*)
a alpha
Name of the data set to dump to
RMDPDSN DATA CLa'DATASET'
RMDPVOL (*)
6 alpha
Volume containing dump data set.
Default = IPL volume
RMDPVOL DATA CL6'VOLUMF
(filler)
1 nla
Reserved field (unused)
RMDPPTN (*)
1 num
Partition to be dumped
DATA H'O'
RMDPPTN DATA H'n'
Figure 36. Required Fields for DUMP Request
Figure 37 on page CO-78 shows an example of the DUMP request. The host requests that
partition 1 be dumped to the data set "MYDATA" on volume "MYVOL." $RMU sends a
status record with -1 (successful completion) to the host.
Figure 53 on page CO-109 shows a sample program that can send a DUMP request.
o
Chapter 2. Remote Management Utility ($RMU)
CO-77
Remote Management Utility ($RMU)
o
Host Programming for the $RMU Application (continued)
Host Program
BSCWRITE IX
Host
ENO ------->
RMHBSCC DATA X'1002'
RMHID DATA C'X'
RMHTYP DATA C'R'
RMREO DATA F4'
RMDPDSN DATA CL8'MYDATA'
RMDPVOL DATA CL6'MYVOL'
DATA H'O'
RMDPPTN DATA H'1'
TEXT
------->
BSCWRITE E
EOT
------->
Remote
<------- ACK*
<------- ACK*
<------ACK*
ENO
------->
<------- TEXT
BSCREAD I
(status)
RMHTYP='S'
RMSREO=4
RMSFN=-l
ACK*
------->
BSCREAD C
<-------
EOT
(termination)
Figure 37. Communications Flow for DUMP
Controlling Data Transfers between Host and Remote Systems
Your host program can ask $RMU to perform functions involving data transiers. You can ask
$RMU to send data to your system or receive data from you. Also, you can send data to the
remote system and have $RMU echo it back to you.
The requests associated with these functions are:
•
RECEIVE data from the host
•
SEND data to the host
•
WRAP host data back to the host.
Host Sending Data to Remote System (RECEIVE)
You can ask $RMU to receive a host data set, and then put the data into a data set on the
remote system. This is the RECEIVE request.
The RECEIVE function requires a data set on the remote system in which to place the data. If
such a data set does not already exist on the remote system, you can allocate one with an
ALLOCATE request.
Send your RECEIVE request by coding a BSCWRITE IX instruction, along with the required
information fields.
CO-78
SC34-0638
o
Host Programming for the $RMU Application (continued)
Upon receiving the RECEIVE request, $RMU checks to see if it can handle the size of the
records to be sent. It then sends a status message to the host. A status message of -1
(successful completion) indicates the RECEIVE function will continue; otherwise it terminates.
After receiving a status message of -1, the host begins to send the data set to $RMU. The
record length of the data set should be a multiple of 256 or 80.
If $RMU receives a data record whose length is not a mUltiple of the specified length, it pads the
record with null bytes. For example, a record of 156 bytes will contain padding with 100 null
bytes, if 256 bytes is the specified length.
If $RMU receives a data record whose length is greater than the length specified on the request,
the RECEIVE function terminates with a status indicating "BSC I/O Failure" and BSC return
code 20 (wrong length record - long).
At the completion of the data set transfer, $RMU sends the host a count message to report the
number of host records it received. This message also indicates if any records were padded.
If the host is sending an empty data set, send one data record which contains no data (only the
4-byte header) and then end the transmission.
If an unrecoverable error occurs, such as a disk or diskette error, $RMU interrupts the host
o
transmission by sending an EOT (end-of-transmission) and a status message containing the
appropriate error code. $RMU terminates the RECEIVE function, and then waits for another
request from the host. The host should use the status record to determine the reason for failure.
The host can terminate the RECEIVE function at any time by sending a status message
followed by a BSCWRITE E instruction.
Specifying Data Set Type
You must specify what type of data set the host is sending. The field RMRTYP is where to
code this information. Enter one of the following values in this field:
•
0 for a standard data set with 256-byte records
•
1 for a source data set with 80-byte records.
Specifying Record Blocking
You must specify whether or not the host will send blocked records to $RMU. If the host is
going to send blocked records, you must specify the number of blocks in each record.
The RMRBLK field is where to code this information. Enter one of the following values in this
field:
•
'0' or '1' to specify no blocking
•
any other number to specify the exact number of blocks the host will send in a record.
o
Chapter 2. Remote Management Utility ($RMU)
CO-79
Remote Management Utility ($RMU)
Host Programming for the $RMU Application (continued)
()
Specifying the Starting Record
You must tell $RMU which record of the host data set will be the first to be received. For
example, you may want to start at the first record, or at any other record within the data set.
The field RMRSTR is where to code this information. If you enter the value '0' or '1', the host
will start sending at the first record. If you enter any other value, the host will start sending at
that particular record.
Coding the Required Fields for RECEIVE Request
The chart that follows shows all the fields to code in your program for a RECEIVE request.
The fields identified by an asterisk (*) contain variable values. You can code any appropriate
value in these fields. However, the other fields can contain only the values shown in the chart.
Code these fields exactly as the chart specifies.
Field
Explanation
What to Code
RMHBSCC
Size
Tvpe
2 hex
Starts the message
RMHBSCC DATA X'lOO2'
RMHID
1 alpha
Identifies a message to $RMU
RMHID DATA C'X'
RMHTYP
1 alpha
Specifies a request to $RMU
RMHTYP DATA C'R'
RMREQ
2 num
Specifies RECEIVE request
RMREQ DATA Fl'
RMRDSN (*)
8 alpha
Name of data set to receive host
data
RMRDSN DATA CLS'DATASET
RMRVOL (*)
7 alpha
Volume containing data set to
receive host data. Default=1 PL
volume
RMRVOL DATA CLS'VOLUMF
RMRSTR (*)
4num
Starting record of host data set
RMRSTR DATA D'n'
RMRTYP (*)
2 num
Type of host data set to be received
RMRTYP DATA Fn'
RMRBLK (*)
2 num
Specifies record blocking
RMRBLK DATA Fn
Figure 38. Required Fields for RECEIVE Request
Here is an example of a RECEIVE request sent by a host program. The host sends a data set
called "MYDATA" to volume "MYVOL" on the remote system.
o
CO-80
SC34-0638
o
Host Programming for the $RMU Application (continued)
Figure 54 on page CO-Ill shows a sample program that sends a RECEIVE request.
Host Program
Host
ENQ
------->
RMHBSCC DATA X'1002'
RMHID DATA C'X'
RMHTYP DATA C'R'
RMREQ DATA F1'
RMRDSN DATA CL8'MYDATA'
RMRVDL DATA CL6'MYVOL'
RMRSTR DATA 0'0'
RMRTYP DATA FO'
RMRBLK DATA F1'
TEXT
------->
BSCWRITE E
EDT
------->
ACK*
------->
BSCWRITE IX
Remote
BSCREAD I
<------- ACK*
<------- ACK*
<-------
ENQ
<------- TEXT
(status)
RMHTYP='S'
RMSREQ=1
RMSFN=-1
ACK*
------->
BSCREAD C
ENQ
C
BSCWRITE IX
RMHBSCC DATA X'1002'
RMHID DATA C'X'
RMHTYP DATA C'D'
RMDDATA DATA C text
------->
TEXT
------->
<-------
EOT
<------- ACK*
<------- ACK*
BSCWRITE C
RMHBSCC DATA X'1002'
RMHID DATA C'X'
RMHTYP DATA C'D'
RMDDATA DATA C text
BSCWRITE E
TEXT
EDT
------->
------->
ACK*
------->
BSCREAD I
<------- ACK*
<-------
ENQ
<------- TEXT
(count)
RMHTYP='C'
RMREQ=1
RMCNT=2
ACK*
BSCREAD C
------->
<-------
EDT
Figure 39. Communications Flow for RECEIVE
o
Chapter 2. Remote Management Utility ($RMU)
CO-81
Remote Management Utility ($RMU)
Host Programming for the $RMU Application (continued)
Remote System Sending Data to Host (SEND)
o
You can ask $RMU to send a remote system data set to the host with the SEND request.
Send this request by coding a BSCWRITE IX instruction, along with the required information
fields. Upon receiving request, $RMU first checks that it can send the requested records. It
then sends a status record to indicate its ability to perform the function. A status record of -1
(successful completion) indicates the SEND function will continue; otherwise it terminates.
If $RMU is sending a program data set to the host, it also sends the program's RLD count, the
program size in bytes, the program entry point and the program load address.
After transmitting the last data record of the data set to the host, $RMU sends a count message
to indicate the number of records it sent the host. The host should compare this number to the
number of records it received to verify that it got all the records $RMU sent. The RMCFLG
field of the count message is not used for the SEND function.
If an unrecoverable error occurs, such as a disk or diskette read error, $RMU sends the host a
status message with the appropriate error code, and terminates the SEND function. The host can
terminate the SEND function by coding a BSCWRITE E instruction, followed by a status
message and another BSCWRITE E.
Specifying the Starting Record: You must tell $RMU to start sending data from a
particular record in the data set. For example, you may want it to start at the first record or at
any other record within the data set.
The RMSSTR field is where to code this information. If you enter the value '0' or ' l' in this
field, $RMU starts sending the first record in the data set. If you enter any other number,
$RMU starts sending from that particular record.
Specifying Data Set Type: You must tell $RMU what type of data set to send. The
RMSTYP field is where to code this information. Enter one of the following values in this field:
'0' for a standard data set with 256-byte records
•
'1' for a source data set with 80-byte records.
Specifying Record Blocking: You must tell $RMU whether or not to block the records it
sends. If you want $RMU to block the records, you must specify the number of blocks in each
record.
The RMSBLK field is where to code this information. Enter one of the following values in this
field:
•
'0' or '1' to specify no blocking
•
any other number to specify the exact number of blocks for $RMU to send in one record.
o
CO-82
SC34-0638
o
Host Programming for the $RMU Application (continued)
Coding Required Fields for SEND Function
The chart that follows shows all the fields to code in your program for a SEND request. The
fields identified with an asterisk (*) contain variable values. You can code any appropriate
value in these fields. However, the other fields can contain only the values shown in the chart.
Code these fields exactly as the chart specifies.
o
Field
Size
Type
Explanation
What to Code
RMHBSCC
2 hex
Starts the message
RMHBSCC DATA X'1002
RMHID
1 alpha
Identifies a message to $RMU
RMHID DATA C'X'
RMHTYP
1 alpha
Identifies a request to $RMU
RMHTYP DATA C'R'
RMREQ
2 num
Specifies the SEND request
RMREQ DATA FO'
RMSDSN (*)
S alpha
Name of data set to send to host
RMSDSN DATA CLS'DATASET'
RMSVOL (*)
S alpha
Volume containing the data set to
be sent. Default=IPL volume
RMSVOL DATA CLS'VOLUME'
RMSSTR (*)
4num
Starting record of the data set to be
sent
RMSSTR DATA 0'0'
RMSTYP (*)
2 num
Type of data set to be sent to the
host
RMSTYP DATA FO'
RMSBLK (*)
2num
Specifies record blocking of data to
be sent
RMSBLK DATA FO'
Figure 40. Required Fields for SEND Request
Here is an example of SEND request communications flow. The host asks the remote system to
send it a data set called "MYDATA."
Figure 55 on page CO-tt5 shows a sample program that sends a SEND request.
o
Chapter 2. Remote Management Utility ($RMU)
CO-83
Remote Management Utility ($RMU)
o
Host Programming for the $RMU Application (continued)
Host Program
Host
ENQ
------->
RMHBSCC DATA X'1002'
RMHID DATA C'X'
RMHTYP DATA C'R'
RMREQ DATA FO'
RMSDSN DATA CLS'MYDATA'
RMSVOL DATA CL6'MYVOL'
RMSSTR DATA D'O'
RMSTYP DATA FO'
RMSBLK DATA Fl'
TEXT
------->
BSCWRITE E
EOT
BSCWRITE IX
Remote
------->
ACK*
------->
ACK*
------->
ACK*
------->
BSCREAD I
BSCREAD C
BSCREAD C
ACK*
------->
ACK*
------->
BSCREAD C
BSCREAD C
<------- ACK*
<------- ACK*
<-------
ENQ
<------- TEXT
(status)
RMHTYP='S'
RMSREQ=O
RMSFN=-1
<------- TEXT
(data)
RMHTYP='D'
RMDDATA=Text
<------- TEXT
(data)
RMHTYP='D'
RMDDATA=Text
(--\
'llLJ
<------- TEXT
(count)
RMHTYP='C'
RMCREQ=O
RMCCNT=2
<-------
EOT
(termination)
Figure 41. Communications Flow for SEND Request
Remote System Echoing Host Data (WRAP)
The host can send data to the remote system, and ask $RMU to echo that data back to the host.
This is the WRAP request. WRAP is useful for testing line conditioning.
Send a WRAP request by coding a BSCWRITE IX instruction, along with the required
information fields. The RMWTXT field is where to specify the text you want $RMU to echo
back to the host.
o
CO-84
SC34-0638
o
Host Programming for the $RMU Application (continued)
Coding the Required Fields for WRAP Request
Specify the following fields for the WRAP function:
The chart that follows shows all the fields to code in your program for a WRAP request. The
fields identified by as asterisk (*) contain variable values. You can code any appropriate value
in these fields. However, the other fields can contain only the values shown in the chart. Code
these fields exactly as the chart specifies.
Field
Size
Explanation
What to Code
Type
RMHBSCC
2 hex
Starts the message
RMHBSCC DATA X'1002
RMHID
1 alpha
Identifies a message to $RMU
RMHID DATA C'X'
RMHTYP
1 alpha
Identifies a request to $RMU
RMHTYP DATA C'R'
RMREQ
2num
Specifies the WRAP request
RMREQ DATA FS'
RMWTXT(*)
vari- able
Text that $RMU is to echo back to
host.
RMWTXT DATA C'ANY TEXT'
Figure 42. Required Fields for WRAP Request
Figure 43 on page CO-86 shows an example of the WRAP function. The host sends the
Series/l a WRAP request along with the text "WRAP TEXT." The Series/l receives the
request and transmits the identical data back to the host, and the operation is completed.
Figure 53 on page CO-l09 shows a sample program that can send a WRAP request.
0:
,
,
Chapter 2. Remote Management Utility ($RMU)
CO-85
Remote Management Utility ($RMU)
o
Host Programming for the $RMU Application (continued)
Host Program
BSCWRITE IX
Host
ENQ -------->
RMHBSCC DATA X'1002'
RMHID DATA C'X'
RMHTYP DATA C'R'
RMREQ DATA F5'
RMWTXT DATA C'WRAP TEXT
TEXT
BSCWRITE E
EOT
------->
------->
ACK*
------->
BSCREAD I
Remote
<------- ACK*
<------- ACK*
<-------
ENQ
<------- TEXT
(wrap text)
RM H BSCC=X' 1002'
RMHID=C'X'
RMHTYP=C'R'
RMREQ=F'5'
RMWTXT=X'WRAP TEXT
ACK*
------->
BSCREAD C
<-------
EOT
(termination)
Fagure 43. Communications Flow for WRAP
Controlling Program Execution on the Remote System
$RMU can perform functions involving the execution of programs on the remote system. You
can tell $RMU to start a program running on the remote system. You can also teli $RMU to
load another program and at the same time terminate itself. The requests associated with these
functions are:
•
EXEC start a program on the remote system
•
SHUTDOWN the operation of $RMU and load another program on the remote system.
Host Starting a Program on Remote System (EXEC)
The host can ask $RMU to start execution of a program on the remote system. This is the
EXEC request.
Send the EXEC request by coding a BSCWRITE IX instruction, along with the required data
fields.
$RMU sends a the host a status message to tell if it was able to perform the EXEC function.
$RMU then waits for a new request from the host.
o
CO-86
SC34-0638
o
Host Programming for the $RMU Application (continued)
Coding the RMXFLG Field: The RMXFLG is an optional field which activates these
conditions:
•
Prints a "program loaded" message on the remote terminal that loaded $RMU. Enter the
value X'40'.
Causes $RMU to wait for the program to finish running before sending a status message to
the host. Enter the value X'20'.
These two values correspond to the LOGMSG and WAIT operands of the Event Driven
Language instruction LOAD.
To specify both of these conditions, enter the value X'60'.
To specify neither of these conditions, simply do not code the RMXFLG field.
Specifying Partition: You must tell $RMU the partition in which to run the program. The
field RMXPTN is where to code this information. Enter one of the following values in this field:
•
-1
$RMU partition
•
0
Any partition
•
1 - 8 Specific partition.
Allocating Free Space: You can specify the amount of free space (in bytes) to pass to the
program. The RMXLFS field is where to code this information.
Passing Parameters: Some programs require parameters to be passed from the host in order
to run successfully. You accomplish this with the RMXPRM# and RMXPRM fields.
In RMXPRM#, specify the length (in words) of the parameters to pass to the program.
In RMXPRM, specify the parameters themselves. The length of RMXPRM must be equal to
the value in RMXPRM#.
Passing Data Sets: You can pass data sets to the program by coding the RMXDS# and
RMXDS fields.
In RMXDS#, specify the number of data sets (up to nine) to pass to the program. Do not leave
this field blank; enter zero if you are not passing any data sets.
In RMXDS, specify the name and volume of each data set to pass to the program. The number
of RMXDS fields must be equal to the value of RMXDS#.
o
Chapter 2. Remote Management Utility ($RMU)
CO-87
Remote Management Utility ($RMU)
Host Programming for the $RMU Application (continued)
Coding Required Fields for EXEC Request
o
The chart that follows shows all the fields to code in your program for an EXEC request. The
fields identified by as asterisk (*) contain variable values. You can code any appropriate value
in these fields. However, the other fields can contain only the values shown in the chart. Code
these fields exactly as the chart specifies.
Field
Size
Type
Explanation
What to Code
RMHBSCC
2 hex
Starts the message
RMHBSCC DATA X'1002
RMHID
1 alpha
Identifies a message to $RMU
RMHID DATA C'X'
RMHTYP
1 alpha
Identifies a request to $RMU
RMHTYP DATA C'R'
RMREQ
2 num
Specifies the EXEC request
RMREQ DATA F9'
filler
2
Reserved field (unused)
RMXFLG (*)
1 num
Load message prints (X' 40') or
status message is delayed (X'20')
This field is optional.
RMXFLG DATA X'nn'
RMXPTN (*)
1 num
Partition to run program in
RMXPTN DATA H'n'
RMXPGM (*)
8 alpha
Name of program to execute
RMXPGM DATA CL8'DATASET
RMXVOL (*)
6 alpha
Volume containing the program to
execute. Default= IPL volume
RMXVOL DATA CL6'VOLUME'
RMXLFS (*)
2 num
Free space (in bytes) to pass to
program
RMXLFS DATA Fnn'
DATA FO'
Figure 44 (Part 1 of 2). Required Fields for EXEC Request
o
CO-88
SC34-0638
o
Host Programming for the $RMU Application (continued)
Field
Size
Type
Explanation
What to Code
RMXPRM# (*)
2num
Length of parameters to pass to
program
RMXPRM# DATA Fnn'
RMXPRM (*)
vari- able
Parameters to pass to program
RMXPRM EQU *
RMXDS# (*)
2 num
Number of data sets to pass to
program
RMXDN# DATA Fnn'
RMXDS (*)
14 alpha
Name and volume of data set to
pass to program.
RMXDS EaU *
Figure 44 (Part 2 of 2). Required Fields for EXEC Request
o
Figure 45 on page CO-90 shows an example of the EXEC function. The host specifies that a
program named "MYPROG" on volume "MYVOL" is to be executed in partition 1, with 256
bytes of free space passed to the program. The RMXFLG field specifies that both the
RMXFLGL and RMXFLGW bits are set on. No parameters or data sets are passed to
"MYPROG." The program ends with a return code of -1. $RMU sends a status record of -1
(successful completion) to the host, along with the return code for "MYPROG."
Figure 53 on page CO-109 shows a sample program that can send an EXEC request.
o
Chapter 2. Remote Management Utility ($RMU)
,
CO-89
Remote Management Utility ($RMU)
o
Host Programming for the $RMU Application (continued)
Host Program
BSCWRITE IX
Host
ENQ ------->
RMHBSCC DATA X'1002'
RMHID DATA C'X'
RMHTYP DATA C'R'
RMREQ DATA F9'
DATA FO'
RMXFLG DATA X'60'
RMXPTN DATA H'1'
RMXPGM DATA CLS'MYPROG'
RMXVOL DATA CL6'MYVOL'
RMXLFS DATA F256'
RMXPRM# DATA FO'
RMXPRM EQU *
RMXDS# DATA FO'
RMXDS EQU *
TEXT
BSCWRITE E
EOT
Remote
<------- ACK*
------->
<------- ACK*
------->
ACK*
------->
BSCREAD I
<-------
ENQ
<------- TEXT
(status)
RMHTYP='S'
RMSREQ=9
RMSFN=-1
RMSST=_I
ACK*
------->
BSCREAD C
<------- EOT
("---,,
,_,"c)
Figure 45. Communications Flow for EXEC
Terminate $RMU/Start Another Program on Remote System (SHUTDOWN)
You can ask $RMU to terminate and release any Series/l resources it has allocated. In addition,
you can ask $RMU to start another program on the remote system before terminating. This is
the SHUTDOWN request.
Send your SHUTDOWN request by coding a BSCWRITE IX instruction, along with the
required information fields. The request may also specify the name of a program to be
executed, similar in format to the EXEC function.
Coding the RMSDFLG Field: The RMSDFLG is an optional field which activates these
conditions:
•
Specifies that $RMU is to run another program. Enter the value X' 80' .
Prints a "program loaded" message on the remote terminal that loaded $RMU. Enter the
value X'60'. This value corresponds to the LOGMSG parameter of the Event Driven
Language instruction LOAD.
To specify both conditions, enter the value X'CO'
o
CO-90
SC34-0638
o
Host Programming for the $RMU Application (continued)
To specify neither of these conditions, simply do not code the RMSDFLG field.
Specifying Partition: You must tell $RMU the partition in which to run the program. The
field RMSDPTN is where to code this information. Enter one of the following values in this
field:
-1
$RMU partition
•
0
Any partition
•
1 - 8 Specific partition.
Allocating Free Space: You can specify the amount of free space (in bytes) to pass to the
program. The RMSDLFS field is where to code this information. This value is expressed in
bytes.
Passing Parameters: Some programs require parameters to be passed from the host system
in order to run successfully. You accomplish this with the RMSDPRM# and RMSDPRM fields.
In RMSDPRM#, specify the length (in words) of the parameters to pass to the program.
c
In RMSDPRM, specify the parameters themselves. The length of RMSDPRM must be equal to
the value in RMSDPRM#.
Passing Data Sets: You can pass data sets to the program by coding the RMSDDS# and
RMSDDS fields.
In RMSDDS#, specify the number of data sets (up to nine) to pass to the program. Do not
leave this field blank; enter zero if you are not passing any data sets.
In RMSDDS, specify the name and volume of each data set to pass to the program. The number
of RMSDDS fields must be equal to the value of RMSDDS#.
o
Chapter 2. Remote Management Utility ($RMU)
CO-91
Remote Management Utility ($RMU)
Host Programming for the $RMU Application (continued)
( ,J~)
,
Coding the Required Fields for SHUTDOWN Request
The chart that follows shows all the fields to code in your program for a SHUTDOWN request.
The fields identified by an asterisk (*) contain variable values. You can code any appropriate
value in these fields. However, the other fields can contain only the values shown in the chart.
Code these fields exactly as the chart specifies.
Field
Size
Type
Explanation
What to Code
RMHBSCC
2 hex
Starts the message
RMHBSCC DATA X'1002'
RMHID
1 alpha
Identifies a message to $RMU
RMHID DATA C'X'
RMHTYP
1 alpha
Identifies a request to $RMU
RMHTYP DATA C'R'
RMREO
2 num
Specifies the SHUTDOWN request
RMREO DATA FT
filler
2
Reserved field (unused)
RMSDFLG (*)
1 num
Execute another program (X'80')
and/or load message prints (X'40')
This field is optional.
RMSDFLG DATA X'nn'
RMSDPTN (*)
1 num
Partition to run program in
RMSDPTN DATA H'n'
RMSDPGM (*)
8 alpha
Name of program to execute
RMSDPGM DATA CL8'DATASET'
RMSDVOL (*)
6 alpha
Volume containing the program to
execute. Default= I PL volume
RMSDXVOL DATA CL6'VOLUMF
RMSDLFS (*)
2num
Free space (in bytes) to pass to
program
RMSDLFS DATA Fnn'
DATA FO'
Figure 46 (Part 1 of 2). Required Fields for SHUTDOWN Request
o
CO-92
SC34-0638
o
Host Programming for the $RMU Application (continued)
Field
RMSDPRM# (*)
Size
Type
2 num
Explanation
What to Code
Length of parameters to pass to
program
RMSDPRM# DATA Fnn'
RMSDPRM (*)
vari- able
Parameters to pass to program
RMSDPRM EQU *
RMSDDS# (*)
2num
Number of data sets to pass to
program
RMSDDN# DATA Fnn'
RMSDDS (*)
14 alpha
Name and volume of data set to
pass to program.
RMSDDS EQU *
Figure 46 (Part 2 of 2). Required Fields for SHUTDOWN Request
Figure 47 on page CO-94 shows an example of the SHUTDOWN function. The host sends the
Series/1 a SHUTDOWN request with a program name specified. The program, "MYPROG"
on volume "MYVOL," is to execute in partition 1, has 256 bytes of free space passed to it, and
has no parameters or data sets passed to it. The RMSDFLG field specifies that a program is to
be executed and a "program loaded" message is to be printed following a successful load of the
program. $RMU sends a status record of -1 (successful completion) to the host, loads the
program, and $RMU ends.
Figure 53 on page CO-109 shows a sample program that can send a SHUTDOWN request.
o
Chapter 2. Remote Management Utility ($RMU)
CO-93
Remote Management Utility ($RMU)
o
Host Programming for the $RMU Application (continued)
Host Program
Host
Remote
Remote
------->
BSCWRITE IX
ENO
RMHBSCC DATA X'1002'
RMHID DATA C'X'
RMHTYP DATA C'R'
RMREO DATA F7'
RMSDFLG DATA X'CO'
RMSDPTN DATA H'1'
RMSDPGM DATA CLS'MYPROG'
RMSDVOL DATA CLS'MYVOL'
RMSDFLS DATA F25S'
RMSDPRM# DATA FO'
RMSDPRM EOU *
RMSDDS# DATA FO'
RMSDDS EOU *
TEXT
BSCWRITE E
EOT
------->
------->
ACK*
------->
BSCREAD I
<------- ACK*
<------- ACK*
<-------
ENO
<------- TEXT
(status)
RMHTYP='S'
RMSREQ=7
RMSFN=-1
ACK*
BSCREAD C
------->
<-------
EOT
(termination)
Figure 47. Communications Flow for SHUTDOWN
Verifying Identities between Systems (I DCH ECK)
You can ask $RMU to verify the identities of the host and remote systems. This is the
IDCHECK request. You send your IDCHECK request by coding a BSCWRITE IX instruction
along with the required information fields.
The IDs of both the host and remote systems have predefined default values. These values are
discussed in the section, "Remote Management Utility Defaults." The default IDs are in remote
system storage. $RMU asks the host to send its ID for verification. Only if the host ID is
correct does $RMU send the remote system ID to the host. If the host sends an incorrect
(invalid) ID, $RMU terminates the function.
Coding the Required Fields for IDCHECK Function
The chart that follows shows all the fields to code in your program for an IDCHECK request.
The fields identified by an asterisk (*) contain variable values. You can code any appropriate
value in these fields. However, the other fields can contain only the values shown in the chart.
Code these fields exactly as the chart specifies.
o
CO-94
SC34-0638
o
Host Programming for the $RMU Application (continued)
Field
Size
Type
Explanation
What to Code
RMHBSCC
2 hex
Starts the message
RMHBSCC DATA X'1002
RMHID
1 alpha
Identifies a message to $RMU
RMHID DATA C'X'
RMHTYP
1 alpha
Identifies a request to $RMU
RMHTYP DATA C'R'
RMREQ
2 num
Specifies the IDCHECK request
RMREQ DATA F9'
RMICHK (*)
8 alpha
Host 10
RMICHK DATA C'HOSTID'
Figure 48. Required Fields for IDCHECK Request
Figure 49 shows an example of the IDCHECK function. The host sends the default ID
"HOSTRMUX." $RMU validates the host ID and sends a status record of -1 (successful
completion) to the host along with its default ID, "REMTRMUX."
Figure 5 3 on page CO-I09 shows a sample program that can send an IDCHECK request.
Host Program
BSCWRITE IX
Host
RMHBSCC DATA X'1002'
RMHID DATA C'X'
RMHTYP DATA C'R'
RMREQ DATA FS'
RMICHK DATA C'HOSTRMUX'
TEXT
BSCWRITE E
EOT
ENQ
Remote
------->
------->
------->
ACK*
------->
BSCREAD I
<------- ACK*
<------- ACK*
<------- ENQ
<------- TEXT
(status)
RMHTYP='S'
RMSREQ=S
RMSFN=-1
RMSRID=' REMTRMUX'
ACK*
BSCREAD C
------->
<------- EOT
Figure 49. Communications Flow for IDCHECK
o
Chapter 2. Remote Management Utility ($RMU)
CO-95
Remote Management Utility ($RMU)
Interacting Between Host and Remote Systems (PASSTHRU)
You can set up interactive sessions between the host and remote systems with the PASSTHRU
request. During a passthru session, the host can perform the same functions as a station directly
attached to the remote system. The host can interact with the Event Driven Executive
supervisor by issuing operator commands, or with a program or utility on the remote system.
o
Most programs that do not require full screen terminal support, including most Event Driven
Executive utilities, are available for use during a passthru session. Programs which cannot be
run under the PASSTHRU function are discussed in "Considerations for Using PASSTHRU."
Considerations for Using PASSTHRU
Certain restrictions apply to programming for the PASSTHRU session. Before establishing a
session, you must know what you can and cannot do with PASSTHRU.
Virtual Terminal Support
PASSTHRU uses the virtual terminal support of the Event Driven Executive. Because of this,
the restrictions inherent in virtual terminal support also apply to PASSTHRU. Virtual terminals
do not support static screens. Therefore, programs that use static screens cannot be run under
the PASSTHRU function. This includes programs such as the full screen editor, $FSEDIT.
Another virtual terminal restriction is that the maximum record length is 254 bytes.
During system generation, you must define two virtual terminals for the remote system:
CDRVTA and CDRVTB. You may want to change the LINSIZE parameter. A LINSIZE of
132 will handle output that uses the full width of a printer. Specifying a smaller value saves
storage, but messages longer than the LINSIZE will be truncated. The maximum value for
LINSIZE is 254.
Because the $RMU PASSTHRU function uses a predefined set of virtual terminals (CDRVTA
and CDRVTB), only one PASSTHRU session can be conducted at a time. While a PASSTHRU
session is being conducted, another copy of $RMU (defined for another communications line)
can be performing any other function except PASSTHRU.
No Attention Interrupt
$RMU allows the host to transmit a Program Function key or an attention key only after $RMU
has sent a request message. Therefore, when the attention key is pressed at a host terminal, the
terminal stops communicating with $RMU (the remote system) and begins communicating with
its own (the host) system. This prevents output from $RMU to the host from being interrupted
by a host terminal attention key, as it could be by a local terminal. For example, a listing
produced by the $DISKUT2 utility could not be interrupted by pressing the host terminal
attention key and entering the $C command.
o
CO-96
SC34-0638
o
Interacting Between Host and Remote Systems (PASSTHRU) (continued)
Deadlock and $RMUPA
A program that stops communicating with the terminal which loaded it and waits for operator
commands (using the attention or Program Function key) will not run directly under the
P ASSTHRU function. This is because $RMU waits indefinitely on a READTEXT to the virtual
channel at the same time the host program is waiting for an Attention or PF key. Since both
programs are "listening" and neither is "talking," both will wait forever. This is called a
deadlock. Programs that may do this include:
$DEBUG
$TRAP
$LOG
$BSCTRCE
$TERMUT 3 (attention-entered commands)
$IOTEST (attention-entered commands)
CALCDEMO (sample program)
$RMUPA is a program that can break this deadlock. It must be started under the PASSTHRU
function prior to starting a PASSTHRU session with a program which may have this problem.
$RMUP A causes a "disconnect", which results in a $RMU sending a Program End P ASSTHRU
record to the host whenever the following events occur:
o
•
No activity has occurred over the virtual channel for 20 seconds.
•
$RMU is waiting on completion of a READTEXT instruction.
•
The host program is not enqueued (ENQT) on its virtual terminal.
$RMUP A uses the STIMER instruction; therefore, timer support must be included in the Event
Driven Executive system.
The sample PASSTHRU host program in "PASSTHRU Sample Program" on page CO-II?
shows how to use $RMUPA. First $RMUPA is started. When a Program End PASSTHRU
record is received at the host, the host responds with a Program End PASSTHRU record and the
PASSTHRU session with $RMUPA ends. Only one copy of $RMUPA should be running at
any time; it can run in any partition. It continues running until an "attention" followed by
$RMUPA is entered.
Once $RMUPA is running, you may start another program. The sample PASSTHRU host
program in "Example of Conducting a PASSTHRU Session" on page CO-12S shows how you
can use $DEBUG. Note that you can enter $PFO to provide the same function as the attention
key.
If a remote program does not perform any terminal I/O for 20 seconds, $RMUPA causes a
Program End record to be sent even though the program is still running. If this happens, the
host should respond with a Request for Data record until the remote program performs terminal
I/O.
o
Chapter 2. Remote Management Utility ($RMU)
CO-9?
Remote Management Utility ($RMU)
Interacting Between Host and Remote Systems (PASSTHRU) (continued)
Indefinite Waits
o
If the PASSTHRU function loads a program which issues an ENQT for a terminal other than
the terminal which loaded $RMU and the program terminates, $RMU does not receive a
"disconnect" over the virtual channel and the host will not receive a Program End record.
$RMU will wait indefinitely. One example of when this occurs is when $EDXASM is running
with output directed to a printer. This condition can be avoided in two ways:
•
Load the program from another program (such as the $JOBUTIL utility) which will wait for
the program to complete. Programs that require interaction with the terminal operator, such
as $EDXASM, should be handled in this way.
•
Load the program through a session with the Event Driven Executive supervisor (using the
$L command) and respond with a Program End when the command terminates.
Abrupt Termination
If a PASSTHRU session is abruptly terminated (status received from host, invalid message
received from host, or an error in the BSCAM), $RMU sends a return code 5 ("disconnected")
to the program for the outstanding terminal request. This code will be received only once by the
PASSTHRU-invoked program. The program should take appropriate action, which would most
likely be to terminate.
If the program does not recognize the error and continues to perform terminal I/O, it will
interfere with attempts to establish a new PASSTHRU session. If the new session is being
established with a program, $RMU returns the status "virtual terminal busy." The host may
establish a session with the Event Driven Executive supervisor and issue a $C command to
cancel the suspended program. (As noted in the Operator Commands and Utilities Reference, the
$C command should be used with caution).
When a load command ($L) is issued during a PASSTHRU session with the Event Driven
Executive supervisor, a Program End record, resulting from completion of the command, may be
received by the host. Whether it is received depends on how quickly the loaded program begins
performing terminal I/O.
Timeouts
$RMU will not time-out while it is receiving messages during a PASSTHRU session. However,
if the host does not acknowledge receipt of messages sent by $RMU, a time-out will occur and
the PASSTHRU session will terminate. This can be avoided in two ways:
•
Avoid any long delays at the host while messages are being received from the Series/I.
•
Define a high retry count for the RETRIES parameter of the BSCLINE statement.
o
CO-98
SC34-0638
o
Interacting Between Host and Remote Systems (PASSTHRU) (continued)
Send your P ASSTHRU request by coding a BSCWRITE IX instruction, along with the required
information fields. Once the passthru session begins, the host and $RMU exchange a series of
messages in a manner similar to the way messages are written to and read from a terminal. This
record exchange consists of two parts:
•
Establishing a PASSTHRU session
Conducting a PASSTHRU session,
Establishing a PASSTHRU Session
The host initiates the PASSTHRU function by sending a PASSTHRU request to $RMU. After
the host receives a successful status record and an EOT, a PASSTHRU session is established.
The PASSTHRU request specifies (in the RMPRPGM field) the type of session:
Communication with the Event Driven Executive supervisor
•
Communication with a program or utility which $RMU will load.
If a session with the EDX supervisor is established, $RMU issues an "attention" (as if the
attention key on the terminal were pressed). After the terminal on the host receives the caret
symbol (», the host operator can enter a Series/1 operator command, for example, $L.
c
If a session with a program is established, the host specifies the name of the program and $RMU
loads the program. The P ASSTHRU session will be conducted with the host interacting with the
program.
Coding Required Fields for PASSTHRU Request
The chart that follows shows all the fields to code in your program for a PASSTHRU request.
The fields identified by an asterisk (*) contain variable values. You can code any appropriate
value in these fields. However, the other fields can contain only the values shown in the chart.
Code these fields exactly as the chart specifies.
Field
RMHBSCC
Size
Tvpe
2 hex
Explanation
What to Code
Starts a message
RMHBSCC DATA X'1002'
RMHID
1 alpha
Identifies a message to
$RMU
RMHID DATA C'X'
RMHTYP
1 alpha
Identifies a request
RMHTYP DATA C'R'
Figure SO (Part 1 of 2). Required Fields for PASSTHRU Request
o
Chapter 2. Remote Management Utility ($RMU)
CO-99
Remote Management Utility ($RMU)
Interacting Between Host and Remote Systems (PASSTHRU) (continued)
Field
Size
Tvpe
Explanation
What to Code
RMREO
2 num
Specifies the PASSTHRU
request
RMREO DATA F12'
RMPRBLK*
2 num
Specifies record blocking by
remote system
RMPRBLK DATA Fn'
RMPRFLG
1
Reserved field (unused)
RMPFLG DATA H'O'
RMPRPTN*
1 num
Partition to run program or
utility in
RMPRPTN DATA H'n'
RMPRPGM*
8 alpha
Name of program or utility to
interact with host
RMPRPGM DATA CL8'PROGNAME'
RMPRVOL*
6 alpha
Volume containing the
program or utility Default=
IPL volume
RMPRVOL DATA CL6'VOLUME'
RMPRLFS*
2 num
Free space to pass to
program
RMPRLFS DATA F'n'
RMPRPRM#
(*)
2 num
Length of parameters to pass
to program
RMPRPRM# DATA F'n'
RMPRPRM*
variable
Parameters to be passed to
the program.
RMPRPRM EOU *
RMPRDS# (*)
2 num
Number of data sets to pass
to program
RMPRDS# DATA Fn'
RMPRDS
14 alpha
Name and volume of data
sets to pass to program
RMPRDS EOU *
o
Figure SO (Part 2 of 2). Required Fields for PASSTHRU Request
Here is an example of the communications flow for a PASSTHRU request.
Figure 56 on page CO-118 shows a sample program that sends a PASSTHRU request.
o
CO-IOO
SC34-0638
o
Interacting Between Host and Remote Systems (PASSTHRU) (continued)
Host Program
BSCWRITE IX
Host
ENQ ------->
RMHBSCC DATA X'1002'
RMHID DATA C'X'
RMHTYP DATA C'R'
RMREQ DATA F12'
RMPRFLG DATA H'O'
RMPRPTN DATA H'O'
RMPRPGM DATA CLS'MYPROG'
RMPRVOL DATA CL6'MYVOL'
RMPRLFS DATA F256'
RMPRBLK DATA FO'
RMPRPRM# DATA FO'
RMPRPRM EQU *
RMPRDS# DATA FO'
RMPRDS EQU *
TEXT
BSCWRITE E
EOT
Remote
<------- ACK*
------->
<------- ACK*
------->
<------- ENQ
ACK*
------->
<------- TEXT
(status)
RMHTYP ='S'
RMSREQ=12
RMSFN=-1
BSCREAD I
o
ACK*
------->
<------- EOT
BSCREAD C
<------ACK*
ENQ
------->
<------- TEXT
(passthru data)
RMHTYP='P'
RMPTYP=1
RMPST=Status from READTEXT
RMPTXTL=Message length
RMPTXT=Message text
BSCREAD I
ACK*
------->
Figure 51 (Part 1 of 2). Communications Flow for PASSTHRU
Chapter 2. Remote Management Utility ($RMU)
CO-l 0 1
Remote Management Utility ($RMU)
Interacting Between Host and Remote Systems (PASSTHRU) (continued)
o
<--------
BSCREAD C
TEXT
(request for data)
RMHTYP='P'
RMPTYP=2
------->
ACK*
BSCREAD C
ENO
------->
BSCWRITE IX
RMHTYP='P'
RMPTYP=1
RMPST=Q (Unused)
RMPTXTL=Message length
RMPTXT=Message text
TEXT
BSCWRITE E
EaT
------->
------->
------->
<------- TEXT
<-------
EaT
<------- ACK*
<------- ACK*
<-------
ENO
ACK*
BSCREAD I
BSCREAD C
ENO
BSCWRITE IX
(PASSTHRU program end)
RMHTYP='P'
RMPTYP=3
------->
TEXT
(PASSTHRU program end)
RMHTYP='P'
RMPTYP=3
ACK* ------->
<------- EaT
<------- ACK*
-------->
<------- ACK*
BSCREAD E
EaT
()
------>
Figure 51 (Part 2 o( 2). Communications Flow (or PASSTHRU
Conducting a PASSTHRU Session
Once the P ASSTHRU session is established, the host and the remote systems exchange
P ASSTHRU records. These records provide information to and receive information from the
host program, as if the host program were a terminal on the remote system. There are four types
of PASSTHRU records:
•
Text or Program Function (PF) Key - passes messages or Program Function keys
•
Request for Data - indicates data should be sent
•
Program End - indicates termination
•
No Data - indicates no messages are available.
o
CO-I02
SC34-0638
o
Interacting Between Host and Remote Systems (PASSTHRU) (continued)
The host "state" can be changed by:
•
Receiving a PASSTHRU record from $RMU. This is shown as a solid horizontal line with
an arrow pointing to the new state.
•
Sending a PASSTHRU record to $RMU. This is shown as a horizontal line of dashes with
an arrow pointing to the new state.
•
A change of state with no PASSTHRU record transfer. This is represented by a dotted line
with an arrow pointing to the new state.
The PASSTHRU session begins with the host in the state READTEXT. The host issues a read
to the communications line and receives either a Text or PF Key, Request for Data, or Program
End record.
If the host receives a Text or PF Key record, the Series I 1 is sending data to the host. The
program (or the supervisor) has issued a PRINTEXT or other terminal 110 instruction, and it is
transmitted to the host as if the host were a terminal. The state of the host changes from
READ TEXT to READING, the host reads the Text or PF Key record, and the state then
changes back to READ TEXT . The host remains in the READ TEXT state as long as it receives
Text or PF Key records.
o
If the host receives a Request for Data record, $RMU needs data from the host. The program
(or the supervisor) has issued a READTEXT or other terminal 110 instruction, and requires
data from the host as if the host were a terminal. The state of the host changes from
READTEXT to "PGM NEEDS DATA". Note that an EOT follows the the Request for Data
record. The host must also read the EOT.
When the host is in the state "PGM NEEDS DATA," it must send a Text or PF Key record
followed by an EOT. The Text or PF Key record the host sends can contain either text or a PF
key.
If the host sends text, the state of the host changes from "PGM NEEDS DATA" to
READTEXT. If the host sends a Program Function key, the host goes to the state "PFK
SENT." The host issues a read to the communications line and will receive a Request for Data
record followed by an EOT. $RMU sends the Request for Data record to the host because the
original request was not satisfied by the Program Function key. As a result, the host is now in
the state "SEND TEXT." The host must send a Text or PF Key record which contains text,
followed by an EOT. The host then returns to the state READTEXT.
If the host is in the state READ TEXT and receives a Program End record followed by an EOT,
this means that the program, the operator command, or an attention exit has completed. The
host changes from the state READTEXT to "CONTINUE ?". At this point, the host must
determine whether the P ASSTHRU session should continue.
0 ,'\
"
Chapter 2. Remote Management Utility ($RMU)
CO-I03
Remote Management Utility ($RMU)
Interacting Between Host and Remote Systems (PASSTHRU) (continued)
If the PASSTHRU session is with a program and the program ends (while in the "CONTINUE
?" state), the host usually does not continue the session. If the session is with the supervisor and
o
you enter a $L command, the host usually continues the session and communicates with the
program that was loaded.
To terminate the PASSTHRU session, the host sends a Program End record, followed by an
EOT. This changes the state of the host from "CONTINUE?" to "EXIT". The PASSTHRU
session now terminates and the Remote Management Utility waits for a new request from the
host. To continue the session, the host sends a Request for Data record followed by an EOT.
The state of the host then changes from "CONTINUE ?" to "ACTIVITY?".
At this point, $RMU determines if there is any activity on the Series/l for the host. If there is,
$RMU sends one of the three PASSTHRU records (Text or PF Key, Request for Data, or
Program End) which the host can receive in the "READTEXT" state. The state of the host
then changes depending on the type of PASSTHRU record it receives.
If there is no terminal activity, $RMU sends a No Data record followed by an EOT, and the
host state changes from "ACTIVITY?" to "CONTINUE ?". The host then determines
whether it should continue. If the program in the Series/l has delays in performing terminal
I/O while the host is in the "CONTINUE ?" state, the host may change from "CONTINUE ?"
to "ACTIVITY?" and back again several times. However, if no activity occurs, the host must
eventually send a Program End record and terminate the PASSTHRU session.
Figure 57 on page CO-125 shows a PASSTHRU session that invokes and runs the $DEBUG
utility from the host terminal.
~"
'~L._"i
PASSTHRU Record Types
This section describes the format and content of the four types of PASSTHRU records.
Text or Program Function Key Record
This record consists of two segments. The first six bytes, or the main segment, identifies the
record as a PASSTHRU Text or Program Function (PF) key record. One or more text or PF
key segments follow the main segment.
In the main segment, all values are constants, as shown below. The number 1 for the RMPTYP
field identifies the record as a text or PF key record. The text or Program Function key segment
contains the information to be transferred.
o
CO-I04
SC34-0638
o
Interacting Between Host and Remote Systems (PASSTHRU) (continued)
Main segment:
RMHBSCC DATA X'1002'
RMHID DATA C'X'
RMHTYP DATA CP'
RMPTYP DATA F1'
Text or Program Function key segment:
RMPST DATA Fnnnn'
RMPTXTL DATA F'nnnn'
RMPTXT DATA C'xxxx'
The fields in the text or Program Function key segment are:
RMPST
A 2-byte numeric field containing the return code associated with the text. For
example, the return code might indicate that the text is to appear on a new line.
This field contains a value only on records received by the host.
Some return codes have no text associated with them. For a complete description
of the possible return codes, see the virtual terminal return codes for the
READTEXT instruction in the Language Reference.
o
The return codes which apply are:
X'8Fnn'
X'8Enn'
-2
-1
LINE=nn received
SKIP= nn received
Line received (no CR)
New line received
RMPTXTL A 2-byte numeric field specifying either the length of the text, or indicating a PF
key is being sent (-1). If there is no text, for example when only a return code is
sent, this field contains a zero.
RMPTXT
Either a variable-length alphameric field containing text, or a 2-byte numeric field
containing the PF key value. If the field contains text, the length of the text must
equal RMPTXTL. If RMPTXTL is an odd number, one byte of blanks (X'40')
follows the text.
If the Text or PF Key record is not blocked, it will contain one of each segment. If the record is
blocked, it will contain one main segment followed by multiple text or PF key segments. The
host must determine the length of the record to process each segment. All records sent by the
host are unblocked. Records sent by $RMU may be blocked if specified on the P ASSTHRU
request. Blocking is discussed in "PASSTHRU Blocking" on page CO-l08.
All Text or PF Key records sent by $RMU will always contain text; the host will never receive a
Program Function key.
o
Chapter 2. Remote Management Utility ($RMU)
CO-l05
Remote Management Utility ($RMU)
Interacting Between Host and Remote Systems (PASSTHRU) (continued)
When the host sends a Text or PF Key record, the record may contain either text (the host as a
terminal has entered text), or a PF key (the host as a terminal has entered a PF key). If text is
sent, the length of the text is specified in the RMPTXTL field, and the text is specified in the
RMPTXT field. The RMPST field is not used.
The following example shows a record sent by the host which contains the text "MESSAGE
FROM HOST PROGRAM."
RMHBSCC DATA X'1002'
RMHID DATA C'X'
RMHTYP DATA C'P'
RMPTYP DATA F1'
RMPST DATA FO' (IGNORED)
RMPTXTL DATA F25'
RMPTXT DATA C'MESSAGE FROM HOST PROGRAM'
When the host sends a PF key, the value of the RMPTXTL field is set to - i and the PF key is
specified as a 2-byte numeric value in the RMPTXT field. A PF key value of 0 is the equivalent
of an "attention."
The following example shows the host sending a Program Function key 3.
RMHBSCC DATA X'1002'
RMHID DATA C'X'
RMHTYP DATA C'P'
RMPTYP DATA F1'
RMPST DATA FO' (IGNORED)
RMPTXTL DATA F-1' (INDICATES PF KEY)
RMPPF DATA F3' PF KEY 3
Figure 52 on page CO-tO? is an example of the records the host receives from a program which
executes a PRINTEXT instruction.
CO-I06
SC34-0638
o
o
Interacting Between Host and Remote Systems (PASSTHRU) (continued)
Issued by program on Series/1 :
PRINTEXT 'ENTER COMMAND',SKIP=1
PASSTHRU record received by host
with no blocking:
RMHBSCC DATA X'1002'
RMHID DATA C'X'
RMHTYP DATA C'P'
RMPTYP DATA F1'
RMPST DATA X'SE01' (SKIP=1)
RMPTXTL DATA FO'
(NO TEXT)
RMHBSCC DATA X'1002'
RMHID DATA C'X'
RMHTYP DATA C'P'
RMPTYP DATA F1'
RMPST DATA F-2'
RMPTXTL DATA F13'
RMPTXT DATA C'ENTER COMMAND'
DATA C"
(PAD)
PASSTHRU record received by host
with blocking:
c
RMHBSCC DATA X'1002'
RMHID DATA C'X'
RMHTYP DATA C'P'
RMPTYP DATA F1'
DATA X'SE01' (SKIP=1)
DATA FO'
(NO TEXT)
DATA F-2'
(NEXT SEGMENT)
DATA F13'
DATA C'ENTER COMMAND'
DATA C' ,
(PAD)
Figure 52. Example of PASSTHRU Records Received by Host
Request for Data Record
The Request for Data record is a 6-byte record that contains constant values. A Request for
Data record is always followed by an EOT. The format of the Request for Data record is:
RMHBSCC DATA X'1002'
RMHID DATA C'X'
RMHTYP DATA C'P'
RMPTYP DATA F2'
o
Chapter 2. Remote Management Utility ($RMU)
CO-I07
Remote Management Utility ($RMU)
Interacting Between Host and Remote Systems (PASSTHRU) (continued)
Program End Record
o
The Program End record is a 6-byte record that contains constant values. A Program End
record is always followed by an EOT. The format of the Program End record is:
RMHBSCC DATA X'1002'
RMHID DATA C'X'
RMHTYP DATA C'P'
RMPTYP DATA F'3'
No Data Record
The No Data record is a 6-byte record that contains constant values. A No Data record is
always followed by an EOT. The format of the No Data record is:
RMHBSCC DATA X'1002'
RMHID DATA C'X'
RMHTYP DATA C'P'
RMPTYP DATA F'4'
PASSTHRU Blocking
When PASSTHRU records are not blocked, each Text or PF Key record contains only one text
segment. With blocking, each record may contain mUltiple text segments. For PASSTHRU
sessions in which the host receives many consecutive lines of output, such as a result of a "list"
command to a utility, blocking allows more efficient usage of the communications line.
!(:~)
The host specifies blocking in the RMPRBLK field of the PASSTHRU request. If this field is
zero, blocking is not performed. A value greater than zero indicates the maximum size, in bytes,
of the text segments which the host can process.
To determine the value for the RMPRBLK field, start with the size of the buffer at the host.
Subtract 6 from the size of the host buffer for the 6-byte main segment of each record. Then
subtract 2 more to allow space for the ETX plus one byte for word alignment. The resulting
number is the maximum block size.
$RMU will use this value if it can. However, if $RMU does not have a buffer as large as the
value of RMPRBLK, $RMU will use the largest block size it can.
The host must determine the length of the Text or PF Key record and process each text segment
until the end of the record is reached. If a text record exceeds the block size specified in
RMPRBLK, $RMU still-sends that record to the host. This may result in a "wrong length
record" condition. The host should ensure that it can handle the longest length record expected
from the utility. For example, if the longest text record is 132 bytes, a block size of 136 would
be sufficient for all records.
o
CO-I08
SC34-0638
()
Interacting Between Host and Remote Systems (PASSTHRU) (continued)
Sample Programs
The following sample Series/1 programs communicate with and perform functions of the
Remote Management Utility.
Multifunction Program
This program executes on a host Series/land communicates with $RMU on a remote Series/1.
The program performs all the functions of $RMU except SEND, RECEIVE, and PASSTHRU.
The program sends an ALLOCATE request and prints a status message, but can be used for the
other functions by simply defining the fields of the desired request at label "RM."
UT
START
*
o
*
*
TERM
*
BSCERR
PROGRAM START
EQU
*
BSCOPEN IOCB,ERROR=BSCERR
IOCB3,+REQLEN
MOVE
OPEN BSC LINE
LENGTH OF REQUEST
IN IOCB
BSCWRITE IX, IOCB,ERROR=BSCERR WRITE REQUEST
WRITE EOT
BSCWRITE E,IOCB,ERROR=BSCERR
MOVEA
IOCB2,ST
ADDRESS OF STATUS
IOCB3,20
LENGTH OF STATUS
MOVE
IN IOCB
BSCREAD I,IOCB,ERROR=BSCERR,TIMEOUT=NO READ STATUS
IOCB,IOCB2,RESULT=PN2 LENGTH INTO PRINTNUM
SUB
ADD
PN2,+1
PN2,1
CONVERT LENGTH TO WORDS
SHIFTR
PRINTEXT '@STATUS MESSAGE:@'
PRINTNUM ST,O,MODE=HEX,P2=PN2 PRINT STATUS MSG
READ EOT
BSCREAD C,IOCB,ERROR=BSCERR,TIMEOUT=NO
(ST+6,EQ,-1)
IF SUCCESSFUL STATUS
IF
THEN
PRINTEXT '@FUNCTION SUCCESSFUL'
ELSE
ELSE
PRINTEXT '@FUNCTION FAILED'
ENDIF
ENDIF
POINT
TERMINATION
EQU
*
CLOSE BSC LINE
BSCCLOSE IOCB
PROGSTOP
EQU
MOVE
PRINTEXT
PRINTNUM
GO TO
*
ST,UT
'@BSC ERROR:'
ST
TERM
BSC ERROR ROUTINE
MOVE RETURN CODE
PRINT RETURN CODE
GO TO TERMINATION
Figure 53 (Part 1 of 2). Multifunction Sample Program
o
Chapter 2. Remote Management Utility ($RMU)
CO-109
Remote Management Utility ($RMU)
o
Sample Programs (continued)
IOCB
*
*
*
ST
*
*
*
*
*
*
*-*
RM
9,RM,0,P2=IOCB2,P3=IOCB3
IOCB
P2=IOCB2 IS MESSAGE ADDRESS
P3=IOCB3 IS MESSAGE LENGTH
DATA
10F'0'
AREA FOR STATUS RECORD
10 BYTES NORMAL STATUS RECORD
8 BYTES IDCHECK STATUS EXT.
ETX
1 BYTE
TOTAL, ROUNDED UP TO
10 WORDS
THE FOLLOWING MAY BE CHANGED FOR OTHER REQUESTS --*
RMHBSCC
RMHID
RMHTYP
RMREQ
RMADSN
RMAVOL
RMANREC
RMADST
REQLEN
*
BSCIOCB
19 BYTES
EQU
DATA
DATA
DATA
DATA
DATA
DATA
DATA
DATA
EQU
*
X'1002'
C'X'
C'R'
F'2'
CL8'MYDATA'
CL6'MYVOL'
D' 10'
F'1 '
*-RM
REQUEST
BSC CTRL CHARS (DLE STX)
HEADER ID
HEADER TYPE: REQUEST
REQUEST TYPE: ALLOCATE
. DATA SET NAME: MYDATA
VOLUME NAME: MYVOL
NUMBER RECORDS: 10
DATA SET TYPE: DATA
LENGTH OF REQUEST
ENDPROG
END
Figure 53 (Part 2 of 2). $RMU Multifunction Program
o
CO-110
SC34-0638
o
Sample Programs (continued)
RECEIVE Sample Program
This sample program, which runs on the host, sends a RECEIVE request transferring a data set
to the remote Series/I. The blocking factor for the data is 2, and it is transferred in 80-byte
records.
EXRECV
START
*
*
*
o
DATA
RDEND
PROGRAM START,DS=((RECVDS,??»
EQU
*
BSCOPEN IOCB,ERROR=BSCOPEN
OPEN BSC LINE
MOVE
IOCB3,+REQLEN
LENGTH OF REQUEST IN IOCB
BSCWRITE IX,IOCB,ERROR=BSCERR WRITE REQUEST
BSCWRITE E,IOCB,ERROR=BSCERR WRITE EOT
MOVEA
IOCB2,ST
MOVE
IOCB3,+STL
BSCREAD I,IOCB,ERROR=BSCERR
BSCREAD C,IOCB,ERROR=BSCERR
IF
(STSFN,NE,-1)
PRINTEXT '@STATUS INDICATES
PRINTNUM ST,5,MODE=HEX
GOTO
TERM1
ENDIF
ADDRESS OF STATUS
LENGTH OF STATUS IN IOCB
READ STATUS
READ EOT
IF STATUS INDICATES ERROR
ERROR' THEN PRINT IT
TERMINATE
ENDIF
MOVEA
IOCB2,DT
ADDRESS OF DATA
MOVE
IOCB3,+DTL
SET LENGTH
EQU
*
READ
DS1,DISKREC,ERROR=RDERR,END=RDEND READ RECORD
MOVE
DTDATA,DISKREC,(80,BYTE)
FIRST RECORD
MOVE
DTDATA+80,DISKREC+128, (80,BYTE) SECOND RECORD
IF
(COUNT,EQ,O)
IF FIRST TIME THEN
BSCWRITE IX,IOCB,ERROR=BSCERR,END=BSCAB WRITE INITIAL
ELSE
ELSE
BSCWRITE CX,IOCB,ERROR=BSCERR,END=BSCAB WRITE CONTINUE
ENDIF
ENDIF
ADD
COUNT, 2
ADD 2 TO COUNT
GOTO
DATA
CONTINUE TRANSFERRING DATA
EQU
*
TO HERE WHEN AT ENDFILE
BSCWRITE E,IOCB,ERROR=BSCERR WRITE EOT
BSCREAD I,IOCB,ERROR=BSCERR READ COUNT
BSCREAD C,IOCB,ERROR=BSCERR READ EOT
IF
(DTCCNT,EQ,COUNT)
IF COUNT OK THEN
PRINTEXT 'COUNT OK:'
PRINT IT
PRINTNUM COUNT
ELSE
ELSE
PRINTEXT '@COUNT FAILED. COUNTED:'
PRINTNUM COUNT
PRINT COUNTS
PRINTEXT' COUNT RECORD:'
PRINTNUM DTCCNT
ENDIF
ENDIF
Figure 54 (Part 1 of 4). RECEIVE Sample Program
o
Chapter 2. Remote Management Utility ($RMU)
CO-Ill
Remote Management Utility ($RMU)
o
Sample Programs (continued)
TERM 1
TERM2
BSCAB
*
BSCERR
*
BSCOPEN
EQU
BSCCLOSE
EQU
PROGSTOP
EQU
BSCREAD
BSCREAD
PRINTEXT
PRINTNUM
GOTO
ABORT RECEIVED ON WRITE
I,IOCB,ERROR=BSCERR READ STATUS
C,IOCB,ERROR=BSCERR READ EOT
'@ABORT RECEIVED. STATUS:'
DT,5,MODE=HEX
TERM1
TERMINATE
EQU
*
MOVE
PRINTEXT
PRINTNUM
GOTO
ST,EXRECV
'@BSC ERROR:'
ST
TERM1
EQU
*
MOVE
PRINTEXT
PRINTNUM
GOTO
OPEN ERROR
ST,EXRECV
MOVE RETURN CODE
'@BSC OPEN ERROR:'
ST
PRINT RETURN CODE
TERM2
GO TO TERMINATION
*
*
*
IOCB
EXIT POINT FOR NORMAL TERM
CLOSE BSC LINE
EXIT POINT FOR OPEN FAILED
BSC ERROR ROUTINE
MOVE RETURN CODE
PRINT RETURN CODE
GO TO TERMINATION
Figure 54 (Part 2 of 4). RECEIVE Sample Pr~am
o
CO-112
SC34-0638
o
Sample Programs (continued)
*
EQU
*
MOVE
PRINTEXT
PRINTNUM
MOVEA
DISK READ ERROR
MOVE RETURN CODE
ST,EXRECV
'@DISK READ ERROR: '
PRINT RETURN CODE
ST
POINT IOCB TO
IOCB2,ST
STATUS MESSAGE
IOCB3,4
SET LENGTH TO 4
MOVE
ST,X'1002'
SET UP STATUS MESSAGE
MOVE
ST+2,C'XS'
MOVE
BSCWRITE IX, IOCB,ERROR=BSCERR SEND STATUS MESSAGE
BSCWRITE E,IOCB,ERROR=BSCERR SEND EOT
GO TO TERMINATION
GOTO
TERM2
RDERR
*
*IOCB
*
*
*
RLEN*
COUNT
*--
*
c
BSCIOCB
9,RM,O,P2=IOCB2,P3=IOCB3
IOCB
P2= IS RECORD ADDRESS
P3= IS RECORD LENGTH
DATA
F'O'
RECORD LENGTH
DATA
F'O'
RECORD COUNT
REQUEST FOR $RMU TO RECEIVE A DATA SET
RM
RMHBSCC
RMHID
RMHTYP
RMREQ
RMRDSN
RMRVOL
RMRSTR
RMRTYP
RMRBLK
REQLEN
EQU
DATA
DATA
DATA
DATA
DATA
DATA
DATA
DATA
DATA
EQU
*
X'1002'
C'X'
C'R'
F'1'
CL8'MYDATA'
CL6'
D'O'
F'1'
F'2'
*-RM
REQUEST
BSC CNTRL CHARS (DLE STX)
HEADER ID
HEADER TYPE:
REQUEST
REQUEST TYPE:
RECEIVE
DATA SET NAME:
MYDATA
VOLUME NAME:
(IPL VOL)
STARTING RECORD: NONE
RECEIVE TYPE:
SOURCE
BLOCKING FACTOR: 2
LENGTH OF REQUEST
Figure 54 (Part 3 of 4). RECEIVE Sample Program
o
Chapter 2. Remote Management Utility ($RMU)
CO-113
Remote Management Utility ($RMU)
o
Sample Programs (continued)
*--
STATUS RECORD
*
ST
*
*
*
STSFN
STL
**-*
DT
DATA
10F'O'
AREA FOR STATUS RECORD
EQU
EQU
ST+6
*-ST
STATUS FUNCTION
STATUS RECORD LENGTH
DATA AND COUNT RECORD
DTCCNT
DTDATA
DTL
*
DISKREC
DATA
DATA
EQU
DATA
EQU
X'1002'
C'XD'
DT+l0
160C' ,
*-DT
DATA 128F'O'
ENDPROG
END
DATA RECORD: DLE STX
HEADER ID, TYPE (DATA)
LOCATION OF COUNT
LENGTH
DISK RECORD AREA
Figure S4 (Part 4 of 4). RECEIVE Sample Program
o
CO-114
SC34-0638
o
Sample Programs (continued)
SEND Sample Program
This program, which runs on the host, contains a SEND request. It asks the remote system to
transfer a data set to the host. Data is blocked with a factor of 3, and transferred in 2S6-byte
records.
EXSEND
START
DATA
*
*
*
PROGRAM START,DS=((SENDDS,??»
EQU
*
BSCOPEN IOCB,ERROR=BSCOPEN
OPEN BSC LINE
MOVE
IOCB3,+REQLEN
LENGTH OF REQUEST IN IOCB
BSCWRITE IX,IOCB,ERROR=BSCERR WRITE REQUEST
BSCWRITE E,IOCB,ERROR=BSCERR WRITE EOT
MOVEA
IOCB2,ST
ADDRESS OF STATUS
MOVE
IOCB3,+STL
LENGTH OF STATUS IN IOCB
BSCREAD I,IOCB,ERROR=BSCERR READ STATUS
IF
(STSFN,NE,-1)
IF STATUS INDICATES ERROR
BSCREAD C,IOCB,ERROR=BSCERR
READ EOT
PRINTEXT '@STATUS INDICATES ERROR' THEN PRINT IT
PRINTNUM ST,5,MODE=HEX
GOTO
TERM1
TERMINATE
ENDIF
ENDIF
MOVEA
IOCB2,DT
ADDRESS OF DATA
EQU
*
IOCB3,+DTL
SET LENGTH TO MAX
MOVE
BSCREAD C,IOCB,ERROR=BSCERR READ DATA OR COUNT
IOCB,IOCB2,RESULT=RLEN COMPUTE LENGTH
SUB
(DTHTYPR,EQ,C'D' ,BYTE) IF DATA THEN
IF
RLEN,+4
-4 FROM LENGTH
SUB
FOR HEADER
RLEN = NUMBER RECORDS
SHIFTR
RLEN,8
WRITE RECORDS NEXT
DS1,DTDATA,RLEN,ERROR=WRERR,END=WRERR
WRITE
COUNT,RLEN
ADD NUMBER WRITTEN
ADD
TO COUNT
GO READ NEXT RECORD
GOTO
DATA
ELSE
ELSE
(DTHTYPR,EQ,C'C' ,BYTE) IF COUNT THEN
IF
IF
(DTCCNT,EQ,COUNT)
IF COUNT OK THEN
PRINTEXT 'COUNT OK:'
PRINT IT
PRINTNUM COUNT
ELSE
ELSE
PRINTEXT 'COUNT FAILED. COUNTED:'
PRINTNUM COUNT
PRINT COUNTS
PRINTEXT' COUNT RECORD:'
PRINTNUM DTCCNT
ENDIF
ENDIF
ELSE MUST BE STATUS
ELSE
PRINTEXT 'ERROR MSG RECEIVED:'
PRINT IT
PRINTNUM DT,5,MODE=HEX
ENDIF
ENDIF
ENDIF
ENDIF
BSCREAD C,IOCB,ERROR=BSCERR READ EOT
Figure 55 (Part 1 of 3). SEND Sample Program
o
Chapter 2. Remote Management Utility ($RMU)
CO-tts
Remote Management Utility ($RMU)
Sample Programs (continued)
TERM 1
TERM2
BSCERR
*
BSCOPEN
*
WRERR
EQU
BSCCLOSE
EQU
PROGSTOP
EQU
*
MOVE
PRINTEXT
PRINTNUM
GO TO
()
*
*
IOCB
ST,EXSEND
'@BSC ERROR:'
ST
TERM1
EXIT POINT FOR NORMAL TERM
CLOSE BSC LINE
EXIT POINT FOR OPEN FAILED
BSC ERROR ROUTINE
MOVE RETURN CODE
PRINT RETURN CODE
GO TO TERMINATION
EQU
*
MOVE
PRINTEXT
PRINTNUM
GOTO
OPEN ERROR
ST,EXSEND
MOVE RETURN CODE
'@BSC OPEN ERROR:'
ST
PRINT RETURN CODE
TERM2
GO TO TERMINATION
EQU
*
MOVE
PRINTEXT
PRINTNUM
BSCWRITE
MOVEA
MOVE
MOVE
MOVE
BSCWRITE
BSCWRITE
GO TO
WRITE ERROR
MOVE RETURN CODE
ST,EXSEND
'@DISK WRITE ERROR:'
PRINT RETURN CODE
ST
E,IOCB,ERROR=BSCERR WRITE EOT (ABORT)
POINT IOCB TO STATUS
IOCB2,ST
SET LENGTH TO 4
IOCB3,4
SET UP STATUS MESSAGE
ST,X'1002'
ST+2,C'XS'
IX, IOCB,ERROR=BSCERR WRITE STATUS
E,IOCB,ERROR=BSCERR WRITE EOT
GO TO TERMINATION
TERM 1
Figure 55 (Part 2 of 3). SEND Sample Program
o
CO-116
SC34-0638
o
0
Sample Programs (continued)
*
BSCIOCB
9,RM,O,P2=IOCB2,P3=IOCB3
IOCB
IOCB
*
P2=IOCB2 IDENTIFIES MSG ADDRESS
*
P3=IOCB3 IDENTIFIES MSG LENGTH
*
F'O'
RECORD LENGTH
RLEN
DATA
*
F'O'
DATA
RECORD COUNT
COUNT
*
*-- REQUEST FOR $RMU TO SEND DATA SET
*
REQUEST
RM
EQU
*
BSC CNTRL CHARS (DLE STX)
RMHBSCC DATA x'1002'
HEADER ID
RMHID
DATA C'X'
REQUEST
HEADER TYPE:
RMHTYP
DATA C'R'
REQUEST TYPE:
SEND
RMREQ
DATA F'O'
DATA SET NAME:
MY DATA
RMSDSN
DATA CL8'MYDATA'
(IPL VOL)
VOLUME NAME:
RMSVOL
DATA CL6'
RMSSTR
DATA D'O'
STARTING RECORD: NONE
SEND TYPE:
NORMAL
RMSTYP
DATA F'O'
BLOCKING FACTOR: 3
RMSBLK
DATA F'3'
LENGTH OF REQUEST
REQLEN
EQU
*-RM
*-- STATUS RECORD
*
AREA FOR STATUS RECORD
DATA 10F'O'
ST
*
*
*
STATUS FUNCTION
STSFN
EQU
ST+6
STATUS RECORD LENGTH
STL
EQU
*-ST
*
*-- DATA AND COUNT RECORD
*
DATA 387F'O'
AREA FOR DATA RECORD
DT
4 BYTES MESSAGE HEADER
*
768 BYTES 3 256-BYTE RECS
*
1 BYTE
ETX
*
*
773 BYTES TOTAL, ROUNDED UP
*
TO 387 WORDS
*
RECORD TYPE
DT+3
DTHTYPR EQU
DATA
DTDATA
EQU
DT+4
COUNT
DTCCNT
EQU
DT+10
LENGTH
DTL
EQU
*-DT
ENDPROG
END
Figure 55 (Part 3 of 3). SEND Sample Program
PASSTHRU Sample Program
This sample program executes a PASSTHRU session. The host Series/I establishes a session
with the supervisor of a remote Series/I. The program uses blocking. The host terminal looks
as if it were connected to the remote system.
o
Chapter 2. Remote Management Utility ($RMU)
CO-II?
Remote Management Utility ($RMU)
o
Sample Programs (continued)
EXPASST
*
*
*
*
*
*
*
*
*
*
*
*
*
*
START
**-*
*
*
*
*
PROGRAM START,TERMERR=TERM1
THIS EXAMPLE HOST PROGRAM USES THE PASSTHRU FUNCTION
OF THE REMOTE MANAGEMENT UTILITY. THE OPERATOR IS
ASKED WHETHER TO START THE PASSTHRU ASSIST PROGRAM.
IF SO, THE PROGRAM $RMUPA IS INVOKED. AFTER THIS, A
SESSION IS ESTABLISHED WITH THE EDX SUPERVISOR.
WHENEVER A "PROGRAM END" PASSTHRU RECORD IS RECEIVED,
A "REQUEST DATA" RECORD IS SENT. WHEN A "NO DATA"
RECORD IS RECEIVED, THE OPERATOR IS ASKED WHETHER TO
"ATTN" (END THE SESSION AND START ANOTHER), "READ"
(TRY TO ACQUIRE DATA FROM THE HOST), OR "QUIT" (END
THE PASSTHRU SESSION AND THEN TERMINATE.
EQU
*
BSCOPEN
IOCB,ERROR=BSCOPEN
OPEN BSC LINE
START UP PASSTHRU ASSIST PROGRAM ($RMUPA) IF NEEDED
QUESTION 'START PASSTHRU ASSIST PROGRAM?' , NO=START2
MOVEA
MOVE
BSCWRITE
BSCWRITE
IOCB2,REQPTAS
IOCB3,+REQPTASL
IX,IOCB,ERROR=BSCERR
E,IOCB,ERROR=BSCERR
ADDRESS OF REQUEST IN IOCB
LENGTH OF REQUEST IN IOCB
WRITE REQUEST
WRITE EOT
ADDRESS OF STATUS
IOCB2,ST
MOVEA
LENGTH OF STATUS IN IOCB
MOVE
IOCB3,+STL
BSCREAD I,IOCB,ERROR=BSCERR READ STATUS
BSCREAD C,IOCB,ERROR=BSCERR READ EOT
IF
(STSFN,NE,-1)
IF STATUS INDICATES ERROR
PRINTEXT '@STATUS INDICATES ERROR' PRINT IT
PRINTNUM ST,5,MODE=HEX
GOTO
TERM 1
TERMINATE
ENDIF
ENDIF
IOCB2,DT
ADDRESS OF DATA
MOVEA
MOVE
IOCB3,+DTL
SET LENGTH
BSCREAD I, IOCB,ERROR=BSCERR,TIMEOUT=NO
READ, EXPECT PROGRAM END
BSCREAD C,IOCB,ERROR=BSCERR,TIMEOUT=NO
READ EOT
(EXPASST,EQ,+1) ,AND, (DT+RMPTYP,EQ,+RMPTYPPE)
IF
IF PGM END AND EOT THEN
DT,X'1002'
SET UP PTHRU PGM END
MOVE
MOVE
DT+RMPTYP,+RMPTYPPE PTHRU TYPE IS PGM END
IOCB3,+RMPX
SET UP LENGTH IN IOCB
MOVE
BSCWRITE IX,IOCB,ERROR=BSCERR,END=BSCAB WRITE TO RMU
BSCWRITE E,IOCB,ERROR=BSCERR WRITE EOT
Figure S6 (Part 1 of 7). PASSTHRU Sample Program
o
CO-tt8
SC34-0638
o
Sample Programs (continued)
ELSE
MOVE
PRINTEXT
PRINTEXT
PRINTNUM
PRINTEXT
PRINTNUM
GOTO
ENDIF
ELSE
ST,EXPASST
SAVE RETURN CODE
'@UNSUCCESSFUL LOAD OF PASSTHRU ASSIST PGM. '
'@LAST MESSAGE READ: '
DT,10,MODE=HEX
PRINT MESSAGE
'@LAST RETURN CODE FROM READ:'
ST,MODE=HEX
PRINT RETURN CODE
TERM1
TERMINATE
ENDIF
*
MAIN PASSTHRU PROCESSING.
*START2 MOVEA
IOCB2,REQPT
*--
SEND REQUEST
ADDRESS OF REQUEST IN IOCB
MOVE
IOCB3,+REQLEN
LENGTH OF REQUEST IN IOCB
BSCWRITE IX,IOCB,ERROR=BSCERR WRITE REQUEST
BSCWRITE E,IOCB,ERROR=BSCERR WRITE EOT
*
o
MOVEA
IOCB2,ST
MOVE
IOCB3,+STL
BSCREAD I,IOCB,ERROR=BSCERR
BSCREAD C,IOCB,ERROR=BSCERR
IF
(STSFN,NE,-1)
PRINTEXT '@STATUS INDICATES
PRINTNUM ST,5,MODE=HEX
GOTO
TERM 1
ENDIF
ADDRESS OF STATUS
LENGTH OF STATUS IN IOCB
READ STATUS
READ EOT
IF STATUS INDICATES ERROR
ERROR' PRINT IT
TERMINATE
ENDIF
Figure 56 (Part 2 of 7). PASSTHRU Sample Program
o
Chapter 2. Remote Management Utility ($RMU)
CO-119
Remote Management Utility ($RMU)
o
Sample Programs (continued)
READ
*
*
*--
*
TEXT
*
*
*
*
EQU
*
MOVE A
IOCB2,DT
ADDRESS OF DATA
MOVE
IOCB3,+DTL
SET LENGTH
IF
(BSCST,NE,+BSCSTRD) IF BSC STATE IS NOT READ
BSCREAD I,IOCB,ERROR=BSCERR,TIMEOUT=NO
READ INIT
MOVE
BSCST,+BSCSTRD
BSC STATE
READ
ELSE
ELSE
BSCREAD C,IOCB,ERROR=BSCERR,TIMEOUT=NO
READ CONT
ENDIF
ENDIF
IF
(DT+RMHTYP,NE,C'P',BYTE) IF NOT PASSTHRU THEN
PRINTEXT '@NON-PASSTHRU MESSAGE RECEIVED:'
PRINTNUM DT,5,MODE=HEX
PRINT WHAT WAS RECEIVED
(WILL BE STATUS)
BSCREAD C,IOCB,ERROR=BSCERR,TIMEOUT=NO
READ EOT
GO TO
TERM 1
TERMINATE
ENDIF
ENDIF
CASE: PASSTHRU TYPE
GO TO
(ERRPT,TEXT,REQD,PGME,NODA),DT+RMPTYP
PASSTHRU TYPE: DATA
SET #1 TO BEGINNING OF TXT
DO UNTIL AT END OF TEXT
UNTIL, (#1,EQ,IOCB)
(IOCB CONTAINS ADDRESS
OF BYTE PAST LAST BYTE
OF DATA)
IF
( (0, # 1 ) , EQ , -1 ) , OR, ( (0, # 1 ) , EQ , - 2) IF TEXT
PRINTEXT (4,#1) ,MODE=LINE
PRINT TO TERMINAL
IF
((0,#1),EQ,-1)
IF NEWLINE
PRINTEXT SKIP=1
THEN DO NEWLINE
ENDIF
ENDIF
ADD
#1, (2,#1)
POINT #1 TO NEXT TEXT
ADD
#1,5
ADD HEADER LENGTH + 1
AND
#1,X'FFFE'
POINT TO EVEN BOUNDARY
ELSE
ELSE
IF
((0,#1),EQ,X'8F',BYTE) IF LINE= THEN
AND
(0,#1) ,X'OOFF' ,RESULT=N1 DO IT
PRINTEXT LINE=N1
ON TERMINAL
ELSE
ELSE
IF
((0,#1),EQ,X'8E',BYTE) IF SKIP= THEN
AND
(0,#1),X'00FF' ,RESULT=N1 DO IT
PRINTEXT SKIP=N1
ON TERMINAL
ENDIF
ENDIF
ENDIF
ENDIF
ADD
#1,4
POINT #1 TO NEXT
TEXT BLOCK
ENDIF
ENDIF
ENDDO
ENDDO
END TEXT PROCESSING
GO TO
READ
EQU
MOVEA
DO
*#1,DT+RMPST
Figure 56 (Part 3 of 7). PASSTHRU Sample Program
o
CO-120
SC34-0638
o
Sample Programs (continued)
REQD
*
*
PGME
0
*
NODA
NODAQ
*
*
EQU
*
PASSTHRU TYPE: REQ DATA
BSCREAD C,IOCB,ERROR=BSCERR READ EOT
MOVE
DT+RMPTXTL,X'FEOO'
SET UP "TEXT" STATEMENT
READTEXT DT+RMPTXT,MODE=LINE GET TEXT FROM TERMINAL
MOVE
DT,X'1002'
SET UP PTHRU TEXT RECORD
DT+RMPTYP,+RMPTYPTX PTHRU TYPE IS TEXT OR PFK
MOVE
MOVE
DT+RMPTXTL,O,BYTE
ZERO HI-ORDER LENGTH BYTE
IF
(DT+RMPTXTL,GE,4) ,AND, (DT+RMPTXT,EQ,C'$P'),
AND, (DT+TXT2,EQ,C'F' ,BYTE) IF "$PFN" ENTERED
MOVE
DT+RMPTXTL,-1
INDICATE PF KEY
MOVE
DT+RMPTXT,DT+TXT2
PLACE NUMBER IN MSG
AND
DT+RMPTXT,X'OOOF'
PURIFY NUMBER
MOVE
IOCB3,2+RMPTXT
LENGTH IN IOCB
ELSE
ELSE
MOVE
IOCB3,DT+RMPTXTL
SET UP LENGTH IN IOCB
ADD
IOCB3,+RMPTXT
INCLUDING HEADER
ENDIF
ENDIF
BSCWRITE IX,IOCB,ERROR=BSCERR,END=BSCAB WRITE TO RMU
BSCWRITE E,IOCB,ERROR=BSCERR WRITE EOT
MOVE
BSCST,+BSCSTO
BSC STATE = RESET
GOTO
READ
END REQ TEXT PROCESSING
PASSTHRU TYPE:
EQU
*
BSCREAD
GO TO
C,IOCB,ERROR=BSCERR
SNDRQD
PROGRAM END
(DISCONNECT)
READ EOT
GO AND REQUEST DATA
*
PASSTHRU TYPE: NO DATA
C,IOCB,ERROR=BSCERR READ EOT
'@"NO DATA" RECEIVED. ENTER ONE:'
INMSG,'@ A(TTN), R(EAD), Q(UIT) ,
(INMSG,EQ,C'A' ,BYTE) ,OR, (INMSG,EQ,C'Q' ,BYTE)
IF "ATTN" OR "QUIT" THEN
SEND PROGRAM END
DT,X'1002'
SET UP PTHRU PGM END
MOVE
DT+RMPTYP,+RMPTYPPE PTHRU TYPE IS PGM END
MOVE
IOCB3,+RMPX
SET UP LENGTH IN IOCB
MOVE
BSCWRITE IX,IOCB,ERROR=BSCERR,END=BSCAB WRITE TO RMU
BSCWRITE E,IOCB,ERROR=BSCERR WRITE EOT
BSCST,+BSCSTO
BSC STATE = RESET
MOVE
EQU
BSCREAD
PRINTEXT
READTEXT
IF
Figure S6 (Part 4 of 7). PASSTHRU Sample Program
Chapter 2. Remote Management Utility ($RMU)
CO-121
Remote Management Utility ($RMU)
o
Sample Programs (continued)
(INMSG,EQ,C'A' ,BYTE) ,GOTO,START2
IF "A" THEN START NEW
SESSION
TERM 1
OTHERWISE TERMINATE
GOTO
ELSE (NOT "ATTN"
ELSE
OR "QUIT")
(INMSG,EQ,C'R') ,GOTO,SNDRQD IF "R" THEN
IF
REQUEST DATA
NODAQ
ELSE ASK AGAIN
GOTO
ENDIF
ENDIF
*
PASSTHRU TYPE: UNKNOWN
EQU
PRINTEXT '@INVALID PASSTHRU RECORD RECEIVED:'
PRINTNUM DT,20,MODE=HEX
TERM 1
TERMINATE
GOTO
IF
*
*
*
*
ERRPT
*
*-*
SNDRQD
*
*
TERM 1
TERM2
*
BSCAB
END OF CASES
EQU
MOVE
MOVE
MOVE
BSCWRITE
BSCWRITE
MOVE
GOTO
*
SEND REQUEST DATA
DT,X'1002'
SET UP PTHRU REQUEST DATA
DT+RMPTYP,+RMPTYPRD PTHRU TYPE IS REQEST DATA
IOCB3,+RMPX
SET UP LENGTH IN IOCB
IX,IOCB,ERROR=BSCERR,END=BSCAB WRITE TO RMU
E,IOCB,ERROR=BSCERR WRITE EOT
BSCST,+BSCSTO
BSC STATE = RESET
READ
END REQ TEXT PROCESSING
EQU
*
BSCCLOSE IOCB
EQU
*
PROGSTOP
EQU
BSCREAD
BSCREAD
PRINTEXT
PRINTNUM
GOTO
EXIT POINT FOR NORMAL TERM
CLOSE BSC LINE
EXIT POINT FOR OPEN FAILED
*
ABORT RECEIVED ON WRITE
I,IOCB,ERROR=BSCERR READ STATUS
C,IOCB,ERROR=BSCERR READ EOT
'@ABORT RECEIVED. STATUS:'
DT,20,MODE=HEX
TERM 1
TERMINATE
Figure 56 (Part 5 of 7). PASSTHRU Sample Program
o
CO-i22
SC34-0638
o
Sample Programs (continued)
*
BSCERR
*
EQU
*
MOVE
PRINTEXT
PRINTNUM
GOTO
BSCOPEN
*--
EQU
*
MOVE
PRINTEXT
PRINTNUM
GOTO
DATA AREA
*INMSG
*IOCB
REQLEN
PRINT RETURN CODE
GO TO TERMINATION
OPEN ERROR
ST,EXPASST
MOVE RETURN CODE
'@BSC OPEN ERROR:'
ST
PRINT RETURN CODE
TERM2
GO TO TERMINATION
LENGTH=4
BSCIOCB
9,O,O,P2=IOCB2,P3=IOCB3
IOCB
P2= IS RECORD ADDRESS
P3= IS RECORD LENGTH
*
REQUEST
*REQPT
EQU
c
BSC ERROR ROUTINE
MOVE RETURN CODE
TEXT
*
*
*--
ST,EXPASST
'@BSC ERROR:'
ST
TERM 1
INPUT MSG FROM OPERATOR
FOR PASSTHRU
DATA
DATA
DATA
DATA
DATA
DATA
DATA
DATA
DATA
DATA
EQU
*
X'1002'
C'X'
C'R'
A (RMREQPST)
A(PBL)
H'O'
H'O'
CL8' ,
CL6' ,
3F'O'
*-REQPT
REQUEST
BSC CONTROL CHARS (DLE STX)
HEADER ID
HEADER TYPE:
REQUEST
REQUEST TYPE:
PASSTHRU (12)
PASSTHRU BLKING
FLAG (UNUSED)
PARTITION (UNUSED)
PROGRAM:
EDX SUPERVISOR
VOLUME (UNUSED)
(REMAINDER UNUSED)
LENGTH OF REQUEST
Figure S6 (Part 6 of 7). PASSTHRU Sample Program
o
Chapter 2. Remote Management Utility ($RMU)
CO-123
Remote Management Utility ($RMU)
o
Sample Programs (continued)
**-- PASSTHRU
*
REQPTAS EQU
DATA
DATA
DATA
DATA
DATA
DATA
DATA
DATA
DATA
DATA
DATA
DATA
REQPTASL EQU
REQUEST:
START PASSTHRU ASSIST PROGRAM
*
X'1002'
C'X'
C'R'
A (RMREQPST)
A(O)
H'O'
H'O'
CL8' $RMUPA
'
,
CL6'
F'O'
F'O'
F'O'
*-REQPTAS
**-- STATUS RECORD
*
ST
DATA 10F'O'
*
*
*
STSFN
ST+6
EQU
STL
**-*
DT
EQU
*-ST
DATA
EQU
EQU
2S6F'O'
*-DT
DTL-8
*
*
*
**-- MISCELLANEOUS VARIABLES
*
BSCST
DATA F'O'
BSCSTO
BSCSTRD
N1
*
RECORD
LENGTH
PASSTHRU BLOCK LENGTH
LENGTH OF DATA AREA 6 BYTES FOR HEADER AND 2
FOR ETX AND WORD ROUND UP
0
1
F'O'
BSC STATE:
RESET
READING
WORK WORD
COPY
EQU
CDRRM
RMPTXT+2
INCLUDE DEFINITION OF RMU MSGS
BYTE 2 OF PASSTHRU TEXT
Figure 56 (Part 7 of 7). PASSTHRU Sample Program
SC34-0638
STATUS FUNCTION
STATUS RECORD LENGTH
EQU
EQU
DATA
ENDPROG
END
CO-124
AREA FOR STATUS RECORD
PASSTHRU SESSION AREA
DTL
PBL
TXT2
*
REQUEST
BSC CONTROL CHARS (DLE STX)
HEADER ID
HEADER TYPE:
REQUEST
REQUEST TYPE:
PASSTHRU ( 12)
PASSTHRU BLKING
(NONE)
FLAG (UNUSED)
(ANY)
PARTITION
PROGRAM:
$RMUPA
VOLUME:
IPL
FREE SPACE:
NONE
PARAMETERS:
NONE
NONE
DATA SETS:
LENGTH OF REQUEST
o
Sample Programs (continued)
Example of Conducting a PASSTHRU Session
In this example of conducting a PASSTHRU session, the host invokes and runs the $DEBUG
utility.
$L EXPASST
EXPASST 9P LP=C900
>
START PASSTHRU ASSIST PROGRAM? Y
$L $DEBUG
$DEBUG27P,09:44:08 LP=BFOO
>
PROGRAM NAME: $DISKUTl
$DISKUTl 30P ,09:44: 14 LP=DAOO
REQUEST "HELP.. TO GET LIST OF DEBUG COMMANDS
TASK STQPP~D AT 0064
"NODATA+lRECEIVED. ENTER ONE:
A(TTN), R(EAD), Q(UIT} A
> WHERE
TASK STOPPED AT 0064
$A'rTASKAT2600
"NO:DATA~ RECE IVED. ENTER ONE:
ACTTN), R(EAD), Q(UIT} A
o
Figure 57 (Part 1 of 4). Example of Conducting a PASSTHRU Session
GO
OPTlQN(*/ADDR/TASK/ALU: ALL
1 BREAKPO I NT{ S) ACTI VATED
USING VOLUME EDX002
>
COMMAND (?): LA ZZZZ
USING VOLUME EDX002
NAME
FREC SIZE
12845 FREERECORO$ IN LIBRARY
COMMAND (?): $PFO
XX
> WHERE
INVALID COMMAND
TASK
AT 0274
,$ATTASKCAT 2~OO
Figure 57 (Part 2 of 4). Example of Conducting a PASSTHRU Session
o
Chapter 2. Remote Management Utility ($RMU)
CO-12S
Remote Management Utility ($RMU)
Sample Programs (continued)
COMMA.ND,{ 11 :$pr~
xX,
.
....::,.wAT·, ... ;,'
.INVALID;COMMAf\I.D,..
.. :
.', ~RT IONf~IADDRI:1:A~K/ALI..l.:
B~EAKPOtNTADDR:: .•••.. 274
.
L.IS1IN.~lIST:....N
.STOP/NOSTOP :' S
..·t\8~EAKPO I NT ($) '$ ET
COMMAND:'."'. XX
TA$IU STA 274 5X
0274 x'80AF lOlOC~D5E5C1 D3C9'
"NO DATA..... RECE WEll, ENTER ONE :
A{TTN)~ R(EAD), ,CUlT) A
> END
1 BREAKPOINT(S) REMOVED
I NVALI D COMMAND
Figure 57 (Part 3 of 4), Example of Conducting a PASSTHRU Session
COMMAND '(1 ):EN
, . ,NO.DATA..... REtE IVEf). '. ENTER ONE:
A{'(TN), R(EAD},Q(UIT) R
"NO.DATA.... RECEI,VED. ENTE~ ONE:
ACTIN), R ( EAD }..,'Q (U I T) A
> .$RM'UPA'
, ,NO ;I)ATA'" RECEI VED '.E NTER "ON~ :
A(TTN)~R(EADY;QfuIT) A
~$A
,
PROGRAMS AT 09:5():26
'N PARTITION.ll
NONE
"NODATA~RECE IVED ~ .ENT£RQNE:
AJTTN),:R (EAD), Q(U IT)Q.
.' EXPASSt ENDED
Figure 57 (Part 4 of 4). Example of Conducting a PASSTHRU Session
CO-126
SC34-0638
(j
o
Chapter 3. Host Communications Facility
o
When Series/ 1 has the Host Communication Facility (HCF) loaded on it, it can communicate
with a host system to perform various functions. The host system has the Host Communication
Facility Installed User Program (IUP 5796-PGH) executing on it. The Host Communications
Facility allows the Series/ 1 to perform file transfers and to submit job streams to the host.
You must write the application program that communicates with the host system. It must
contain Event Driven Language TP instructions. These instructions perform various
communications functions between the Series/l and the host. Your program can perform the
following functions:
Write to a host data set
•
Read from a host data set
•
Submit a background job to the host system
•
Obtain the time and date from the host system
Set the occurrence of a Series/l event so that it can be tested by a program running on the
host system
•
Test for the occurrence of an event that is set by the host system
Erase the record, on the host system, of an event that occurred on either the Series/lor the
host system.
You can also perform HCF functions with the $HCFUTl utility, which provides interactive
capability between the Series/land the host.
o
Chapter 3. Host Communications Facility
CO-127
Host Communications Facility
Planning to Use the Host Communications Facility
Certain requirements and restrictions apply to the operation of the Host Communications
Facility.
Installation Requirements
Both the host and Series/1 must meet certain installation requirements for successful
communications through HCF. The host must have the HCF IUP 5796-PGH executing on it.
The BSC line connecting the Series/1 to the System/370 must be point-to-point leased. Only
the BSC Single Line Control (feature #2074) can be used to attach the line to the Series/1.
System generation for the Series/1 must support the Host Communications Facility. The
appropriate supervisor modules and the TPCOMM system configuration statement provide this
support. Refer to the Installation and System Generation Guide for information.
Host Data Sets
Host data sets in your HCF programs must be named according to a naming convention. Also,
your program can open only one host data set at a time.
Host Data Set Naming Conventions
When you refer to a host data set in a TP instruction, its name must consist of an alphanumeric
character string immediately preceded by one word specifying the length of the name field. You
can do this most easily by coding a labeled TEXT instruction to define the name; for example:
DSN1
TEXT 'XYZ.EXP1.DATA
Data set names follow standard host system naming conventions and must not exceed 44
characters in length (including delimiting periods). Pad the name field with blanks on the right.
In the case of a partitioned data set and member name, specify a string of the form
dsname(membername); for example:
I
PDSDSN
TEXT 'XYZ.EXP1.DATA(RUN1)
The maximum length of such a string is 54 characters.
To read a data set name from a terminal into a text field, issue a READ TEXT instruction.
CO-128
SC34-0638
o
o
Planning to Use the Host Communications Facility (continued)
Host Data Set Characteristics
You can access host data sets with the following characteristics:
•
they must be catalogued
•
they must be single volume
they must be direct-access
•
they must contain fixed or variable-length records
•
they can be either sequential data sets or members of partitioned data sets.
•
they can be either blocked or unblocked.
Fixed-length logical records must contain an even number of words. In fixed blocked format the
block size must be an integer multiple of the logical record length (LRECL), not exceeding
13030.
You can use either sequential data sets or members of partitioned data sets to submit jobs to the
host. Logical records must be 80 bytes long and can be blocked or unblocked. The size of
blocked records must be a multiple of 80.
c'
Record Sizes
You can use a large range of logical and physical record sizes when writing your program. In
selecting a record size, there is no absolute best choice, but you should consider the following:
•
The basic disk or diskette record size on the Series/lis 256 bytes. Therefore, this is a
natural unit of measure for transfer to and from disk and a natural choice for a logical
record size on the host. This is the default for the TP READ and TP WRITE instructions.
•
A host physical record (block) size of 1536 bytes yields 80 percent utilization of host direct
access storage on an IBM 3330 disk. This size also provides enough record space so that
there will be moderate requirements for buffer storage.
The larger the physical record being transferred between the host and the Series/l (a host
logical record), the higher the effective data transfer rate that will be achieved. Also, the
larger the physical record (block) being transferred between host processor storage and
direct access, the higher will be the effective data rate. The maximum data rate is achieved
when using track size records (13030 bytes for the IBM 3330 disk) for both operations.
•
The large physical records naturally require correspondingly large buffers in your program.
In order to achieve overlapped I/O, multiple buffers are required.
o
Chapter 3. Host Communications Facility
CO-129
Host Communications Facility
Planning to Use the Host Communications Facility (continued)
Variable-Length Records
o
A variable-length record is always prefixed by four bytes of control information. This is called a
Record Descriptor Word or RDW. The RDW consists of two fields.
The length (LL) field (bytes land 2) describes the total length of the record in bytes and is
therefore always four greater than the length of the data field. The 00 field (bytes 3 and 4) is
reserved for use by the host system.
The rest of the record is taken up by the DATA field.
When a variable-length record is transferred from the host to the Series/ l, the total record,
including the LL field, is transferred. When a variable-length record is to be transferred from
the Series/l to the host, you must set the RDW to the proper value.
Opening Host Data Sets
You may open only one host data set open at a time. If a second task attempts to open a data
set, HCF will place it in a queue of tasks waiting to use the facility.
If the task currently using HCF attempts to open a second data set, then the currently open data
set automatically closes, and the second one opens.
System Status Data Set
Synchronization of programs in the host system and the Series/l is accomplished with a status
data set on the host system. Both systems share this data set. You can directly access this
system status data set with the TP SET, TP FETCH, and TP RELEASE instructions. With
these instructions you set the occurrence of events on the Series/ 1 which the host monitors,
tests for and then erases. These are called status functions. You can also perform the status
functions with the $HCFUTl utility.
For example, one program (Program A) makes an entry in the system status data set by
invoking a SET instruction specifying an index and a key. Another program (Program B) tests
for the existence of such an entry with a FETCH or RELEASE referring to the same index and
key names, and receives a positive return code if the entry exists. After performing a SET, the
first program (Program A) could periodically issue a FETCH. A companion program (Program
B) on the other system might also be issuing a periodic FETCH for the agreed-upon index and
key. At the appropriate time, this program (Program B) could issue a RELEASE which would
result in the first program (Program A) receiving a "not found" return code from its next
FETCH. This could be interpreted as a notification by the companion program (Program B)
that the message had been received.
o
CO-l30
SC34-0638
o
Planning to Use the Host Communications Facility (continued)
System Status Data Set Organization
The system status data set has direct organization. You write records into this data set using TP
SET, test for the existence of a record using TP FETCH, or test and delete a record using TP
RELEASE.
A record sent to or retrieved from the status data set consists of three part, two of which are
mandatory:
•
Index entry (mandatory)
•
Key field (mandatory)
•
Data (optional 256-byte field).
Index entries and key fields can each be up to eight EBCDIC characters in length and have
significance for the using programs.
The system status data set has one 268-byte index record capable of containing 22 separate
index entries. An index entry has two parts:
•
Index name - eight EBCDIC characters
•
Key pointer - a 4-byte relative record pointer to the first associated key field record.
A key entry is a 268-byte record with the following format:
•
Forward pointer - a 4-byte relative record number of the next key entry or zero if this is the
last one
•
Key name - eight EBCDIC characters
•
Data - 256 bytes of optional data.
The next record pointer allows more than one key to be associated with a given index. The next
record pointer of the last key field will be set to zero to indicate the end of the chain.
Logically, an unlimited number of key records may be associated with a single index. In
practice, the limiting factor is the physical size of the data set. The distributed data set allows
for a total of 94 key entries.
The system status data set format is defined and allocated during the installation of the Host
Communications Facility Installed User Program.
Appendix B of the Host Communications Facility Installed User Programcontains more details on
the use of the system status data set.
o
Chapter 3. Host Communications Facility
CO-131
Host Communications Facility
Planning to Use the Host Communications Facility (continued)
Host Storage
o
To ensure economical utilization of host processor storage, while also providing large record
capability, host processor storage is shared by all Series/I systems. The Host Communications
Facility IUP region allocation determines how much buffer space is available; therefore, it
determines the upper limit for the host BLKSIZE. Despite this determination of buffer size, it is
still possible for error code 222 (sufficient I/O buffer space unavailable) to occur because of
multiple and simultaneous requests for access to data sets with very large block sizes. Although
this is not likely to occur, you should minimize the amount of realtime control you require with
the Host Communications Facility in order to minimize the probability of interference.
You should also specifically test for error code 222 in response to a TP OPEN instruction and, if
it is received, retry your request later.
Data Transfer Rates
Data transfer rates between a Series/I and the host vary depending on the activity on the host
and the type of physical connection used between the systems. In general, you should avoid
implementing any functions in a manner which depends on specific data rates between the host
and Series/I.
Tasks Common to Programming and Using $HCFUT1
~..~
You can perform almost all tasks both by writing TP instruction programs and using the
$HCFUTI utility. These include transfer of data sets between the host and Series/ I, submitting
jobs to the host, and performing status functions.
Programming for the Host Communications Facility Application
Your application programs for the Host Communications Facility can control data transfers,
submit background jobs to the host, and perform status functions.
Event Driven language Instruction Set
You write HCF programs with a set of EDL instructions called TP instructions. The chart that
follows shows these instructions and the functions they perform. They are listed in alphabetical
order.
CO-132
SC34-0638
I\~L)
o
o
Programming for the Host Communications Facility Application (continued)
Instruction
TP CLOSE
Function
Ends a data transfer operation (any operation begun by a TP OPEN IN or TP
OPEN OUT intruction)
TP FETCH
Tests the existence of a record in the system status data set and/or reads it
TP OPEN IN
Prepares Series/1 to read data from the host
TP OPENOUT
Prepares the Series/1 to send data to the host
TP READ
Reads data sent from the host to Series /1
TP RELEASE
Deletes a record from system status data set and/or reads it
TPSET
Writes a record to the system status data set
TP SUBMIT
Submits a job stream from the Series/1 to host
TPTIMEDATE
Obtains time of day and date from the host
TPWRITE
Sends data to the host
Figure 58. EDL TP Instructions
For the syntax of the TP instructions, refer to the Language Reference.
Controlling Data Transfers between Series/1 and Host
You can send data to the host and receive data from the host through your program.
Chapter 3. Host Communications Facility
CO-133
Host Communications Facility
Programming for the Host Communications Facility Application (continued)
Sending Data to the Host
o
Series/l can write data to a host data set. Code this sequence of TP instructions to perform this
function:
1. TP OPENOUT (to specify an output operation)
2. TP WRITE (to send the data to the host system)
3. TP CLOSE (to end the output operation).
In the TP OPENOUT instruction, specify the name of the host data set where you are sending
the data. Follow naming conventions.
In the TP WRITE instruction, you must specify the label of the buffer that contains the data to
be sent. In the program, specify this buffer with a BUFFER statement that contains the
operand TPBSC.
You should also code error routines into the TP WRITE instruction to take over if an error or
end condition occurs.
Receiving Data from the Host
Series/l can ask the host to send it data. Code this sequence of TP instructions to perform this
function:
1. TP OPENIN (to specify an input operation)
2. TP READ (to receive the host data)
3. TP CLOSE (to end the receive operation).
In the TP OPENIN instruction, specify the name of the host data set that contains the data you
want to receive. Follow naming conventions.
In the TP READ instruction, specify the label of the buffer where the host data is to be stored.
In the program, specify this buffer with a BUFFER instruction that contains the operand
TPBSC.
You should also code error routines in TP READ to take over if an error or end condition
occurs.
o
CO-134
SC34-0638
o
Programming for the Host Communications Facility Application (continued)
Submitting Background Jobs to the Host
Your program can allow the Series/1 to submit a host data set to the host batch job stream. To
perform this function, code a TP SUBMIT instruction. The host data set can be either
sequential or a member of a partitioned data set. In the TP instruction, specify the label of the
TEXT instruction that contains the name of the host data set. In the program, code the TEXT
instruction with the naming conventions for host data sets. The Language Reference contains
the syntax and description of the TEXT instruction.
Performing Status Functions
Your program can perform the status functions associated with the system status data set that
resides on the host system.
Writing Data to the System Status Data Set
You can set the occurrence of an event on the Series/1 by writing a record to the system status
data set. To perform this function, code a TP SET instruction. In the TP SET instruction, refer
to the label of the STATUS instruction, which references a record in the system status data set.
In the program, code the STATUS instruction with its index entry and key fields, along with the
optional 256-byte data field. The Language Reference contains the syntax and description of the
ST ATUS instruction.
Retrieving a Record from the System Status Data Set
You can retrieve a specific record from the host data set and (optionally) read the record. To
perform this function, code a TP FETCH instruction. In the TP FETCH instruction, refer to
the label of the STATUS instruction that references the specific record of data in the system
status data set. If you intend to read the record, code the ~'length" operand of TP FETCH with
the number of bytes in the record to be read. If you do not want to read the record, you must
still code the "length" operand, but enter the value zero.
Deleting a Record in the System Status Data Set
You can delete a record from the system status data set after you (optionally) read it. To
perform this function, code a TP RELEASE instruction. This erases a Series/1 event that was
set by a TP SET instruction. In the TP RELEASE instruction, refer to the label of the STATUS
instruction which in turn refers to the specific record in the system status data set. If you intend
to read the record before deleting it, you must code the "length" operand in TP RELEASE,
specifying the record length. If you do not want to read it, you must still code the operand,
specifying the value zero. In the program, code the STATUS instruction with the required index
entry and key field.
o
Chapter 3. Host Communications Facility
CO-135
Host Communications Facility
Programming for the Host Communications Facility Application (continued)
Obtaining Time and Date from the Host
o
You can obtain the current time (hours, minutes, seconds) and date (day, month, year) from the
host system. To perform this function, code a TP TIMED ATE instruction. You must specify
the six-word data area where the time and date information is to be stored in the Series/I.
Sample Programs
The following sample programs show how to accomplish some of the HCF functions with the
TP instructions.
Status Functions Sample Program
This program performs the SET, FETCH, and RELEASE function. It communicates with the
system status data set on the host system.
PROGA
STATA
*
*
A1
*
*
*
A
ERRORA
PROGB
STATB
*
**
*
B
ERRORB
END
PROGRAM A
STATUS PROGID,KEYA
TP
PROGRAM A
DEFINE STATUS ID & KEY
SET,STATA
SEND MESSAGE TO PROGB
VIA HOST
TP
FETCH,STATA,ERRORA
CHECK IF PROGB RECEIVED
MESSAGE
FALL THRU IF KEY & ID STILL ON HOST
GOTO
A1
EQU
*
PROGSTOP
ENDPROG
END
PROGRAM B
STATUS PROGID,KEYA
TP
CONTINUE INTERROGATION
DELETE THE MESSAGE ON HOST
PROGRAM B
DEFINE SAME STATUS ID & KEY
FETCH, STATB , ERROR=ERRORB
FETCH MESSAGE
MESSAGE WAS FOUND AND IS DELETED, THUS SIGNALING PROGA
TP
RELEASE,STATB
GOTO
END
GOTO
B
PROGSTOP
ENDPROG
END
CONTINUE LOOKING FOR MESSAGE
Figure 59. System Status Data Set Sample Program
o
CO-136
SC34-0638
o
Programming for the Host Communications Facility Application (continued)
Sample Program to Send Data to the Host
This same program sends a 256-byte Series/ I data set to a data set on the host. It prompts the
user to specify the host data set to receive the data.
WRITASK
*
TPOPEN
o
PROGRAM
TPOPEN,DS=((SOURCE,??))
OPEN TP LINE
READTEXT DSNAME,'HOST DATASET: ',PROMPT=COND
TP
OPENOUT,DSNAME
IF
(WRITASK,EQ,-1),GOTO,DSREAD
OPEN OK?
MOVE
SWITCH, 3
.. TPOPEN ERROR
GOTO
ERRSW
*
READ A RECORD FROM DATA SET
DSREAD
READ DS1,BUFFER,ERROR=ERR2,END=TPCLOSE
*
WRITE A RECORD TO HOST
TPWRITE TP
WRITE, BUFFER, 256
IF
(WRITASK,EQ,-1),GOTO,DSREAD
.. OK?
ERR1
MOVE SWITCH, 1
.. WRITE ERROR
GOTO TPCLOSE
ERR2
MOVE SWITCH, 2
.. READ ERROR
*
CLOSE DATA SET AND PRINT MESSAGE AS APPROPRIATE
TPCLOSE TP
CLOSE
ERRSW
GOTO (RETO,RET1,RET2,RET3) ,SWITCH
RETO
PRINTEXT '*****READ/WRITE SUCCESSFUL*****@'
PROGSTOP
RET1
PRINTEXT '*****WRITE UNSUCCESSFUL*****@'
PROGSTOP
RET2
PRINTEXT '*****READ UNSUCCESSFUL*****@'
PROGSTOP
RET3
PRINTEXT '*****TP OPEN UNSUCCESSFUL*****@'
PROGSTOP
SWITCH
DATA F'O'
DSNAME
TEXT LENGTH=40
BUFFER
BUFFER 256, TPBSC ENDPROG
END
Figure 60. Sample Program to Send Data Set to the Host
o
Chapter 3. Host Communications Facility
CO-I37
Host Communications Facility
Programming for the Host Communications Facility Application (continued)
Sample Program to Receive a Host Data Set
o
In this example, the Series/l specifies that the host send it a data set. It reads the host data into
a pre-allocated data set on a Series/l volume. During program load, the user is prompted for
the Series/l data set where the host data will be placed.
READTASK PROGRAM TPOPEN,DS=((TARGET,??))
OPEN TP LINE
*
TPOPEN
READTEXT DSNAME,'HOST DATASET: ',PROMPT=COND
TP
OPENIN,DSNAME
IF
(READTASK,EQ,-1),GOTO,TPREAD
OPEN OK?
MOVE
SWITCH, 3
TP OPEN ERROR
GOTO
ERRSW
READ A RECORD FROM HOST
*
TPREAD
TP
READ,BUFFER
IF
(READTASK,EQ,-1) ,GOTO,DSWRITE
OK?
IF
(READTASK,EQ,300),GOTO,TPCLOSE
END?
GOTO ERR2
WRITE RECORD ON DISK
*
DSWRITE WRITE DS1,BUFFER,ERROR=ERR1
IF
(READTASK,EQ,-1) ,GOTO,TPREAD
OK?
ERR1
MOVE SWITCH, 1
WRITE ERROR
GOTO ERRSW
ERR2
MOVE SWITCH, 2
CLOSE TP LINE AND PRINT MESSAGE AS APPROPRIATE
*TPCLOSE TP
CLOSE
ERRSW
GOTO (RETO,RET1,RET2,RET3),SWITCH
RETO
PRINTEXT '*****READ/WRITE SUCCESSFUL*****@'
PROGSTOP
RET1
PRINTEXT '*****WRITE UNSUCCESSFUL*****@'
PROGSTOP
RET2
PRINTEXT '*****READ UNSUCCESSFUL*****@'
PROGSTOP
RET3
PRINTEXT '*****TP OPEN UNSUCCESSFUL*****@'
PROGSTOP
SWITCH
DATA F'O'
DSNAME
TEXT LENGTH=40
BUFFER
BUFFER 256,TPBSC
ENDPROG
END
l)
Figure 61. Sample Program to Receive a Host Data Set
o
CO-138
SC34-0638
o
Interacting with the Host Communication Facility ($HCFUT1)
The $HCFUTI utility allows the Host Communications Facility on the Series/Ito interact with
the Host Communications Facility Installed User Program on the System/370. $HCFUTI can
perform four functions:
•
Read a data set from the host
•
Write a data set to the host
•
Submit a job to the host
•
Perform status functions in the system status data set.
Figure 62 lists the $HCFUTI commands.
END
FE
REL
READ DATA
READ80
READOBJ
SE
SU
WR
o
-
END
FETCH STATUS
RELEASE STATUS
READ HOST
~READaOBYT~RECORl)$- STORE2/DISK
-READ80BYTE,R~CORPS,:-STORE3/DISK
~,.S~~'.STATl)S .
... 'SUBMIT A JOB
.., WRITE TO HOST
'.
RECORD
RECORD
. .
Figure 62. $HCFUTt Commands
Notes:
1. See "Host Data Set Naming ~onventions" on page CO-128 and"Host Data Set
Characteristics" on page CO-129.
2. See "System Status Data Set" on page CO-130. Appendix B of the Host Communications
Facility Installed User Program contains more details on its use.
3. The Host Communications Facility IUP, program number 5796-PGH, is required on the
host System/370.
4. Host Communications Facility must be installed and configured on the Series/I.
Many of the functions that $HCFUTI performs are the same as those you can program with the
TP instructions.
Transferring Host Data to Series/1
You can transfer data with two commands, depending on the type of data being sent.
o
Chapter 3. Host Communications Facility
CO-139
Host Communications Facility
Interacting with the Host Communication Facility ($HCFUT1) (continued)
Using READDATA Command
o
The READ DATA command transfers a data set from the host to the Series/I. The host logical
record size is assumed to be 256 bytes.
The utility prompts for the following information:
WORKFILE. This refers to the 1-8 character name of the Series/l data set where the host
data will be transferred, including the volume name.
Record Count. This refers to the number of records to be transferred, beginning with the
first. Use this if, for example, only the first 10 records of a 50-record data set are to be
transferred.
Enter zero to indicate that the entire data set is to be transferred.
•
DSNAME. This refers to the name of the host data set to be transferred .
The following is a terminal printout of a typical run. In this example, all records (length = 256
bytes each) of the host data set "Sl.EDX.TESTIN(DATA)" (which contains 40 records) are
transferred to the Series/l data set "DATAFIL2."
> $L $HCFUTl
LOADING $HCFUTl
8P,08.15.30, LP=4BOO
WORKFILE(NAME,VOLUME): DATAFIL2,EDXOOl
COMMAND (1): READDATA
NO. OF RECORDS TO READ (O=ALL):
DSNAME: Sl.EDX.TESTI~(DATA)
END AFTER 40 RECORDS
COMMAND
f-- '\
~ )
0
(1):
Using READ80 and READOBJ Commands
The READ80 and READOBJ commands transfer 80-byte records from a host data set and
store them in 256-byte Series/l disk or diskette data set records.
READ80 stores two 80-byte records per 256-byte disk record. the first 80-byte record is
stored in the first 80 bytes of the disk record. The second 80-byte record is stored starting at
byte 129 of the disk record. This format is compatible with the saved results of using $EDITIN
or $FSEDIT and is also the format required for input to a language compiler or $EDXASM
program preparation. READ80 is normally used to transfer source program modules from the
System/370 to Series/1 disk.
READOBJ stores three 80-byte records in the first 240 bytes of each disk record. This format
is compatible with object modules produced by any of the assembler programs. It is also the
format required for input to· $EDXLINK and is one of the formats accepted by $UPDATE.
o
CO-140
SC34-0638
o
Interacting with the Host Communication Facility ($HCFUT1) (continued)
READOBJ is normally used to transfer the output object module of a host assembly to the
Series/1 for processing by $EDXLINK or $UPDATE.
For both these commands, the utility prompts for the name of the Series/1 data set where the
data is to go, the number of host records to be transferred, and the name of the host data set
where the records come from.
Performing Status Functions
The status commands allow you to perform, from a terminal, the SET, FETCH, and RELEASE
functions on the system status data set. The functions are identical to those you can perform
with TP SET, TP FETCH and TP RELEASE.
For the SE and FE commands, the utility prompts for the index entry and key field. For the RE
command, it prompts for the index entry. After performing one of the status functions, the
utility sends a return code indicating the status of the data set.
Submitting Jobs to the Host Job Stream
c
The SU command allows you to submit a job to the host job stream. This function is identical to
the one that TP SUBMIT performs. The utility prompts you for the name of the host data set
you want to submit. Follow host data set naming conventions when you specify the name.
Sending Data to the Host
The WR command sends data from the Series/1 to the host. The host logical record size is
assumed to be 256 bytes.
The utility prompts you for the following information:
•
WORKFILE. This refers to the 1-8 character name of the Series/1 data set to be
transferred, and its volume name, if not the IPL volume.
•
Record Count. This refers to the number of records to be transferred, beginning with the
first. This would be used if, for example, only the first 10 records of a 50-record data set
are to be transferred.
A count of zero is used to indicate that the entire data set is to be transferred.
•
DSNAME. This refers to the name of the host data set to which the data is to be
transferred. The name consists of up to 44 characters, or 54 characters if a member of a
partitioned data set.
o
Chapter 3. Host Communications Facility
CO-141
Host Communications Facility
Interacting with the Host Communication Facility ($HCFUT1) (continued)
The following is a terminal printout of a typical run. In this example, 28 records of the Series/l
data set "DATAFILl" are transferred to the host data set "S1.EDX.TESTOUT(DATA)."
c
COMMAND' (1) :,WR
NO. OF RECORDS TO WRITE(O=ALL):
D?NM1E:,$ 1.EQX.JESTOUT{oAJA)
END ,AFTER'28 RECORDS
l \~
"
~-/
o
CO-142
SC34-0638
o
Part 2. Channel Attach
Part 2 discusses the Channel Attach Program, which allows Series/Ito communicate with large
host systems.
o
o
Part 2. Channel Attach
CO-143
Notes
o
o
CO-144
SC34-0638
o
Chapter 4. Channel Attach Program
o
The channel attach program allows the Series/1 to communicate with a larger host processor.
This discussion refers to the System/370 as the host processor. However, the host can be any
processor that uses the Basic Telecommunications Access Method (BT AM) form of data
communications.
Series/lis physically connected to the host by a channel attach device.
You must write the application programs that communicate with the System/370 host. The
program must contain special Event Driven Language instructions, called CA instructions, used
for the channel attach application. In addition, you can communicate with the host by using the
$CHANUTI utility.
Planning for the Channel Attach Application
Before you begin to write your application program to communicate with the host system, you
should be familiar with the way channel attach works and what requirements and restrictions
apply to its use.
Channel Attach Program ($CAPGM)
The channel attach program, as it executes on the Series/I, transfers data from the Series/l
application program to the channel attach device. At the same time, an application program on
the System/370 is executing to transfer data between the channel attach device and the
System/370.
Chapter 4. Channel Attach Program
CO-14S
Channel Attach Program
Planning for the Channel Attach Application (continued)
$CAPGM allows you to perform the following functions through your application program
running on the Series/1:
•
o
Establishing, controlling, and terminating access between Series/1 and System/370
Transferring data between Series/1 and System/370
•
Communicating with System/370 application programs by 32 data ports (System/370
device addresses)
Handling interrupts from the channel attach device
•
Managing data ports to avoid conflict or contention
Performing error recovery and retry
•
Performing error logging
Tracing Series/1 I/O commands and attention interrupts from the channel attach device.
Channel Attach Device (4993)
The channel attach device provides an interface between a Series/1 and a System/370. It
responds to commands from the System/370 and directs the information to the Series/I.
Likewise, the device responds to commands from the Series/1 and directs the information to the
host.
(f-)\
~
The connection between the channel attach device and the 370 consists of 32 device address
(data port) connections. The channel attach device allows activity over only one port at a time.
Software Considerations
During system generation for the Series/I, you must define each channel attach device as an
EXIO device. The instructions for this procedure are described in the Installation and System
Generation Guide.
Hardware Considerations
You should consider the following when installing your channel attach device:
By installing the channel attach device in the I/O expansion unit rather than the processor,
you will be able to turn off the processor power temporarily without having to turn off the
channel attach device first. If the channel attach device is in the processor, you must follow
the power-off sequence described in "Powering On The Channel Attach Device" on page
CO-148 to power off.
o
CO-146
SC34-0638
o
Planning for the Channel Attach Application (continued)
•
When you install your channel attach device, it must be jumpered correctly to specify the
lowest System/370 device address you will be using. For example, if your channel attach
device is connected to the host on channel 5, subchannel8 (with 32 device addresses X'580'
to X'59F'), then the setting of the jumpers on the channel attach feature card should be for
X'80'. You must be able to provide this information to the person who installs your channel
attach device.
•
On the System/370, your channel attach device must be defined to use a shared unit control
word (DCW). Failure to specify a shared UCW can cause unpredictable results when you
are using more than one port.
Tailoring the Channel Attach Program
During system generation for the Series/ l, you can tailor the channel attach program to fit your
specific needs by editing the program's control module, $CACBS. The section of $CACBS that
you should edit consists of channel attach control block statements, CACBl and CACB2. Two
channel attach control block statements are required for each channel attach feature installed
(physically and logically) on the Series/l processor. CACBl and CACB2 are configuration
statements that create control blocks. These statements describe to the channel attach program
the characteristics of a particular channel attach device. The CACBl and CACB2 statements
for a device must be contiguous and both must specify the same device address, trace size, and
number of ports. In these statements, you can specify the following information:
o
•
device address of the channel attach device
•
amount of storage for the channel attach trace area
•
number of host ports with which the device will connect
•
number of retries during errors.
After you modify the CACBl and CACB2 statements, assemble the $CACBS module and use
$EDXLINK or $LINK/$UPDATE to link edit it to the channel attach support modules. If you
followed the standard installation procedures, the link-edit control statements to do this are in
data set $CALNK on EDX002.
$CALNK provides full support for a channel attach system, including trace, log, and OLTEP
support. You should use the full support system for initial debugging efforts.
To modify the provided support, you may want to include XCAXDIAG instead of $CAXDIAG
to eliminate OLTEP support; XCAXLOG instead of $CAXLOG to eliminate error logging;
XCAXTRCE instead of $CAXTRCE to eliminate tracing; and XCAXERR instead of
$CAXERR to eliminate the task error exit facility.
Chapter 4. Channel Attach Program
CO-l47
Channel Attach Program
Planning for the Channel Attach Application (continued)
~\
()
Powering On The Channel Attach Device
Before any communication can occur, you must power on the channel attach device at the
Series/I. Use the following procedure:
1. Turn off the channel attach device, and ensure that it is offline. Set the Enable/Disable
switch on the 4993 Termination Enclosure to the Disable position and the On/Off switch to
the Off position.
2. Turn on the other devices. Set the On/Off switch for each Series/l unit (except for the
4993 Termination Enclosure and the Series/l processor) to the On position.
3. Turn on the processor by setting the On/Off switch on the Series/l processor to the On
position.
4. Turn on the Termination Enclosure unit by setting the On/Off switch on the 4993
Termination Enclosure to the On position and making sure that the Power On indicator is
on.
5. After you complete the above steps, place the channel attach device online to the
System/370 by setting the Enable/Disable switch on the 4993 Termination Enclosure to
the Enable position. Make sure that the Disable indicator is off (indicating that the unit is
online), and notify the System/370 operator that the channel attach device is online. If you
attempt to vary a System/370 device address online when the channel attach device is not
powered on and enabled, the System/370 receives a NO PHYSICAL PATH message.
(1-_--)'\
"'--
To power off the channel attach device, use the reverse sequence of the power on instructions.
You must disable the channel attach device, turn off the device, and turn off the I/O expansion
unit and the other devices. Never turn the channel attach device off when the device is enabled.
Programming for the Channel Attach Application
This section tells how to write programs that communicate between the Series/land the host by
means of the channel attach.
Event Driven Executive Instruction Set
Your program must contain these channel attach instructions. They provide you with the
interface to the System/370 channel attach program. They are:
•
•
•
•
•
CACLOSE - Close a channel attach port
CAIOCB - Create a channel attach port I/O control block
CAOPEN - Open a channel attach port
CAPRINT - Print channel attach trace data
CAREAD - Read from a channel attach port
o
CO-148
SC34-0638
o
Programming for the Channel Attach Application (continued)
•
•
CASTART - Start channel attach device
CASTOP - Stop a channel attach device
CATRACE - Control channel attach trace
CAWRITE - Write to a channel attach port.
For the syntax of each instruction, refer to the Language Reference.
Detecting and Handling Errors
Each instruction sets the task code word to indicate success or failure of the operation it
performs. You should use the ERROR operand of the instruction or check the task code word
after each instruction.
To ensure that the instructions are successful, your program should wait on an event control
block (ECB) for completion of the I/O associated with the instruction. CATRACE has no I/O
associated with it so no wait is required. CASTOP, CASTART, and CAPRINT use the ECB
supplied with the instruction. CAOPEN, CAREAD, CAWRITE, and CACLOSE use the first
three words of the CAIOCB as the ECB to wait on. After you do a WAIT on the ECB, check
the completion code for I/O errors. Do not issue a WAIT if the return code in the task code
word indicates an unsuccessful operation. The second word of the TCB contains the address of
the instruction that received the error.
c
BT AM Considerations
The Basic Telecommunications Access Method (BTAM) interfaces with the System/370
channel attach; you should consider the following:
•
BT AM issues an ERASE/WRITE of 1 byte (X'C3 ') or (X'7B') when you open or close a
channel attach port. Respond with a read o( this ERASE/WRITE when opening a port.
When closing a port, you can either read the (X'C3 ') or ignore it. If you ignore the (X'C3 ')
then you may get a return code from the close operation to show data pending from the
host.
•
If BTAM requests an I/O operation to the device and the device is in a "not ready"
condition (the System/370 device address has not been enabled by Series/l), BTAM posts
an intervention required (X' 41 ').
•
On an asynchronous device end from the Series/1 (caused by a Series/1 ENABLE
System/370 DEVICE ADDRESS), the System/370 application may elect to be notified by
BTAM (OS/VS only). This is done by specifying the READYQ option on the DCB macro,
which causes the user to be posted when a device end occurs for the specified device
address. The device end is ignored if the READYQ option is not selected or if using
DOS/VS BTAM.
•
BTAM issues retries for read errors and all busy conditions.
0 ,\
.1,
Chapter 4, Channel Attach Program
CO-149
Channel Attach Program
Programming for the Channel Attach Application (continued)
You must not issue any BTAM macro which might cause BTAM to generate a channel
program that contains both read and write channel command words (CCWs), such as Read
Modify Position or Read Buffer Position. Extraneous I/O operations that result from
chained read and write CCWs can invalidate protocol understanding at the Series/I.
o
Do not issue a command that requires an attention interrupt to begin on the System/370 as
the first command after OPEN. If you do, you must have some method of ensuring that the
System/370 opening process is done before you issue the (Series/I) attention interrupt.
•
The first three bytes of data sent by a Series/l write request can have explicit meaning to
the System/370 support program. Therefore, be careful when setting the first three bytes
of data, because unpredictable results can occur. To avoid problems, set the first three
bytes of the data to X'7D4040'. This corresponds to an attention identification descriptor
(AID) and two bytes of null buffer address. The X'7D' corresponds to an Enter key
response from an IBM 3272 Control Unit.
Assembling the Application Program
If you are going to assemble your program with either the host or native macro assemblers, you
don't have any special steps to perform. If you are using $EDXASM to assemble, you must
code the following statements in your program for proper assembly.
COPY CMDEQU
COpy PROGEQU
These statements generate several pages of equates. To suppress printing these equates, code
the following statements:
PRINT
COpy
COpy
PRINT
OFF
CMDEQU
PROGEQU
ON
Link-Editing the Application Program
After assembling your program, you must use $EDXLINK or $LINK/$UPDATE to link-edit it.
If your channel attach support has been installed as shown in the Program Directory, the link
editing control statements required to link your application program are in the data set
USERPGM on EDX002. A listing of the data set USERPGM follows.
()
CO-ISO
SC34-0638
o
Programming for the Channel Attach Application (continued)
LIST OF DATA SET USERPGM ON EDX002
*
*
EVENT DRIVEN EXECUTIVE
SYSTEM/370 CHANNEL ATTACH VER. 1
***************************************************************
* COMMENTS MAY BE INCLUDED BY AN '*' IN COLUMN 1
*
*
* USE THIS TECHNIQUE TO OMIT UNNEEDED SUPPORT
***************************************************************
OUTPUT
<---- YOUR OUTPUT MODULE NAME AND VOLUME IT RESIDES
ON, GOES HERE
* INCLUDE <---INCLUDE
*INCLUDE
INCLUDE
INCLUDE
INCLUDE
* INCLUDE
INCLUDE
INCLUDE
INCLUDE
c
INCLUDE
INCLUDE
INCLUDE
END
YOUR INPUT MODULE NAME AND VOLUME IT RESIDES
ON, GOES HERE
$CAPRCES,EDX002
*MAKE A COMMENT AND INCLUDE
XCAPRCES,EDX002
*THIS IF TRACE PRINT OMITTED
$CABEGIN,EDX002
$CAPARM,EDX002
*MAKE A COMMENT AND INCLUDE
$CALOGCO,EDX002
XCALOGCO,EDX002
*THIS IF INPUT ERR. OK OMITTED
$CALOGIC,EDX002
$CAFILL,EDX002
$CAPRNT,EDX002
*MAKE THIS A COMMENT IF TRACE
*PRINTING OMITTED
$$SVC,ASMLIB
$$RETURN,ASMLIB
$EDXATSR,ASMLIB
LIST COMPLETE
Figure 63. Listing of USERPGM Data Set
The name of your output module and input module refer to your object output and input data
sets respectively.
This link editing control data set provides you with the full support link modules. You should
use the full support system during initial debugging activities.
Starting a Channel Attach Device
Code a CASTART instruction to load the channel attach device support program and prepare
the channel attach device to accept interrupts from the host. You must start the channel attach
device before you can open any of its ports and before you can issue any I/O instructions.
After your program issues a CASTART instruction, check the return code in the first word of
the task control block (TCB). If the return code indicates a successful request, issue a WAIT
for the I/O to complete. Use the event control block (ECB) operand of the CASTART
instruction to wait on I/O completion. If the return code indicates that the device was already
started or an error occurred, do not issue aWAIT instruction.
Chapter 4. Channel Attach Program
CO-lSI
Channel Attach Program
Programming for the Channel Attach Application (continued)
Opening a Channel Attach Port
o
Code a CAOPEN instruction to open a specific port on the channel attach device. This logically
assigns the port to your application program, and enables it to accept interrupts from the host.
You must open a port before using it for data transfer.
You must code a control block instruction (CAIOCB) for each port you open in your program.
The CAIOCB stores the device address, port number, control block addresses associated with
the port, and the ECB used to wait for I/O completion on the port. Its use it discussed in the
next section.
Coding the Control Block for a Channel Attach Port
The CAIOCB statement creates a channel attach port I/O control block which contains the
information required to access a port. It is a nonexecutable instruction which allocates storage.
You supply the device address, port number, and the address of the first buffer control area.
Other information in the System/370 channel attach I/O control block is supplied by the
System/370 channel attach link module when the device is opened. In every other CA
instruction you code to perform operations on a port, you must refer to the label of the
CAIOCB for that port, which you code in the nonexecutable section of your program.
As for all EDX channel attach instructions, check the return code in the TCB before issuing a
WAIT.
Issuing I/O
Your application program requests I/O processing by issuing CAREAD and CAWRITE
instructions.
For both CAREAD and CAWRITE, check the return code in the TCB before issuing a WAIT
instruction for the I/O to complete.
Series/1 Receiving Data from the Host (CAREAD)
The CAREAD instruction reads data from a host device address. Specify the CAIOCB
statement that refers to the port in the CARE AD instruction. Each CAREAD instruction must
supply the addresses of two buffer control blocks.
When you issue a Series/1 read request, one of two conditions are true: either the System/370
has aiready issued the write to match your CAREAD, or your CAREAD was issued before the
matching write request was received. If the System/370 has already issued its write request,
your CAREAD is posted immediately and the address of the buffer that the System/370 wrote
to is returned to you. If the System/370 has not issued a write to match your CAREAD, the
channel attach program holds your CAREAD until the System/370 issues its write request.
Because the System/370 can issue a write request at any time, a buffer must be available to
receive data from the System/370. This is accomplished as follows:
o
CO-1S2
SC34-0638
o
Programming for the Channel Attach Application (continued)
When you open a channel attach port, you must point to a buffer control block defining the
address, size, and partition of the buffer to receive data for the first System/370 write. This
information is stored by the channel attach program and is returned to you when your first
CAREAD is complete.
When you issue a CAREAD instruction it must identify two buffer control blocks:
The first buffer control block receives (from the channel attach program the address,
size, and partition of the data buffer written by the System/370 to satisfy that
CAREAD.
The second buffer control block must contain three words defining the address, size and
partition of the buffer to be used for the next System/370 write. These values are
stored by the channel attach program, and are returned to you when the next Series/I
CAREAD is complete.
On every Series/I CAREAD instruction, you are told where the data for the read was stored,
and you supply the information required to set up for the next System/370 write operation.
Series/1 Sending Data to the Host
o
The CAWRITE instruction sends data from your application program buffer to a channel attach
device port. On the CAWRITE instruction, you must specify the CAIOCB used to open the
port.
When a Series/I CAWRITE is issued to a port and the System/370 application program is not
actively reading from the corresponding device address, the channel attach program issues an
attention interrupt to the System/370. This attention interrupt notifies the System/370
application program that the data from the Series/I is available for the associated device
address.
The System/370 should then select the port and issue a READ. The channel attach program
recognizes the READ command and issues a start I/O (write) command to the channel attach
device to start transfer of the contents of the Series/I data buffer to the System/370.
When data transfer is complete, the write operation is not posted until the System/370
application program acknowledges the data transfer or indicates negative acknowledgement.
This acknowledgement can be in one of two forms. If the System/370 program issues an Erase
All Unprotected (EAU) command after data has been sent to the host, then the EAU is
considered to be a positive acknowledgement of the data transfer. The CAWRITE which
caused the data to be sent to the host is then posted.
A second way the System/370 acknowledges a CAWRITE is by issuing a write command.
When a System/370 Write or Erase/Write is received as an acknowledgement of a CAWRITE,
bit 6 of the first data byte from the System/370 is examined to determine whether it is a positive
acknowledgement (bit 6 on) or a negative acknowledgement (bit 6 off), and the Series/I
program is posted appropriately.
o
Chapter 4. Channel Attach Program
CO-IS 3
Channel Attach Program
Programming for the Channel Attach Application (continued)
~
. c>J
(
If the System/370 issues additional read requests before it acknowledges the Series/1
CAWRITE, the read requests connect to the same CAWRITE, causing retransmission of the
data.
If the System/370 tries to read when no corresponding Series/1 CAWRITE has been issued,
the channel attach program generates a write operation and sends X'604040' to the host; this
indicates that a CAWRITE is not pending on the Series/1. If the channel attach program has
sent X'604040' to the host one or more times before the Series/1 user issues a CAWRITE, then
when the CAWRITE is issued the channel attach program sets the appropriate flags to allow the
next System/370 read to the Series/1 user data buffer. No attention interrupt is issued to the
System/370 in this case.
The first three, bytes of data sent by a Series/1 CAWRITE can have explicit meaning to the
System/370 support program. Therefore, be careful when setting the first three bytes of data,
because unpredictable results can occur. To avoid problems, set the first three bytes of the data
to X'7D4040'. This corresponds to an attention identification descriptor (AID) and two bytes
of null buffer address. The X'7D' corresponds to an Enter key response from an IBM 3272
Control Unit.
Closing a Channel Attach Port (CACLOSE)
When your program no longer requires a port it should issue a CACLOSE instruction to free the
port. A CACLOSE for a port causes the channel attach program to:
•
Reinitialize the control blocks for the port so the port can be opened by another application
program.
o
Disable the port except for port 0 which is kept open for potential use by the Online Test
Executive Program (OLTEP).
Stopping the Channel Attach Device (CASTOP)
The CASTOP instruction frees the channel attach device. A CASTOP causes the channel attach
program to:
•
Disable port 0
Disable the channel attach device for interrupts
Reinitialize the control block for the channel attach device so it can be started by another
application program
•
Unload the channel attach program (only if all channel attach devices are stopped).
o
CO-1S4
SC34-0638
o
Programming for the Channel Attach Application (continued)
Traci~g
Series/1 I/O during Channel Attach (CATRACE)
The CATRACE instruction enable or disables the collection of I/O trace data for a channel
attach device. Channel attach trace data is collected in processor storage and, for performance
reasons, should only be used during debugging.
Printing Channel Attach Trace Data (CAPRINT)
To print the entire area of trace data obtained through CATRACE, code a CAPRINT
instruction. The data prints out on a printer or displays at your terminal. Tracing is disabled
while printing is in progress.
Interacting with Channel Attach (Using $CHANUT1 Utility)
The channel attach utility, $CHANUTI, allows you to perform several functions associated with
channel attach operations:
•
o
start or stop channel attach device
enable or disable I/O tracing
•
print trace data.
Invoke $CHANUTI by the $L command or by the session manager. You can load the utility
into any partition. As soon as it is loaded, the utility asks for the address of the channel attach
device you want to work with. All commands you enter during a session with $CHANUTI will
apply to the first device you specify, unless you change the address (this procedure is discussed
below). The $CHANUTI commands interface with the channel attach program in the same
manner as the channel attach instructions. The error codes for the $CHANUTI commands are
the same as those for the corresponding instructions.
$CHANUT1 Commands
The $CHANUTI commands are shown below. To obtain this list at your terminal, enter a
question mark in response to the prompting message, COMMAND(?):
o
Chapter 4. Channel Attach Program
CO-IS S
Channel Attach Program
o
Interacting with Channel Attach (Using $CHANUT1 Utility) (continued)
Changing Channel Attach Device Address (CA)
The CA command changes the address of the channel attach device you want to use during the
$CHANUTI session.
Ending the Utility (EN)
The EN command ends the $CHANUTI utility.
lCOMMANO(?):
EN
j
Printing the Trace Data (PR)
The PR command prints the trace buffer, with the title you enter, on a terminal.
COMMAND(?): PR
TITLE: TRACE PRINTOUT 07/26/80
CONSOLE: $SYSPRTR
PRINT TRACE BUFFER SUCCESSFUL
COMMAND(?) :
Stopping a Channel Attach Device (SP)
The SP command stops the channel attach device you have specified.
I·
COMMAND(?):
SP
l" " - - - - - - - - - - .STO. P DEVICE SUCCESSFUL
COMMAND(?):
)
I
Starting a Channel Attach Device (ST)
The ST command starts the channel attach device you have selected.
COMMAND (?): ST
START DEVICE SUCCESSFUL
COMMAND ( ?):
Performing Trace Function (TR)
The TR command allows you to enable (E) or disable (D) the trace function.
COMMAND (? ): TR
ENABLE OR DISABLE: 0
ENABLE/DISABlESUCCESSFUL
COMMAND(?) :
o
CO-lS6
SC34-0638
o
Channel Attach Sample Programs
This section contains two sample programs. The first, executes on a Series/1 using the EDX
channel attach support. It communicates with an OS/VS2 application program which is
executing at the same time on the host System/370.
The second sample program executes on a System/370 using BTAM or BTAM-ES facilities. It
communicates with the first sample program, which is running on the Series/1.
Configuration Requirements for Sample Programs
Hardware
System/370
Block multiplexer or selector channel
One control unit position on channel
Other peripherals to support OS/VS2.
Series/1
IBM Series/l hardware required to operate EDX
IBM 4993-1 Series/1-System/370 termination enclosure
IBM Series/l-System/370 Channel Attachment Feature #1200.
•
Software
System/370 software:
OS/VS2 (MVS)
Basic Telecommunications Access Method (BTAM)
Channel attach device defined to OS /VS2 via I/O generation
User application program.
Series/l software:
EDX operating system (any version)
EDX Channel Attach Program
User application program.
o
Chapter 4. Channel Attach Program
CO-lS7
Channel Attach Program
Channel Attach Sample Programs (continued)
General Guide for Execution of Sample Programs
o
• . Install channel attach support.
•
Modify the sample program if your channel attach device is not at address 10. Assemble,
link, and update Series/l program.
•
Assemble host program and link-edit for S/370 execution.
•
Power on the channel attach device and set the enable/disable switch to enable.
•
Start sample program on the Series/I.
When prompted, start the sample program on the System/370.
Series/1 Sample Program
The Series/l sample program (SAMPLEA) performs the following functions:
•
Starts the channel attach device (the CASTART instruction)
•
Enables and disables I/O tracing (the CATRACE instruction)
•
Opens channel attach device port #1 (the CAOPEN instruction)
•
Reads from the System/370 over port #1 (the CAREAD instruction)
•
Writes to the System/370 over port #1 (the CAWRITE instruction)
Closes channel attach device port #1 (the CLOSE instruction)
•
Prints the I/O trace area (the CAPRINT instruction)
•
Stops the channel attach device (the CASTOP instruction).
o
CO-lS8
SC34-0638
o
Channel Attach Sample Programs (continued)
SAMPLEA
BEGIN
PROGRAM BEGIN
PRINT OFF
COpy PROGEQU
===> REMOVE FOR MACRO ASSEMBLER
COPY CMDEQU
===> REMOVE FOR MACRO ASSEMBLER
PRINT ON
PRINTEXT '@THIS IS A TEST OF THE CHANNEL ATTACH SUPPORT.'
PRINTEXT '@THE CHANNEL ATTACH DEVICE MUST BE ON AND'
PRINTEXT '@ENABLED BEFORE YOU PRESS ENTER TO CONTINUE.'
READTEXT SYNC
********************************************************************
*
*
START CHANNEL ATTACH DEVICE 10
********************************************************************
CASTART 10,STREVNT,ERROR=STRTERR
WAIT STREVNT
IF
(STREVNT,NE,+MINUS1)
GOTO STRTERR
ENDIF
PRINTEXT '@DEVICE 10 STARTED'
********************************************************************
*
*
TURN ON I/O TRACING
********************************************************************
CATRACE 10,ENABLE=YES,ERROR=TRCERR
PRINTEXT '@TRACE ENABLED'
********************************************************************
*
o
OPEN PORT ONE
*
********************************************************************
CAOPEN PORTONE,ERROR=OPNERR
WAIT PORTONE
IF
(PORTONE,NE,+MINUS1)
GOTO OPNERR
ENDIF
PRINTEXT '@PORT ONE OPENED'
PRINTEXT '@PLEASE START SAMPLEC ON THE SYSTEM/370.'
PRINTEXT '@PRESS ENTER WHEN RDACK APPEARS ON THE'
PRINTEXT '@S/370 DISPLAY, INDICATING THAT THE S/370'
PRINTEXT '@HAS COMPLETED OPEN PROCESSING.'
READTEXT SYNC
Figure 64 (Part 1 of 6). Series/l Sample Program
o
Chapter 4. Channel Attach Program
CO-lS9
Channel Attach Program
Channel Attach Sample Programs (continued)
o
********************************************************************
* READ C3 WRITTEN BY SYSTEM/370 DURING OPEN PROCESSING
*
********************************************************************
CAREAD PORTONE,WHATREAD,INAREA,ERROR=C3ERR
WAIT PORTONE
IF
(PORTONE,NE,+MINUS1)
GOTO C3ERR
ENDIF
PRINTEXT '@READ OF C3 SUCCESSFUL'
********************************************************************
* WRITE MESSAGE TO SYSTEM/370 TO ACKNOWLEDGE RECEIPT OF C3
*
********************************************************************
CAWRITE PORTONE,OUTACK,ERROR=ACKERR
WAIT PORTONE
IF
(PORTONE,NE,+MINUS1)
GOTO ACKERR
ENDIF
PRINTEXT '@ACK OF C3 WRITTEN TO SYSTEM/370'
********************************************************************
* I/O LOOP
*
********************************************************************
DO
WHILE, (COUNT,LT,+LIMIT)
ADD
COUNT, 1
********************************************************************
* WRITE MESSAGE TO SYSTEM/370
*
********************************************************************
CAWRITE PORTONE,OUTAREA,ERROR=WRITERR
WAIT PORTONE
IF
(PORTONE,NE,+MINUS1)
GOTO WRITERR
ENDIF
PRINTEXT '@DATA WRITTEN TO SYSTEM/370'
Figure 64 (Part 2 of 6). Series/l Sample Program
o
CO-160
SC34-0638
o
Channel Attach Sample Programs (continued)
********************************************************************
*
*
READ MESSAGE FROM SYSTEM/370
********************************************************************
CAREAD PORTONE,WHATREAD,INAREA,ERROR=READERR
WAIT PORTONE
IF
(PORTONE,NE,+MINUS1)
GOTO READERR
ENDIF
PRINTEXT '@DATA READ FROM SYSTEM/370'
********************************************************************
*
*
WRITE ACK TO SYSTEM/370
********************************************************************
CAWRITE PORTONE,OUTACK,ERROR=RDACKERR
WAIT PORTONE
IF
(PORTONE,NE,+MINUS1)
GO TO RDACKERR
ENDIF
PRINTEXT '@ACK WRITTEN TO SYSTEM/370'
ENDDO
********************************************************************
*
*
CLOSE PORT ONE
********************************************************************
EXIT
CACLOSE PORTONE,ERROR=CLOSERR
WAIT PORTONE
IF
(PORTONE,NE,+MINUS1)
GOTO CLOSERR
ENDIF
PRINT EXT '@PORT ONE CLOSED'
Figure 64 (Part 3 of 6). Series/l Sample Program
o
Chapter 4. Channel Attach Program
CO-161
Channel Attach Program
Channel Attach Sample Programs (continued)
o
********************************************************************
* TURN OFF TRACE
*
********************************************************************
TRCDIS
CATRACE 10,ENABLE=NO,ERROR=TDISERR
PRINTEXT '@TRACE DISABLED'
********************************************************************
* PRINT THE TRACE AREA ON THE SYSTEM PRINTER
*
********************************************************************
PRNTRCE CAPRINT 10,STREVNT,TITLE=TITLDATA,ERROR=PRNTERR
WAIT STREVNT
IF
(STREVNT,NE,+MINUS1)
GOTO PRNTERR
ENDIF
PRINTEXT '@TRACE AREA PRINTED'
********************************************************************
* STOP THE CHANNEL ATTACH DEVICE
*
********************************************************************
STOPDEV CASTOP 10,STREVNT,ERROR=STOPERR
WAIT STREVNT
IF
(STREVNT,NE,+MINUS1),AND, (STREVNT,NE,+ENDED)
GOTO STOPERR
ENDIF
PRINTEXT '@DEVICE 10 STOPPED'
PROGSTOP -1
Figure 64 (Part 4 of 6). Series/1 Sample Program
:1
\
i,'L)
o
CO-162
SC34-0638
o
Channel Attach Sample Programs (continued)
********************************************************************
*
*
DATA AREAS AND I/O BUFFERS
********************************************************************
PORTONE
STREVNT
C3AREA
o
CAIOCB 10,PORT=1,BUFFER=C3AREA
CAIOCB FOR PORT ONE
ECB
0
EVENT FOR START, STOP, PRINT
DATA A(INBUFF)
BUFFER CONTROL AREA FOR
DATA F'1'
* READ OF C3
DATA F'O'
* FROM S/370 OPEN
INAREA
DATA A(INBUFF)
BUFFER CONTROL AREA FOR
DATA F'128'
* DATA INPUT
DATA F'O'
* FROM S/370 WRITE
OUTAREA DATA A (OUTBUFF)
BUFFER CONTROL AREA FOR
DATA F'128'
* WRITE OF DATA
* TO SYSTEM/370
DATA F'O'
OUTACK
DATA A (OUTBUFF)
BUFFER CONTROL AREA FOR
DATA F'4'
* WRITE OF ACK
DATA F'O'
* TO SYSTEM/370
WHAT READ DATA 3F'0'
RECEIVE CONTROL INFO FOR READ
INBUFF
DATA 128C'0'
OUTBUFF DATA X'7D4040AA'
DATA C'BB CC DD EE FF GG HH'
DATA C'11 22 33 44 55 66 77'
DATA C'ZZZZZYYYYYXXXXXWWWWW'
DATA C'THIS IS TO BE WRITTE'
DATA C'N TO THE SYSTEM/370.'
DATA C' THE END'
COUNT
DATA F'O'
LIMIT
EQU
2
MINUS1
EQU
-1
SYNC
TEXT LENGTH=4
TITLDATA DATA A (MYTITLE)
DATA F'25'
MYTITLE DATA C'SAMPLE PROGRAM TRACE AREA'
ENDED
EQU
599
Figure 64 (Part 5 of 6). Series/l Sample Program
o
Chapter 4. Channel Attach Program
CO-163
Channel Attach Program
Channel Attach Sample Programs (continued)
()
********************************************************************
*
ERROR MESSAGES
*
********************************************************************
STRTERR
PRINTEXT '@ERROR DURING START PROCESSING'
GOTO EXIT
OPNERR
PRINTEXT '@ERROR DURING OPEN PROCESSING'
GOTO EXIT
C3ERR
PRINTEXT '@ERROR DURING C3 PROCESSING'
GOTO EXIT
ACKERR
PRINTEXT '@ERROR DURING C3/ACK PROCESSING'
GOTO EXIT
WRITERR PRINTEXT '@ERROR DURING S/1 WRITE PROCESSING'
GOTO EXIT
READERR PRINTEXT '@ERROR DURING S/1 READ PROCESSING'
GOTO EXIT
RDACKERR PRINTEXT 'ERROR DURING READ/ACK PROCESSING'
GOTO EXIT
TRCERR
PRINTEXT '@ERROR DURING TRACE ENABLE'
GOTO EXIT
TDISERR PRINTEXT '@ERROR DURING TRACE DISABLE'
GOTO PRNTRCE
PRNTERR PRINTEXT '@ERROR DURING PRINT OF TRACE AREA'
GOTO STOPDEV
CLOSERR PRINTEXT '@ERROR DURING CLOSE PROCESSING'
GOTO TRCDIS
STOPERR PRINTEXT '@ERROR DURING STOP PROCESSING'
PROGSTOP -1
ENDPROG
END
Figure 64 (Part 6 of 6). Series/l Sample Program
CO-164
SC34-0638
o
Channel Attach Sample Programs (continued)
Host Sample Program
This program executes on a System/370 using OS/VS Basic Telecommunications Access
Method (BTAM) facilities, to communicate the application program executing at the same time
on the Series/I. Refer to the previous program, which is the companion to this host program.
*********************************************************************
*
INVOKE SAMPLEC VIA TSO COMMANDS OR JCL.
*
EXAMPLE: INVOKE SAMPLEC VIA TSO COMMANDS:
*
*
*
*
FREE FI(PRINTER,SNAP,S1GROUP)
*
ALLOC FI(SYSABEND) DA(DUMP.LIST) NEW SPACE(5,1) CYLINDERS +
*
*
CATALOG
*
ALLOC FI(SNAP) DA(SNAP.LIST) NEW SPACE(5,1) CYLINDERS CATALOG
*
*
ALLOC FI(S1GROUP) UNIT(581) NEW
*
*
ALLOC FI(PRINTER) DA(*)
*
*
*
CALL 'PROJECT.LIB.LOAD(SAMPLEC)'
*
*
*
FREE FI(PRINTER,SNAP,S1GROUP)
*
EXAMPLE: INVOKE SAMPLEC VIA OS/vs JCL:
*
* II
JOB (ACCOUNTING INFO),'NAME',
*
* IISAMPLEC EXEC PGM=SAMPLEC
*
*
* IISTEPLIB DD DISP=SHR,DSN=PROJECT.LIB.LOAD
* IIS1GROUP DD UNIT=581,DISP=NEW
*
*
* IIPRINTER DD SYSOUT=A
* IISNAP
DD SYSOUT=A
*
* IISYSIN DD *
*
*
1*
*
*********************************************************************
*
EQUATES
*
*********************************************************************
RO
o
EQU
TEMPORARY STORAGE
R1
1
TEMPORARY STORAGE
EQU
RLN
EQU
1
RELATIVE LINE NUMBER
R2
2
EQU
MESSAGE ADDRESS
R3
3
LOOP COUNTER
EQU
R4
4
BAL
EQU
R5
5
BAL
EQU
DCBREG
6
DCB USING REGISTER
EQU
DECBREG EQU
DECB USING REGISTER
7
R8
BAL
8
EQU
R9
NOT USED
EQU
9
R10
10
NOT USED
EQU
BASEREG EQU
11
BASE USING REGISTER
R12
12
NOT USED
EQU
SAVEREG EQU
13
SAVE AREA ADDRESS REGISTER
R14
14
LINKAGE
EQU
R15
15
LINKAGE
EQU
Figure 65 (Part 1 of 8). Host Sample Program
o
Chapter 4. Channel Attach Program
CO-165
Channel Attach Program
Channel Attach Sample Programs (continued)
o
*********************************************************************
* START SAMPLEC
*
*********************************************************************
SAMPLEC CSECT
SAMPLEC PROGRAM
SAVE (14,12)
SAVE REGISTERS
BALR BASEREG,O
ESTABLISH ADDRESSABILITY
USING *,BASEREG
FOR CSECT.
USING IHADCB,DCBREG
ESTABLISH ADDRESSABILITY
USING IECTDECB,DECBREG
FOR DCBS AND DECBS
ST
SAVEREG,SAVEAREA+4
STORE ADDRESS OF SAVE AREA
LA
SAVEREG,SAVEAREA
LOAD THIS PROG SAVE AREA ADDR
LA
DECBREG,CADECB
LOAD DECB USING REG
*********************************************************************
* OPEN PRINTER DATASET
*
*********************************************************************
LA
DCBREG,PRINTDCB
LOAD DCB DSECT REG
OPEN (PRINTDCB,(OUTPUT))
OPEN PRINTER DCB
TM
DCBOFLGS,X'10'
IF OPEN OK
BO
CAOPEN1
BRANCH
ABEND 1,DUMP
ELSE ABEND
*********************************************************************
*
ISSUE OPEN MACRO FOR SNAP DATASET * * * *
*********************************************************************
CAOPEN1 LA
DCBREG,SNAPDCB
LOAD DCB DSECT REG
OPEN (SNAPDCB,(OUTPUT))
OPEN SNAP DCB
TM
DCBOFLGS,X'10'
IF OPEN OK
BO
CAOPEN2
BRANCH
ABEND 2,DUMP
ELSE ABEND
*********************************************************************
* OPEN CHANNEL ATTACH DEVICE DCB
*
*********************************************************************
DCBREG,CADCB
LOAD DCB DSECT REG
CAOPEN2 LA
COP(8) ,OPEN
CURRENT OP = OPEN
MVC
OPEN SERIES/1 LINE GROUP DCB
OPEN (CADCB)
DCBOFLGS,X'10'
IF OPEN OK
TM
BO
CAINIT
BRANCH
LA
R2,MSG09
ELSE
R5,PRINTIO
PRINT MESSAGE
BAL
ELSE ABEND
ABEND 3,DUMP
CAINIT
EQU
*
PRINT BEGIN
LA
R2,MSGOO
TEST MESSAGE.
BAL
R5,PRINTIO
PRINT CHANNEL ATTACH
R2,MSG01
LA
DEVICE OPEN MESSAGE.
R5,PRINTIO
BAL
Figure 65 (Part 2 of 8). Host Sample Program
o
CO-166
SC34-0638
o
Channel Attach Sample Programs (continued)
*********************************************************************
*
READ ACKNOWLEDGE MESSAGE FROM SERIES/1 FOR BTAM OPEN'S WRITE.
*********************************************************************
BAL
BAL
RB,RDACK
R4,CHKRTN
READ S/1 ACK MSG
CHECK RETURN CODE
*********************************************************************
DO UNTIL COUNT = LIMIT
**********************************************************************
LOOP
LA
EQU
R3,NLIMIT
*
SET R3 = LIMIT
*********************************************************************
*
READ A MESSAGE
*********************************************************************
BAL
BAL
RB,RDINIT
R4,CHKRTN
READ FROM SERIES/1
CHECK RETURN CODE
*********************************************************************
*
WRITE A MESSAGE
*********************************************************************
WRIT
BAL
BAL
BAL
BAL
RB,WRINIT
R4,CHKRTN
RB,RDACK
R4,CHKRTN
WRITE TO SERIES/1
CHECK RETURN CODE
READ SERIES/1 ACKNOWLEDGEMENT
CHECK RETURN CODE
*********************************************************************
ENDDO
**********************************************************************
c
BCT
R3,LOOP
IF R3 NE ZERO CONTINUE
*********************************************************************
*
OUTPUT 'SAMPLEC TEST ENDED'
*********************************************************************
LA
BAL
R2,MSG04
R5,PRINTIO
PRINT END OF
TEST MESSAGE.
*********************************************************************
ISSUE CLOSE MACRO CHANNEL ATTACH DCB
**********************************************************************
MVC
COP(B),CLOSE
CLOSE CADCB
CURRENT OP = CLOSE
CLOSE LINE DCB
*********************************************************************
*
ISSUE CLOSE MACRO FOR PRINTER DATASET
*********************************************************************
EXIT
CLOSE PRINTDCB
EQU
*
L
SAVEREG,SAVEAREA+4
RETURN (14,12),RC=O
CLOSE PRINTER DCB
RESTORE SAVEREG
EXIT
Figure 65 (Part 3 of 8). Host Sample Program
o
Chapter 4. Channel Attach Program
CO-167
Channel Attach Program
o
Channel Attach Sample Programs (continued)
*********************************************************************
*
*
INTERNAL SUBROUTINE CHKRTN: CHECK I/O RETURN CODES
CALLING SEQUENCE:
BAL R4,CHKRTN
*********************************************************************
CHKRTN
CHKFL1
CHKFL2
CHKCC41
IOERROR
IOERR
EQU
CLI
BNE
CLI
BNE
BR
CLI
BNE
MVI
BR
CLI
BE
MVC
UNPK
MVI
TR
LA
BAL
ABEND
EQU
TM
BNO
TM
BNO
TM
BNO
LA
BAL
*
DECSDECB,X'7F'
CHKCC41
DECFLAGS,X'OO'
CHKFLl
R4
DECFLAGS,X'FO'
CHKFL2
READY,X'FF'
R4
DECSDECB,X'41 ,
IOERROR
WORK(l) ,DECSDECB
MSG02+28(3),WORK(2)
MSG02+30, C' ,
MSG02+28(2),TABL-240
R2,MSG02
R5,PRINTIO
4,DUMP
*
DECERRST,X'80'
IOERR
DECCSWST,X'02'
IOERR
DECSENSO,X'40'
IOERR
R2,MSG10
R5,PRINTIO
EXIT
B
WORK(1) ,DECFLAGS
MVC
UNPK MSG03+33 (3) ,WORK(2)
MSG03+35, C' ,
MVI
MSG03+33(2),TABL-240
TR
LA
R2,MSG03
BAL
R5,PRINTIO
ABEND 5,DUMP
IF ECB POST CODE IS BAD
BRANCH
ELSE IF FLAGS NOT ZERO
BRANCH
ELSE RETURN
IF DEVICE HAS NOT BECOME READY
BRANCH
ELSE SET READY FLAG
RETURN
IF ECB POST CODE IS I/O ERROR
BRANCH
ELSE LOAD POST CODE INTO WORK
LOAD CHAR INTO MSG
INSERT BLANK
TRANSLATE
PRINT
MESSAGE
ABEND
IF NOT SIO ERROR
BRANCH
ELSE IF NOT UNIT CHECK
BRANCH
ELSE IF NOT INTERVENTION REQ'D
'RRANC'H
ELSE
PRINT INTERVENTION REQ'D
EXIT
LOAD FLAGS INTO WORK
LOAD CHAR INTO MSG
INSERT BLANK
TRANSLATE
PRINT
MESSAGE.
ABEND
FIgUre 65 (Part 4 of 8). Host Sample Program
o
CO-168
SC34-0638
()
Channel Attach Sample Programs (continued)
********************************************************************
*
*
*
*
INTERNAL SUBROUTINE PRINTIO: PRINT MESSAGE
CALLING SEQUENCE:
LA R2,MSGXX
ADDR OF MSG IN R2(NOTE)
BAL PRINTIO,R5 PRINT MESSAGE
NOTE: FIRST BYTE PRECEDING THE MESSAGE HAS LENGTH OF MESSAGE.
********************************************************************
PRINTIO
LR
BCTR
CLI
BNH
LA
B
PRINT
PRINT1
IC
BCTR
EX
PUT
SNAP
MVI
MVC
BR
R1,R2
GET ADDR OF MSG
R1,O
GET ADDR OF MSG LENGTH
O(R1),128
IF MSG NOT TOO LONG
PRINT
BRANCH
R1,127
ELSE
PRINT1
TRUNCATE TO MAX LENGTH
R1,O(R1)
GET MSG LENGTH
R1,O
SUBTRACT ONE FOR MVC INSTR
R1,MOVE
EXECUTE MOVE INSTRUCTION
PRINT IT
PRINTDCB,PRTBUF
DCB=SNAPDCB,ID=10,
STORAGE=(PRTBUF,EPRTBUF)
PRTBUF,C' ,
SET PRINT
PRTBUF+1 (127) ,PRTBUF
BUFFER TO BLANKS.
RETURN
R5
********************************************************************
*
*
*
o
INTERNAL SUBROUTINE EMSG: PRINT BTAM MACRO ERROR MESSAGE
CALLING SEQUENCE: B EMSG
(OR EQUIVALENT)
ERROR CODE IN R15
********************************************************************
EMSG
STC
UNPK
MVI
TR
MVC
UNPK
MVI
TR
MVC
LA
BAL
B
R15,WORK
MSGOS+46(3),WORK(2)
MSG05+48,C"
MSG05+46(2),TABL-240
WORK(1),DECSDECB
MSGOS+59(3),WORK(2)
MSG05+61,C"
MSGOS+59(2),TABL-240
MSG05+26(8),COP
R2,MSG05
RS,PRINTIO
EXIT
SAVE RC INTO WORK
CONVERT TO ZONED FORMAT
INSERT BLANK FOR SIGN POSITION
TRANSLATE TO EBCDIC FOR PRINTI~G
MOVE DECSDECB INTO WORK
CONVERT TO ZONED FORMAT
INSERT BLANK FOR SIGN POSITION
TRANSLATE TO EBCDIC FOR PRINTI G
INSERT CURRENT BTAM OPERATION
PRINT
ERROR MESSAGE
EXIT
Figure 65 (Part 5 of 8). Host Sample Program
0:
,
,
Chapter 4. Channel Attach Program
CO-169
Channel Attach Program
Channel Attach Sample Programs (continued)
*********************************************************************
*
BTAM I/O REQUESTS
*********************************************************************
* READ ACKNOWLEDGE MESSAGE
)RDACK
LA
R2,MSGll
RDACK MESSAGE
B
RDALL
PRINT MESSAGE
* READ INITIAL
RDINIT
LA
R2,MSG06
RDINIT MESSAGE
RDALL
BAL
R5,PRINTIO
PRINT MESSAGE
MVC
COP(8),READ
CURRENT OP = READ
READ (DECBREG) ,TI,CADCB,AREAIN,LIN"RLN,MF=E
B
WAIT
* WRITE INITIAL
WRINIT
LA
R2,MSG07
WRINIT MESSAGE
BAL
R5,PRINTIO
PRINT MESSAGE
MVC
COP(8),WRITE
CURRENT OP = WRITE
WRITE (DECBREG),TI,CADCB,AREAOUT,LOUT"RLN,MF=E
B
WAIT
* WRITE UNPROTECTED ERASE
WRUNER
LA
R2,MSG08
WRUNER MESSAGE
BAL
R5,PRINTIO
PRINT MESSAGE
MVC
COP(8),WRITE
CURRENT OP = WRITE
WRITE (DECBREG) ,TUS,CADCB,AREAOUT,l"RLN,MF=E
B
WAIT
********************************************************************
*
WAIT FOR I/O COMPLETION
********************************************************************
WAIT
LTR
R15,R15
IF I/O RETURN CODE IS NONZERO
BNZ
EMSG
BRANCH
WAIT 1,ECB=(DECBREG)
ELSE WAIT FOR I/O TO COMPLETE
SNAP DCB=SNAPDCB, ID=20,PDATA= (PSW,REGS) ,
STORAGE=(SAVEAREA,PRINTDCB)
CLC
COP(8),READ
IF COP EQ READ
BE
WRUNER
BRANCH TO WRITE ACK
BR
R8
RETURN
o
c::)
Figure 65 (Part 6 of 8). Host Sample Program
o
CO-170
SC34-0638
o
Channel Attach Sample Programs (continued)
********************************************************************
*
DATA DECLARATIONS
********************************************************************
DS
LTORG
SAVEAREA DS
LIMIT
DC
MOVE
MVC
WORK
DC
DC
MSGOO
DC
DC
MSGOl
DC
DC
MSG02
DC
DC
MSG03
DC
DC
MSG04
DC
DC
MSG05
DC
MSG10
DC
DC
DC
DC
DC
DC
DC
DC
DC
DC
MSGll
COP
READ
WRITE
CLOSE
DC
DC
DC
DC
DC
DC
MSG06
MSG07
0
MSG08
MSG09
OF
WORD ALIGNMENT
18F
SAVE AREA
F'O'
LIMIT COUNTER VALUE
PRTBUF(1),O(2)
MOVE INSTR IS EXECUTED BY EX
X'OOOF'
WORK SPACE
ALl (L'MSGOO)
C'SAMPLEC TEST STARTED'
AL 1 (L' MSGO 1 )
C'CHANNEL ATTACH DEVICE OPENED. '
AL 1 (L' MSG02)
C'SAMPLEC:
COMPLETION CODE = XX
AL 1 (L' MSGO 3 )
C'SAMPLEC:
I/O ERROR. DECFLAGS
XX
AL 1 (L' MSGO 4 )
C'SAMPLEC TEST ENDED'
ALl (L'MSG05)
C'BTAM OPERATION ERROR FROM XXXXXXXX MACRO.
RC= YY DECSDX ECB= ZZ '
AL 1 (L' MSGO 6 )
C'RDINIT
ALl (L'MSG07)
C'WRINIT
AL 1 (L' MSGO 8 )
C'WRUNER
AL 1 (L' MSGO 9 )
C'CHANNEL ATTACH DEVICE COULD NOT BE OPENED.'
ALl (L'MSG10)
C'INTERVENTION REQUIRED ON CHANNEL ATTACH DEVICE.
ISSUE X SERIES/l OPERATOR COMMAND: "STDV CAl" ,
AL 1 (L' MSG 11 )
C'RDACK
CL8' ,
CURRENT BTAM OPERATION
CL8'READ'
READ
CL8'WRITE'
WRITE
CL8'CLOSE'
CLOSE
Figure 65 (Part 7 of 8). Host Sample Program
o
Chapter 4. Channel Attach Program
CO-17I
Channel Attach Program
o
Channel Attach Sample Programs (continued)
OPEN
PRTBUF
EPRTBUF
READY
TABL
AREAIN
EAREAIN
AREAOUT
ENDOUT
NLIMIT
LIN
LOUT
DC
DS
DC
EQU
DC
DC
DC
EQU
DC
DC
DC
DC
DC
DC
DC
EQU
EQU
EQU
EQU
CL8'OPEN'
OPEN
FULLWORD ALIGNMENT
128C' ,
PRINT BUFFER
ADDR OF LAST WORD IN PRTBUF
*-4
X'OO'
READY FLAG
C'0123456789ABCDEF'
TRANSLATE TABLE
256C' ,
INPUT AREA
ADDR OF LAST WORD IN INPUT
*-4
C'THE QUICK BROWN FOX ' AREA
C'JUMPED OVER THE LAZY'
C' DOG AND THE DISH RA'
C'N AWAY WITH THE SPOOl
C'N * $RIGX0004$ * () ,
C'SYSTEM/370 -> SERIES'
C'/1
OF
*
2
AREAOUT-AREAIN
ENDOUT-AREAOUT
LOOP COUNT
LENGTH OF INPUT AREA
LENGTH OF INPUT AREA
********************************************************************
*
CONTROL BLOCKS
********************************************************************
READ
CADCB
DCB
PRINTDCB DCB
SNAPDCB
CADECB,TI,AREAIN,LIN"RLN,MF=L
DSORG=CX,MACRF=(R,W),DDNAME=S1GROUP,EROPT=E
BLKSIZE=128,DDNAME=PRINTER,DSORG=PS,
LRECL=128,MACRF=(PM) ,RECFM=FB
DCB
DSORG=PS,RECFM=VBA,MACRF=(W),BLKSIZE=1632,LRECL=125,
DDNAME=SNAP
DCBD DSORG=BS,DEVD=DA
IECTDECB
END
Figure 65 (Part 8 of 8). Host Sample Program
o
CO-172
SC34-0638
()
Part 3. Specialized Series/1 Event Driven
Executive Communications Methods
c
Part 3 discusses the two methods of communications that you can use on Series/l only with the
Event Driven Executive operating system:
•
Series/l-to-Series/l Attachment
•
General Purpose Interface Bus (GPIB) Adapter.
o
Part 3. Specialized Series/l Event Driven Executive Communications Methods
CO-173
Notes
o
o
CO-174
SC34-0638
o
Chapter 5. Series/1-to-Series/1 Attachment
Support
()
Your Series/l can communicate directly with the processor of another Series/lin a
configuration called a Series/ I-to-Series/ 1 attachment. The two processors communicate over
a connection established by RPQ 002241 and RPQ 002242 attachment cards plugged into each
processor's I/O channel and connected by a cable. (One processor uses RPQ 002241 and the
other RPQ D02242.) Each RPQ card connected to a given Series/l must have its own cable.
For hardware installation and configuration details, refer to the Series/ l-to-Series/ 1 Attachment
(RPQs D02241 and D02242) Custom Feature.
Application programs running on both processors control the transfer of data between the two
Series/Is. A separate synchronization program, also running simultaneously on the two
processors, synchronizes the execution of the application programs.
To communicate with the processor that your Series/lis attached to, you must write application
programs to perform data transfers, and synchronization programs to control the application
programs.
Planning the Series/1-to-Series/1 Application
Certain requirements and restrictions apply to the Series/Ito Series/l application.
o
Chapter 5. Series/ I-to-Series/ 1 Attachment Support
CO-l 75
Series/1-to-Series/1 Attachment Support
Planning the Series/1-to-Series/1 Application (continued)
Processor Relationships
o
Normally, the attached Series/l systems communicate in a peer-to-peer relationship. Both
processors contend with equal priority to initiate data transfers. However, the Series/l to
Series/l attachment allows one processor to IPL the other (remote IPL). This establishes a
primary-and-secondary processor relationship between the two Series/Is. Only the processor
connected with RPQ D02241 can perform the remote IPL. When remote IPL is complete, the
processor with RPQ D02241 functions as the primary and the processor with RPQ D02242 as
the secondary. The primary processor controls the data transfers, thus eliminating contention
between the two.
Initiating Data Transfers
Either Series/l can initiate a data transfer to the other, regardless of the relationship between
the processors. A data transfer can write data to the other processor, read data from it, or issue
a control instruction. The receiving processor must always respond to a data transfer by sending
back the opposite instruction to the initiating processor. For example, if the initiating processor
performs a write operation, the receiving processor must answer with a read operation.
Responding to External Events
A processor that receives an external interrupt while attached to another Series/l can record the
external event by posting an event control block (ECB). For example, one processor may need
to receive data from a device attached to it while it is in the middle of talking to the other
processor.
However, it is possible to post an event control block even if the processor is not communicating
with the other Series/I. This enables other terminal I/O tasks to execute on the posting
processor while it waits for communications from the other processor.
Figure 66 on page CO-177 illustrates setup and usage of posting a user ECB. The program
should execute on both processors.
The program has three tasks:
•
Task 1 performs a write (PRINTEXT) and is driven by an external event, in this case task 3,
which is a timer task. It could be sensor I/O or BSC as well.
•
Task 2 performs a read (READTEXT). It responds only to an attention interrupt on the
Series/l-to-Series/llink, or to a post from task 1.
•
Task 3 is a timer task, intended to simulate external stimuli.
o
CO-l 76
SC34-0638
o
Planning the Series/1-to-Series/1 Application (continued)
T1
GO
*
WAITT1
o
*
*
*
*
*
T2
T2GO
PROGRAM GO,30
PRINT
OFF
COPY
CCBEQU
PRINT
ON
EJECT
RESET
ECB
RESET ECB FOR S1S1
TECB
RESET ECB FOR TIMER TASK
RESET
MOVE
BUF-2,256
SET TO READ/WRITE 256 BYTES
MOVE
BUF-4,BUF-2
ENQT
S1S1
GET S1S1
TCBGET
#1,$TCBCCB
GET CCB ADDRESS OF S1S1
MOVEA
#2,ECB
SET ECB ADDR IN CCB
MOVE
($CCBS1EI+2,#1),#2,TKEY=0
DO IT
TCBGET
#2, $ TCBAKR
GET AKR
AND
#2,X'0030'
AND TO GET OP2
SHIFTR
#2,4
MOVE IT OVER TO BITS 13-15
MOVE
($CCBS1EI,#1),#2,TKEY=0
SET INTO CCB
DEQT
S1S1
GIVE UP S1S1
ATTACH
T2
START TIMER TASK
ATTACH
T3
START READ TASK
TASK 2 ALWAYS DOES A WRITE (PRINTEXT)
WAIT
TECB
WAIT FOR TIMER TASK
RESET
TECB
CLEAR TIMER ECB
ENQT
S1S1
PRINTEXT BUF,XLATE=NO
WRITE DATA
MOVE
T1STAT,T1
CHECK STATUS
IF
(T1STAT,EQ,-1)
IF OK
ADD
NUMT1,1,PREC=DS
BUMP COUNT
ELSE
ADD
NUMT1E,1,PREC=DS
IF ERROR, BUMP COUNT
DUE TO THE ASYNCHRONOUS NATURE OF THE S1/S1
WE MUST POST THE ECB WHEN WE GET AN ERROR HERE - ASSUMING
IT IS AN INVALID SEQUENCE ERROR (PRINTEXT FACING PRINTEXT)
POST
ECB,-1
POST THE ECB JUST IN CASE
ENDIF
DEQT
GOTO
WAITT1
LOOP
TASK 2 ALWAYS DOES A READ
TASK
T2GO,25
EQU
*
Figure 66 (Part 1 of 2). Program for Posting an Event Control Block
~,
'-Ii
Chapter 5. Series/l-to-Series/l Attachment Support
CO-I77
Series/1-to-Series/1 Attachment Support
Planning the Series/1-to-Series/1 Application (continued)
SLEEP
*
T3
T3GO
ECB
TECB
T1STAT
T2STAT
NUMT1
NUMT1E
NUMT2
NUMT2E
TYPE
ZERO
S1S1
BUF
c
WAIT
ECB
WAIT ON ECB POSTED BY S1S1
RESET
ECB
RESET ECB
S1S1
ENQT
CLEAR HEADER AREA
BUF,O,DWORD
MOVE
SEE IF A READ
TERMCTRL STATUS,BUF,WAIT=NO
IF NO OPERATION READY
IF
(BUF,EQ,ZERO,4)
DEQT
GO BACK TO SLEEP
GOTO
SLEEP
ENDIF
IF OPERATION READY
AND
BUF,X'2000'
(BUF,EQ,ZERO)
SEE IF REQUIRES A READTEXT
IF
DEQT
IF NOT, GO BACK TO SLEEP
GOTO
SLEEP
ENDIF
IF REQUIRES A READ, DO IT
READTEXT BUF,XLATE=NO
CHECK STATUS
MOVE
T2STAT,T2
(T2STAT,EQ,-1)
IF
BUMP COUNT
NUMT2,1,PREC=DS
ADD
ELSE
BUMP ERROR COUNT
NUMT2E,1,PREC=DS
ADD
ENDIF
DEQT
LOOP
GOTO
SLEEP
TASK 3 MERELY WAKES UP TASK 1 PERIODICALLY
T3GO,510
TASK
EQU
*
STIMER
50,WAIT
TECB
POST
GOTO
T3GO
EJECT
-1
ECB
-1
ECB
F'O'
DATA
F'O'
DATA
D'O'
DATA
D'O'
DATA
D'O'
DATA
D'O'
DATA
F'O'
DATA
D'O'
DATA
X'0808'
DATA
S1S1,BUFFER=BUF
IOCB
1024,BYTES
BUFFER
ENDPROG
END
Figure 66 (Part 2 of 2). Program for Posting an Event Control Block
o
CO-178
SC34-0638
o
Programming for Series/1-to-Series/1 Attachment
You must write application programs using a set of Event Driven Language instructions that
implement Series/l-to-Series/l communication. Your program can perform any type of data
transfer (read, write or control operation). You can also write a program to synchronize the
execution of the application program on both processors.
Event Driven Language Instruction Set
The following Event Driven Language instructions allow communication between the Series/ls.
For descriptions and syntax of the instructions, refer to the Language Reference
Instruction
DEQT
Explanation
Releases the Series/1 previously enqueued with the
ENQT instruction
ENQT
Acquires exclusive right to communicate with the
enqueued Series/1
IOCB
Identifies the Series/ 1 as the enqueued processor
PRINTEXT
Writes a message to the enqueued Series/1
READTEXT
Reads a message from the enqueued Series /1
TERMCTRL
Performs control functions on the enqueued
Series/1
Figure 67. EDL Instructions for Communication between Series/Is
Basic Programming Tasks
To communicate with the other Series/l processor, your program must perform the following
tasks:
•
Gain exclusive ability to communicate with the other processor (enqueue with ENQT
instruction)
•
Identify the other processor (lOCB instruction)
•
Write data to or read data from the other processor (PRINTEXT or READTEXT
instruction)
•
Perform control functions on the other processor (TERMCTRL instruction).
In addition, your program should provide for error detection and handling, and keep a count of
the data transfers.
o
Chapter 5. Series/l-to-Series/l Attachment Support
CO-l79
Series/1-to-Series/1 Attachment Support
Programming for Series/1-to-Series/1 Attachment (continued)
Enqueuing the Other Processor
o
Before your Series/l can make data transfers to the other Series/I, you must gain exclusive
right to communicate with that processor. The instruction that performs this function is ENQT.
The other processor is treated as a terminal that your Series/l enqueues. No other device or
processor is able to send data to the other Series/l while you have it enqueued. Because ENQT
treats the other processor as a terminal, you must specify its symbolic identity. You must refer
to the label of the IOCB instruction, which identifies the enqueued Series/l in your program.
The IOCB instruction is covered in the section that follows.
Identifying the Enqueued Processor
You must specify the identity of the processor that your Series/l is going to communicate with.
The IOCB instruction provides this information.
Give the lOeB instruction a label when you code it. You must refer to this label in the ENQT
and DEQT instructions for the program.
A typical way to identify the Series/l in IOCB is "S 1S1."
Writing Data to the Enqueued Processor
To write data to the other Series/I, code a PRINTEXT instruction. Besides using PRINTEXT
to simply initiate a write operation, code it in response to a READTEXT instruction issued by
the other processor.
Reading Data from the Enqueued Processor
To read data from the other processor, code a READTEXT instruction. Besides using
READTEXT to simply initiate a read operation, code it in response to a PRINTEXT issued by
the other processor.
Performing Control Functions on the Enqueued Processor
You can perform certain control functions on the other processor by coding TERMCTRL
instructions. The functions that apply to the Series/ I-to-Series/ 1 Attachment are listed in the
chart below.
Function
ABORT
IPL
Explanation
What to Code
Enqueued processor sends
back a message to your
Series/l telling it to terminate
the last function
TERMCTRL ABORT
Performs remote I PL of the
enqueued processor
TERMCTRL IPL
Figure 68 (Part 1 of 2). TERMCTRL Functions for Series/l-to-Series/l Communications
o
CO-180
SC34-0638
o
Programming for Series/1-to-Series/1 Attachment (continued)
Function
RESET
Explanation
Resets to the last ENQT
issued
What to Code
TERMCTRL RESET
STATUS
Obtains status of enqueued
processor
TERMCTRL STATUS
Figure 68 (Part 2 of 2). TERMCTRL Functions for Series/l-to-Series/l Communications
Do not attempt to use any TERMCTRL functions other than those specifically for
Series/ 1-to-Series/ 1 attachment.
Programming Considerations
Certain requirements and restrictions apply to programming for the Series/ 1-to-Series/ 1
attachment.
•
If a program that has issued an ENQT loads a program (via LOAD), the new program will
have the Series/ 1-to-Series/ 1 as its default terminal. Therefore, a DEQT instruction should
always be issued to the attachment before issuing the LOAD.
•
c
Data to be transferred must start at an even address.
Byte counts (data length) must be even.
Return codes must be examined by the application. The return code is placed in the first
word of the task control block (TCB). The return codes for the operations performed by
the attachment are described in the Messages and Codes with the PRINTEXT /READTEXT
instructions.
•
Synchronization between the two processors is possible only by checking and responding to
the return codes and by using TERMCTRL STATUS. A listing of the return codes can be
obtained by including the copy code "COPY ERRORDEF" in your program.
•
Do not use the CT command of the $TERMUT1 utility to reconfigure the
Series/1-to-Series/1. The CT command parameters are not valid for the
Series/1-to-Series/1 Attachment. Using $TERMUT1 to change attributes will cause
unpredictable results.
•
Byte counts must be equal on each processor. For example, if processor A issues a
READTEXT for 50 bytes, then processor B must respond with a PRINTEXT for 50 bytes.
However, if Event Driven Executive terminal I/O buffer management is utilized, this may
be very difficult to achieve unless direct I/O is used. Direct I/O means that a buffer is
specified in the application program by an 10CB statement and the lOeB is enqueued
(ENQT) prior to issuing a PRINTEXT /READTEXT instruction. Data is transferred
directly from the buffer instead of the buffer generated by the TERMINAL configuration
statement. Refer to the Event Driven Executive Language Programming Guide for a
description of the 10CB statement and for further information on direct I/O.
o
Chapter 5. Series/l-to-Series/l Attachment Support
CO-181
Series/1-to-Series/1 Attachment Support
Programming for Series/1-to-Series/1 Attachment (continued)
Your program should use direct I/O, with XLATE=NO, and should always transmit
fixed-length records. Terminal I/O buffer management allows the number of bytes to vary
for a PRINTEXT, but not for a READTEXT. READTEXT always reads the number of
bytes specified by the TERMINAL statement LINSIZE parameter. PRINTEXT writes the
number of bytes specified by the LENGTH parameter or the number of bytes in the
message itself.
You may not be able to synchronize the byte counts unless direct I/O is used. If, however,
direct I/O is not used and buffering of data with PRINTEXT /READTEXT instructions is
performed, the results of using these instructions are shown in Figure 69. The "error" in the
figure means that an invalid data length status is returned to the application.
Initiating
Processor
READTEXT of x bytes
PRINTEXT of x bytes
Responding
Processor
PRINTEXT of x bytes
of less than x bytes
of more than x bytes
READTEXT of x bytes
of less than x bytes
of more than x bytes
Status Returned to
Responding Processor
OK
OK
error
OK
error
OK
Figure 69. Usage of READTEXT /PRINTEXT without Direct I/O
CO-182
•
Except for the device address, use identical TERMINAL statements for each processor. The
results will be unpredictable if the TERMINAL statements differ.
•
The IPL function of the $SISI UTI utility reads a specified nucleus from a disk and sends
this nucleus to the other processor. The IPL function does not merely trigger the other
processor to IPL from a disk or diskette. Therefore, the other processor does not require a
disk or diskette. If the other processor does not have a disk or diskette, then the nucleus
being sent must contain the supervisor and your application program. One processor cannot
load a program on another processor.
•
The Series/l-to-Series/l Attachment supports only a subset of the terminal I/O
instructions. Using instructions other than those described in the Language Reference for
Series/ l-to-Series/ I can cause unpredictable results. In addition, only the RESET,
ABORT, STATUS, and IPL functions of the TERMCTRL instruction should be used.
•
When a processor issues a PRINTEXT or READTEXT instruction (with or without direct
1/0), control is not returned to the issuing program until the data transfer is complete (the
other processor issues the opposite operation). Therefore, it is not necessary to perform
request/ acknowledge operations.
•
TERMCTRL RESET is used for error recovery. This operation causes the attachment to
reset. The two applications must be synchronized to avoid an error/reset loop.
SC34-0638
o
o
Programming for Series/1-to-Series/1 Attachment (continued)
For example, an error/reset loop can occur if program A issues a PRINTEXT and
encounters an error, issues a TERMCTRL RESET, and reissues the PRINTEXT. Program
B, on the other hand, issues a READTEXT (at approximately the same time as program A's
initial PRINTEXT) and receives an error. However, because of heavy processor or I/O
activity, program B is unable to issue its TERMCTRL RESET until after program A has
already performed its reset and reissued a PRINTEXT. Hence, program B's reset will cause
program A to receive an error while program A is issuing its second PRINTEXT (retry).
Both programs enter the loop as a result of trying to read or write while the programs are no
longer synchronized and the attachments are being reset. Issuing an STIMER instruction
(with WAIT) in the error recovery routine in program A can help avoid entering an
error / reset loop.
•
Only two of the possible errors can occur concurrently on both processors. These errors
should be taken into consideration in your error recovery routine:
1004 - Checksum error
1008 - Time-out error.
Programming Examples
o
The following programs perform data transfers controlled by a synchronization program. The
processors are assumed to be operating in a primary-to-secondary relationship. The PRIMARY
program runs on the Series/l using RPQ D02241; the SECOND program runs on the Series/l
using RPQ D02242. Both of these programs run simultaneously on the two processors. The
SYNC program controls their execution.
Primary Processor Sample Program
The PRIMARY program controls the SECOND program. The processor running PRIMARY
can abort the SECOND program. The operator presses the attention key and enters "AB" at
the terminal that loaded PRIMARY. The command "MS" sends a message, a count of the
transfers, and their length. Note the code for error recovery.
()
Chapter 5. Series/l-to-Series/l Attachment Support
CO-183
Series/1-to-Series/1 Attachment Support
Programming for Series/1-to-Series/1 Attachment (continued)
PRIMARY
*
*
ABT
MSG
GO
GETSIZE
G01
G02
*
PROGRAM
ATTNLIST
EQU
MOVE
ENDATTN
EQU
MOVE
ENDATTN
PRINTEXT
PRINT EXT
PRINTEXT
EQU
GETVALUE
IF
AND
IF
PRINTEXT
GO TO
ENDIF
QUESTION
ENQT
TERMCTRL
DEQT
EQU
QUESTION
QUESTION
EQU
MOVE
MOVE
MOVE
MOVE
MOVE
MOVE
MOVE
MOVE
ENQT
o
GO
(AB,ABT,MS,MSG)
*
ABSW,1
SET ABORT FLAG
*
SET MESSAGE FLAG
MSW,1
'@I AM THE PRIMARY SERIES/1@'
'@"> AB" TO ABORT SECOND@'
'@"> MS" TO SEND MESSAGE FLASH@'
*
BUFI,'@ENTER DATA LENGTH(6 ==> 4096)@'
(BUFI,LT,6) ,OR, (BUFI,GT,4096) ,GOTO,GETSIZE
BUFI,X'0001' ,RESULT=TEMP
TEMP,NE,O
'@DATA LENGTH CANNOT BE ODD@'
GETSIZE
'@RESET S1S1? ',NO=G01
S1S1
RESET
*'@READY?
',YES=G02
'@TERMINATE? ',YES=STOP1,NO=GO
*
SET UP CONSTANTS
FOR RESTART
SET DATA LENGTH
BUFI+2,BUFI
CLEAR STATUS
STAT, 0
CLEAR ABORT SWITCH
ABSW,O
CLEAR MESSAGE SWITCH
MSW,O
SET TYPE
TYPE,-1
CLEAR COUNTER
COUNT,O,DWORD
CLEAR S1S1 HEADER
HBUF,O, (6,BYTES)
CSs,O, (24,BYTES)
CLEAR S1S1 CSS
S1S1
Figure 70 (Part 1 of 4). Primary Processor Sample Program
o
CO-184
SC34-0638
0
Programming for Series/1-to-Series/1 Attachment (continued)
CONT
*
*
*
0
EQU
MOVE
ADD
MOVE
MOVE
*
TYPE, 1
COUNT,1,PREC=D
BUF, COUNT, DWORD
BUF+4,MSW
MOVE
PRINTEXT
MOVE
IF
CALL
GOTO
ENDIF
MOVE
MOVE
IF
MSW,O
BUF,XLATE=NO
STAT, PRIMARY
STAT,NE,-1
S1ERR
ERROR
ADD
READTEXT
MOVE
IF
CALL
GOTO
ENDIF
IF
COUNT,1,PREC=D
BUF,XLATE=NO
STAT, PRIMARY
STAT,NE,-1
S1ERR
ERROR
PRINTEXT
CALL
GOTO
ENDIF
IF
BUF,O, (6,BYTES)
TYPE,O
(ABSW,NE,O),GOTO,ABORT
SET TYPE = WRITE
INCREMENT COUNTER
MOVE COUNTER TO BUFFER
MOVE MESSAGE SWITCH
TO BUFFER
CLEAR MESSAGE SWITCH
GET STATUS
CHECK FOR BAD STATUS
CALL ERROR SUBROUTINE
ERROR EXIT
CLEAR BUFFER
SET TYPE = READ
CHECK OPERATOR
ABORT REQUEST
INCREMENT COUNTER
ACKNOWLEDGE
GET STATUS
IF ERROR CALL ERROR SUBROUTINE
IF COUNT BAD OUT OF SYNC
'@OUT OF SYNC - COUNT FAILURE@'
S1ERR
ERROR
(BUF,NE,COUNT,DWORD)
BUF+4,NE,O
*
CHECK MESSAGE
FLAG REQUEST
Figure 70 (Part 2 of 4). Primary Processor Sample Program
o
Chapter 5. Series/l-to-Series/l Attachment Support
CO-18S
Series/1-to-Series/1 Attachment Support
Programming for Series/1-to-Series/1 Attachment (continued)
DEQT
PRINTEXT
PRINTEXT
PRINTNUM
PRINTEXT
PRINTNUM
PRINTEXT
ENQT
ENDIF
GOTO
**
*
*
*
ERROR
o
'@MESSAGE RECEIVED FROM SECOND@'
'COUNT= '
COUNT,FORMAT=(12,0,I),TYPE=D
'@DATA LENGTH = '
BUFI,FORMAT=(6,0,I)
'@'
S1S1
CONT
ERROR EXIT
IF GET AN ERROR - RESET THE OTHER
DEVICE, WAIT, THEN RETRY.
*
STOP
STOP1
**
*
ABORT
ABORT 1
EQU
DEQT
ENQT
TERMCTRL
STIMER
DEQT
PRINTEXT
GOTO
EQU
DEQT
QUESTION
EQU
PROGSTOP
*
S1S1
RESET
200,WAIT
RESET S1S1
WAIT 200 MS
'@AUTO RESTART@'
G02
RESTART
AUTOMATICALLY
*
'@RESTART? ',YES=GO
*
ABORT ROUTINE
EQU
DEQT
PRINTEXT
EQU
ENQT
STIMER
TERMCTRL
IF
TERMCTRL
DEQT
PRINTEXT
GOTO
ENDIF
DEQT
PRINTEXT
GOTO
*
'@OPERATOR REQUESTED ABORT@'
*
S1S1
1000,WAIT
STATUS,HBUF
(HBUF,NE,DO,DWORD)
ABORT
WAIT 1 SECOND
SECONDARY TALKING TO ME?
IF YES - ABORT SECOND
'@ABORT ISSUED AS PER REQUEST@'
STOP
END IT
'@SECOND DID NOT REQUEST DATA IN 1 SECOND@'
STOP
END IT
Figure 70 (Part 3 of 4). Primary Processor Sample Program
()
CO-186
SC34-0638
o
Programming for Series/1-to-Series/1 Attachment (continued)
**
*
c
HBUF
CSS
*
STAT
TYPE
COUNT
MSW
ABSW
S1S1
BUF
DO
TEMP
S1S1 ERROR SUBROUTINE
SUBROUT
S1ERR
TERMCTRL STATUS,HBUF,CSS
DEQT
ENQT
PRINTEXT '@BUF: '
PRINTNUM BUF
PRINTEXT '@TYPE: '
PRINTNUM TYPE
PRINT EXT '@COUNT: '
PRINTNUM COUNT,FORMAT=(12,O,I) , TYPE=D
PRINTEXT '@I/O ERROR ON S/1-S/1 - STATUS
PRINTNUM STAT,MODE=HEX
PRINTEXT , HEX; ,
PRINTNUM STAT
PRINTEXT , DEC@'
PRINTEXT
'@HEADER: '
PRINTNUM
HBUF,2,MODE=HEX
PRINTEXT , @'
'DIAGNOSTIC JUMPER WORD: '
PRINTEXT
PRINTNUM CSS,1,MODE=HEX
PRINTEXT '@'
'CYCLE STEAL STATUS: '
PRINTEXT
PRINTNUM CSS+2,11,MODE=HEX
PRINTEXT '@'
DEQT
RETURN
S1S1 HEADER
2F'O'
DATA
JUMPER + CYCLE
12F'O'
DATA
STEAL STATUS
F'O'
STATUS RETURN
DATA
READ/WRITE TYPE
DATA
F' -1 '
D'O'
SYNC COUNTER
DATA
F'O'
MESSAGE SWITCH
DATA
F'O'
ABORT SWITCH
DATA
IOCB
S1S1,BUFFER=BUF
BUFFER
4096,BYTES,INDEX=BUFI
D'O'
DWORD CONSTANT
DATA
F'O'
TEMP STORAGE
DATA
ENDPROG
END
Figure 70 (Part 4 of 4). Primary Processor Sample Program
o
Chapter 5. Series/l-to-Series/l Attachment Support
CO-187
Series/1-to-Series/1 Attachment Support
Programming for Series/1-to-Series/1 Attachment (continued)
Secondary Processor Sample Program
o
The SECOND program is controlled by the PRIMARY program. The attention command
"MS" sends a message, transfer count, and data length to PRIMARY.
SECOND
*
*
MSG
GO
G01
G02
*
*
*
*
*
*
PROGRAM
GO
ATTNLIST
EQU
MOVE
ENDATTN
PRINTEXT
PRINTEXT
QUESTION
ENQT
TERMCTRL
DEQT
EQU
QUESTION
QUESTION
EQU
(MS,MSG)
*
MSW,1
SET MESSAGE SWITCH
'@I AM THE SECOND@'
'@"> MS" TO SEND MESSAGE FLASH@'
'@RESET S1S1? ',NO=G01
S1S1
RESET
RESET DEVICE
*'@READY?
',YES=G02
'@TERMINATE? ',YES=STOP1,NO=GO
*
HERE WE WAIT FOR THE MASTER TO INITIATE A DATA
TRANSFER. WHEN IT DOES, WE USE ITS DATA LENGTH
AND PROCEED.
STIMER
ENQT
TERMCTRL
DEQT
IF
DEQT
PRINTEXT
GOTO
ENDIF
MOVE
MOVE
MOVE
MOVE
MOVE
MOVE
MOVE
ENQT
1000,WAIT
S1S1
STATUS,HBUN
GET STATUS
(HBUF,EQ,DO,DWORD)
IF NO DATA HERE YET
WAIT 1 SECOND
'@NO DATA FROM MASTER IN 1 SECOND@'
G02
SHOULD HAVE HAD
DATA BY NOW
BUFI,HBUF+2
BUFI+2,HBUF+2
STAT,O
COUNT,O,DWORD
TYPE,-1
HBUF, 0, (6, BYTES)
CSs,O, (24,BYTES)
S1S1
GET DATA LENGTH
INTO BUFFER
CLEAR STATUS
CLEAR COUNTER
INIT TYPE
CLEAR S1S1 HEADER
CLEAR CSS
Figure 71 (Part 1 of 4). Secondary Processor Sample Program
o
CO-I88
SC34-0638
o
Programming for Series/1-to-Series/1 Attachment (continued)
CONT
*
*
0
.,
'1
EQU
MOVE
ADD
MOVE
READTEXT
MOVE
IF
CALL
GOTO
ENDIF
IF
DEQT
PRINTEXT
CALL
GOTO
ENDIF
IF
DEQT
PRINTEXT
PRINTEXT
PRINTNUM
PRINTEXT
PRINTNUM
PRINTEXT
ENQT
ENDIF
*
TYPE,O
COUNT,1,PREC=D
BUF,O, (6,BYTES)
BUF,XLATE=NO
STAT, SECOND
STAT,NE,-1
S1ERR
SET TYPE = READ
INCREMENT COUNTER
CLEAR BUFFER
GET STATUS
ERROR - CALL
ERROR SUBROUT
ERROR
(BUF,NE,COUNT,DWORD)
CHECK COUNT FOR SYNC
'@OUT OF SYNC - COUNT FAILURE@'
S1ERR
ERROR
(BUF+4,NE,O)
CHECK FOR MESSAGE
REQUEST
'@MESSAGE RECEIVED FROM MASTER@'
'COUNT = '
COUNT,FORMAT=(12,O,I) , TYPE=D
'@DATA LENGTH = '
BUFI,FORMAT=(6,O,I)
'@'
S1S1
Figure 71 (Part 2 of 4). Secondary Processor Sample Program
Chapter 5. Series/l-to-Series/l Attachment Support
CO-189
Series/1-to-Series/1 Attachment Support
Programming for Series/1-to-Series/1 Attachment (continued)
*
*
STOP
STOP1
**
*
*
*
ERROR
ADD
MOVE
MOVE
COUNT,1,PREC=D
BUF",COUNT , DWORD
BUF+4,MSW
MOVE
MOVE
PRINTEXT
MOVE
IF
MSW,O
TYPE, 1
BUF,XLATE=NO
STAT, SECOND
STAT,NE,-1
CALL
GO TO
ENDIF
GOTO
EQU
DEQT
QUESTION
EQU
PROGSTOP
S1ERR
ERROR
CONT
INCREMENT COUNTER
MOVE COUNT TO BUFFER
MOVE MESSAGE SWITCH
TO BUFFER
CLEAR MESSAGE SWITCH
SET TYPE = WRITE
GET STATUS
IF ERROR - CALL
S1S1 ERROR
GO TO ERROR ROUTINE
CONTINUE
*
'@RESTART? ',YES=GO
*
IF THE ERROR IS AN ABORT REQUEST, TERMINATE THE
EXERCISE. IF IT IS ANY OTHER ERROR, RESET THE
DEVICE, AND START OVER.
EQU
DEQT
IF
PRINTEXT
GOTO
ENDIF
ENQT
TERMCTRL
DEQT
GOTO
*
(STAT,EQ,1010)
'@MASTER ISSUED ABORT@'
STOP
S1S1
RESET
SEE IF ABORT
RESET DEVICE
G02
Figure 71 (Part 3 of 4). Secondary Processor Sample Program
o
CO-190
SC34-0638
o
Programming for Series/1-to-Series/1 Attachment (continued)
*
*
*
c
S1S1
HBUF
CSS
*
STAT
TYPE
COUNT
MSW
ABSW
BUF
DO
S1S1
ERROR SUBROUTINE
SUBROUT
TERMCTRL
DEQT
ENQT
PRINTEXT
PRINTNUM
PRINTEXT
PRINTNUM
PRINTEXT
PRINTNUM
PRINTEXT
PRINTNUM
PRINTEXT
PRINTNUM
PRINTEXT
PRINTEXT
PRINTNUM
PRINTEXT
PRINTEXT
PRINTNUM
PRINTEXT
PRINTEXT
PRINTNUM
PRINTEXT
DEQT
RETURN
IOCB
DATA
DATA
S1ERR
STATUS,HBUF,CSS
DATA
DATA
DATA
DATA
DATA
BUFFER
DATA
ENDPROG
END
'@BUF: '
BUF
'@TYPE: '
TYPE
'@COUNT: '
COUNT,FORMAT=(12,O,I),TYPE=D
'@I/O ERROR ON S/1-S/1 - STATUS
STAT,MODE=HEX
, HEX; ,
STAT
, DEC@'
'@HEADER: '
HBUF,2,MODE=HEX
'@'
'DIAGNOSTIC JUMPER WORD: '
CSS,1,MODE=HEX
'@'
'CYCLE STEAL STATUS: '
CSS+2,11,MODE=HEX
'@'
S1S1,BUFFER=BUF
2F'O'
12F'O'
F'O'
F' -1 '
D'O'
F'O'
F'O'
4096,BYTES,INDEX=BUFI
D'O'
S1S1 HEADER BUFFER
JUMPER + CYCLE
STEAL STATUS
S1S1 STATUS
READ/WRITE TYPE
SYNC COUNTER
MESSAGE SWITCH
ABORT SWITCH
DWORD CONSTANT
Figure 71 (Part 4 of 4). Secondary Processor Sample Program
o
Chapter 5. Series/l-to-Series/l Attachment Support
CO-191
Series/1-to-Series/1 Attachment Support
Programming for Series/1-to-Series/1 Attachment (continued)
Synchronization Program (SYNC)
o
The synchronization program shows a way to synchronize operations between two processors.
Neither processor begins communicating until some external event sets FLAG. When FLAG is
set, the program responds as follows:
•
•
•
•
FLAG = 0 indicates no external event.
FLAG = 1 indicates write to other processor.
FLAG = 2 indicates read from other processor.
FLAG = 3 is the termination indicator.
This program runs on both processors.
SYNC
*
F1
F2
END
A
A1
*
PROGRAM
A
ATTNLIST
MOVE
ENDATTN
MOVE
ENDATTN
MOVE
ENDATTN
MOVE
ENQT
TERMCTRL
DEQT
IF
STIMER
IF
(WR,F1,RD,F2,EN,END)
FLAG, 1
EXTERNAL EVENT= WRITE
FLAG, 2
EXTERNAL EVENT=READ
FLAG, 3
EXTERNAL EVENT=STOP PGM
BUFX,1024
S1S1
STATUS,HBUF,WAIT=NO
SET BUFFER FOR WRITES
GET THE S1S1
OBTAIN S1S1 STATUS
(HBUF+2,EQ,O)
5000,WAIT
(FLAG,EQ,O)
IF NO ACTION YET
WAIT 5 SECONDS
EXTERNAL EVENT NOT
OCCURRED YET
rf· \
\',-)
DEQT
PRINTEXT '@NOTHING HAS OCCURRED YET IN 5 SECONDS@'
GO TO
A1
ENDIF
IF
(FLAG,EQ,3),GOTO,STOP
EXTERNAL EVENT
TERMINAT
IF
FLAG,EQ,1
EXTERNAL EVENT
WRITE
DEQT
PRINTEXT '@WRITING TO OTHER CPU@'
ENQT
S1S1
GET S1S1
WRITE TO OTHER CPU
PRINTEXT BUF,XLATE=NO
DEQT
MOVE
FLAG,O
CLEAR FLAG TO IDLE
GOTO
A1
CONTINUE
ENDIF
Figure 72 (Part 1 of 2). Synchronization Sample Program
o
CO-192
SC34-0638
()
Programming for Series/1-to-Series/1 Attachment (continued)
*
STOP
S1S1
BUF
FLAG
TEMP
HBUF
EXTERNAL EVENT
READ
IF
FLAG,EQ,2
DEQT
PRINTEXT '@READING FROM OTHER CPU@'
S1S1
ENQT
GET 81S1
READTEXT BUF,XLATE=NO
READ FROM OTHER CPU
DEQT
CLEAR FLAG TO IDLE
MOVE
FLAG, 0
A1
CONTINUE
GOTO
ENDIF
ELSE
SEE IF READ OR
SHIFTL
HBUF,2,1,RESULT=TEMP
WRITE REQUEST
IT DID A WRITE
IF
TEMP,LT,O
DEQT
PRINTEXT '@READING WHAT IT SAID@'
S1S1
ENQT
READTEXT BUF,XLATE=NO
READ WHAT IT WROTE
DEQT
CONTINUE
GOTO
A1
ELSE
DEQT
PRINTEXT '@WRITING WHAT IT SAID@'
ENQT
S1S1
WRITE WHAT IT WROTE
PRINTEXT BUF,XLATE=NO
DEQT
CONTINUE
GOTO
A1
ENDIF
ENDIF
GOTO
A1
CONTINUE
PROGSTOP
END THE PROGRAM
IOCB
S1S1,BUFFER=BUF
BUFFER
1024,BYTE,INDEX=BUFX
DATA BUFFER
F'O'
DATA
EXTERNAL EVENT FLAG
F'O'
DATA
2F'O'
DATA
S1S1 HEADER
ENDPROG
END
Figure 72 (Part 2 of 2). Synchronization Sample Program
o
Chapter 5. Series/l-to-Series/l Attachment Support
CO-193
Series/1-to-Series/1 Attachment Support
Interacting with the 8eries/1-to-8eries/1 Attachment (Using $8181 UT1)
The $SISI UTI utility allows you to perform several functions on the other processor. These
include remote IPL, data transfers and status operations. The utility also verifies that the
attachment is installed correctly, and checks out an application program. You must always
specify the identity of the other Series/l the $SISI UTI commands:
o
AB - Abort
•
DD - Define device name
•
IP - IPL the other processor
•
RE - Read data
•
RS - Reset device
•
WR - Write data
•
EN - End the program
EC - Verify the Series/l - Series/l attachment
•
ST - Obtain status.
You must have both attached processors actively communicating with the RE (read), WR
(write), and AB (abort) commands. For example, if you issue a WR command on one
processor, then you must issues a corresponding RE command on the other processor.
(1«-- ' ;
1,'<11,
_)
...... ~-'
When you load $SISI UTI, it immediately issues a DD command to obtain the ID of the
Series/l that loaded it.
Invoking $S1 S1 UT1
You invoke the $SISIUTI utility with the $L operator command or option 4.8 of the session
manager. $SIS1UTI must be active on two connected processors for processor-to-processor
communication via the RE (read), WR (write), and AB (abort) commands. For example, if you
issue a WR command on one processor, then you must issue a corresponding RE command on
the other processor.
Aborting an Operation (AB)
The ..AJ3 command causes the other processor to abort a pending operation on the initiating
processor. The AB command is sent to the Series/l specified in the most recent DD command.
This command abnormally ends a data transfer operation.
o
CO-194
SC34-0638
o
Interacting with the Series/1-to-Series/1 Attachment (Using
$S1 S1 UT1) (continued)
Example: AB command
COMMAND(?): AB
ABORT OPERATION?
Y
COMMAND(?):
Specifying the Other Processor (DO)
For every function you perform with $SlSlUTl, you must identify the other Series/l. The
specified processor receives all the issued subsequent utility commands until another DD is
issued. The Series/l name is the name specified on the TERMINAL configuration statement at
system generation.
Example: DD command
COMMAND(?): DD
5151 DEVICE NAME:
515100
COMMAND(?):
c
Verifying the Series/1-to-Series/1 Attachment (Ee)
The EC command verifies that the attachment is installed correctly. It results in a continuous
exchange of l024-byte records between the attached processors. To terminate EC, press the
attention key and enter EC.
Example: EC command
COMMAND(?): EC
ECHO EXERCISE
ATTN.." EC~ TO STOP ECHO TEST
ATTEMPTtNG TO SYNCH UP
lK DATA TRANSMITTED
lK DATA RECEIVED
DATA CHECKS OUT!
(Attention)
>
EC
COMMAND(?):
o
Chapter 5. Series/l-to-Series/l Attachment Support
CO-195
Series/1-to-Series/1 Attachment Support
Interacting with the 5eries/1-to-5eries/1 Attachment (Using
$5151 UT1) (continued)
(J
"'\.
'
IPL the Other Processor UP)
You can issue the IP command only if your Series/I is the primary. It issues an IPL (initial
program load) command to the secondary processor. You must supply the member name and
volume that contains the nucleus to be transferred to the secondary.
The nucleus being transferred must begin with the characters $EDXNUC. The IPL bootstrap
program, IPLS I SI, must be located in the IPL volume; you are prompted to verify that the
volume name specified is correct. You are also asked if the secondary has a disk or diskette
device and for the address of that device. The specified disk or diskette becomes the default
direct access device for disk I/O operations on the processor being initialized. The bootstrap
program is sent to the secondary and it reads the specified nucleus, 1024 bytes at a time, across
the attachment. Control is passed to the nucleus upon completion of the transfer.
Example: IP command
COMMAND (?):
IP
ENTER NUCLEUS DSN:
$EDXNUC
ENTER NULCEUS VOLUME: EDX002
IS THERE A DEFAULT DISK DEVICE FOR THE NUCLEUS? Y
SUPPLY DISK/DISKETTE DEVICE ADDRESS(HEX): 48
IPL PROGRAM NAME: IPLS1Sl ON VOLUME: EDX002
OK? Y
READY FOR lPL? Y
Reading Data from the Other Processor (RE)
The RE command issues an ENQT instruction for the terminal name specified by the most
recent DD command. $SISI UTI then issues a READ TEXT instruction for that terminal to
read data from the other processor. If $SISIUTI is active on the other processor, a WR
command must be issued to complete an RE command.
Example: RE command
COMMAND ( ? ) : RE
MESSAGE RECEIVED!
I
--'•.j
T_H._I_S__
IS_'_(?)
TE_S._T
DA_T_A_R_E_C_E_IV_E_D_________________________________________
_COMMAND
: __
_
o
CO-196
SC34-0638
o
Interacting with the Series/1-to-Series/1 Attachment (Using
$S1S1UT1) (continued)
Resetting Device (RS)
The RS command resets the to the Series/l attachment specified by the most recent DD
command. This command clears any pending interrupt or busy condition.
Example: RS command
COMMAND(?}: RS
RESET ATTACHMENT?
Y
COMMAND(?}:
Obtaining Status of an Operation (ST)
The ST command obtains status information on an operation. The status returned by this
command is the same as the information returned when a TERMCTRL STATUS instruction is
issued.
Example: ST command
o
COMMAND(?}: ST
OBTAIN CYCLE STEAL STATUS ALSO? Y
WAIT FOR HEADER? N
HEADER WORDS: 1100 0400
READ(READTEXT} ISSUED BY OTHER CPU
NO. BYTES = 0400
DIAGNOSTIC JUMPER WORD: 02E6
CYCLE STEAL STATUS:
(11 words of status)
COMMAND(?):
o
Chapter 5. Series/l-to-Series/l Attachment Support
CO-197
Series/1-to-Series/1 Attachment Support
Interacting with the Series/1-to-Series/1 Attachment (Using
$S1S1UT1) (continued)
o
Writing Data to the Other Processor (WR)
The WR command issues an ENQT instruction to the Series/l specified by the most recent DD
command. A PRINTEXT instruction is then issued for that terminal to write data to the other
processor. If $SISI UTI is active on the other processor, an RE command must be issued to
complete a WR command.
Example: WR command
COMMAND (? ) : WR
ENTER TEXT:
TEST DATA TO WRITE
MESSAGE SENT!
COMMAND(?):
Ending the Utility (EN)
The EN command ends the $SIS1 UTI utility.
Example: EN command
COMMAND ( 1 ) :
EN
$SlS1UTl ENDED AT 00:00:00
o
CO-198
SC34-0638
o
Chapter 6. General Purpose Interface Bus - IEEE
Standard 488-1975
The General Purpose Interface Bus (GPIB) Adapter, when connected to the Series/I, allows it
to communicate with up to 14 peripheral devices. The devices that GPIB can connect to the
Series/l include printers, plotters, graphics display units, and programmable laboratory
equipment such as digital voltmeters, frequency analyzers, and signal generators.
The connection between the Series/l and the GPIB devices is much like a multipoint
connection. The Series/l acts as the control station, and the GPIB devices as its tributaries.
You must write application programs to control communications between the Series/l and the
GPIB devices. Your program must perform polling and selection, and initiate all data transfer
operations.
Planning for the G PI B Application
System Generation for GPIB
During system generation for the Series/I, you must include a TERMINAL statement in the
configuration module ($EDXDEF) for each GPIB adapter. Also, you must include the GPIB
device handler (IOSGPIB) in the supervisor link control data set ($LNKCNTL). Refer to the
Installation and System Generation Guide for additional information on system generation.
o
Chapter 6. General Purpose Interface Bus - IEEE Standard 488-1975
CO-199
General Purpose Interface Bus - IEEE Standard 488-1975
Planning for the GPIB Application (continued)
You may want to connect GPIB to a particular partition so that SRQ interrupts adapter can be
properly handled. The partition to which the GPIB adapter is initially connected is defined by
the PART parameter of the TERMINAL statement. To modify the size of the system buffer
generated for the GPIB adapter, use the LINSIZE parameter.
o
The following TERMINAL statement connects a GPIB adapter named GPIB to partition 2 and
defines the system buffer to be 200 bytes in length.
GPIB
TERMINAL DEVICE=GPIB,ADDRESS=32,LINSIZE=200,PART=2
Relationship between Series/1 and GPIB Devices
The Series/ 1 always acts as the control station and the GPIB devices act as its tributary stations.
A GPIB device can function in two roles:
As a talker, a device is sending data to the Series/ 1 or to another device.
•
As a listener, a device is receiving data from the Series/ 1 or another device.
The Series/l controls communications so that only one device is talking at a time. However,
any number of devices can be listening at the same time. The devices can function in either role.
A device can act as talker during one data transfer, and as listener during another transfer. The
Series/ 1 tells the devices which role to assume during each transfer operation.
The Series/ 1 must make the assignments of talker and listener(s) before a data transfer
operation occurs. For example, to send data to a device, the Series/l designates itself as the
talker and the receiving device as the listener. The Series/l then sends the data. To read the
response from the device, the Series/l designates the device as talker, and itself as listener. The
Series/ 1 then reads the data.
Assigning Device Addresses
Each device on a GPIB bus has two addresses: one identifies the device as a listener and the
other identifies it as a talker. Each listen address has a corresponding talk address, and vice
versa. For example, if a device listens at address C'3', it talks at address C'S'.
The chart below shows the sets of listen and talk addresses; they are ASCII characters.
Although GPIB device addresses are usually expressed as ASCII characters, they can also be
coded in hexadecimal.
The Series/llisten and talk addresses are C'5' and C'U' respectively; they cannot be changed.
o
CO-200
SC34-0638
o
Planning for the GPIB Application (continued)
Listen
Address
(space)
!
&sqd.
#
$
Talk
Address
@
A
B
C
D
%
&
E
F
G
H
I
*
J
K
+
L
M
N
/
P
1
Q
2
3
4
C\
o
0
5
6
7
8
9
/
<
>
R
S
T
U
V
W
X
y
Z
[
\
]
(caret)
Figure 73. Listen and Talk Addresses for GPm Devices
Initializing and Configuring the Bus
You must initialize and configure the bus before the Series/land the GPIB device can
communicate. These functions are performed by the TERMCTRL instruction, as described in
the Programming section. The initialization consists of these operations:
1. Reset the adapter.
2. Clear the interface between Series/l and GPIB; this makes the entire bus inactive.
3. Perform remote enable of GPIB; this enables all the devices attached to the bus.
Code these operations at the beginning of your application program. Unless an error oCGurs,
you do not have to repeat the initialization.
o
Chapter 6. General Purpose Interface Bus - IEEE Standard 488-1975
CO-201
General Purpose Interface Bus - IEEE Standard 488-1975
Planning for the GPIB Application (continued)
Configuring the bus consists of assigning the roles of talker and listener(s) for the tasks in a
program. It also allows the Series/Ito send data to listening devices.
Interrupt Handling
A service request (SRQ) is a device-generated signal that informs the controller (Series/I) that
the device needs service. A program can be notified of the occurrence of an SRQ by coding a
$PF255 reference in an attention list (ATTNLIST), with SCOPE=GLOBAL specified. Since
the attention list receives control enqueued to the terminal, the main task (which is enqueued to
GPIB) .1Jlust issue a DEQT to GPIB. The following example shows an event control block
(ECB) being posted when an SRQ occurs.
ATTNLIST ($PF255,GOTSRQ) ,SCOPE=GLOBAL
* ATTENTION LIST
* WHEN AN SRQ IS
*
GOTSRQ
EQU
TASK THAT RECEIVES CONTROL
RECEIVED.
POST
ENDATTN
*
*
*
*
*
SRQECB
POST SRQ OCCURRENCE
END ATTENTION PROCESSING
MAIN TASK
AT THIS POINT, INSTRUCTIONS HAVE BEEN ISSUED THAT
CAUSE A GPIB DEVICE TO ISSUE AN SRQ.
DEQT
WAIT
*
SRQECB
ECB
SRQECB
DISCONNECT FROM GPIB
PROGRAM WAITS FOR EVENT
INDICATING SRQ OCCURRENCE
SRQ EVENT CONTROL BLOCK
Note: A program that uses an attention list to receive SRQ interrupts in this manner must run in
the partition to which the GPIB terminal is connected. This is initially defined at system
generation time; but can be changed using the change partition (CP) command of $GPIBUTl.
A program can also handle an SRQ interrupt via the WAIT KEY instruction. The program
remains in a wait state until an SRQ interrupt is received by the Series/I. However, as for all
WAIT KEY instructions, an interrupt that occurs before the WAIT KEY is executed will be lost.
An SRQ does not identify the interrupting device. To determine this, the application program
must poll all devices connected to the bus; see "Polling the Devices" on page CO-209.
o
CO-202
SC34-0638
o
Programming for the GPIB Application
You must write programs that allow communication between Series/land the GPIB devices.
Your program must perform the following tasks:
•
Initialize and configure the bus
•
Control data transfer operations
•
Poll and select devices
•
Send data to devices
•
Receive data from devices
•
Perform control functions on devices.
Your programs must consist of Event Driven Language instructions. The instructions that apply
specifically to the GPIB application are discussed in the next section.
Event Driven Language Instruction Set
Your program must contain the following EDL instructions, which perform the task of
communicating between the Series/land the GPIB devices.
o
Instruction
DEQT
Function
Releases the device that Series /1 is
communicating with
ENQT
Gives Series/1 exclusive right to
communicate with a device
IOCB
Identifies the particular GPIB adapter
that connects the device Series/1
wants to communicate with
PRINTEXT
Sends data to a device
READTEXT
Receives data from a device
TERMCTRL
Performs control functions on a
device
For description and syntax of the instructions refer to the Language Reference.
o
Chapter 6. General Purpose Interface Bus - IEEE Standard 488-1975
CO-203
General Purpose Interface Bus - IEEE Standard 488-1975
Programming for the GPIB Application (continued)
Programming Considerations
o
Certain requirements and restrictions apply to programming for the GPIB application.
Performing Control Function (Using TERMCTRL)
Use only the TERMCTRL operands specific to GPIB. These are described in the Language
Reference.
Forcing Output of Data
You must "force" the output of data to a GPIB device. If the Series/ I issues a PRINTEXT
instruction to send data to a device, the program must force the output by one of several
methods:
Include the new line character (@) in the output. Do not use this method when coding
MODE=LINE or XLATE=NO parameters.
•
Code the XLATE=NO parameter.
•
Specify SKIP = I on a PRINT EXT instruction.
•
Issue a TERMCTRL DISPLAY instruction.
Specifying Translation of Data
If you want to send or receive hexadecimal data (when issuing the PRINTEXT or READTEXT
instructions) you must suppress translation of the data. The Series/I uses EBCDIC s the GPIB
Adaptor uses ASCII, and the GPIB devices use the code specific to each device type. To
suppress translation of data, code the XLATE=NO parameter for PRINT EXT or READTEXT.
If you want to send or receive data in EBCDIC for Series/I, ASCII for GPIB, or the code
appropriate to a device, code XLATE= YES. Use of XLATE=NO with PRINTEXT forces
output of data.
Specifying a User Buffer
If an application is to transfer more data than will fit in the system buffer (defined at system
generation), the IOCB through which the application is enqueued must specify a user buffer. A
user buffer is necessary if you want to specify the exact number of characters for a read.
In the following example) the IOCB (GPIBIOCB) specifies a BUFFER operand; the buffer
length is 500 bytes. If a buffer is used, you are responsible for setting the buffer iength
(GPIBLEN in this example) to the number of bytes to be written via PRINTEXT. The buffer
length is set to the number of bytes actually read by a READTEXT instruction. The example
below shows how the buffer can be initialized for a PRINTEXT of IOO bytes.
C)
,,I
CO-204
SC34-0638
o
Programming for the GPIB Application (continued)
ENQT
GPIBIOCB
CONNECT TO GPIB
DEQT
GPIBIOCB IOCB
GPIBBUFF BUFFER
MOVE
DISCONNECT FROM GPIB
GPIB,BUFFER=GPIBUFF
500,BYTES,INDEX=GPIBLEN
GPIB TERMINAL NAME
BUFFER FOR GPIB USE
GPIBLEN,100
If a user buffer is not desired, do not include the BUFFER parameter in the IOCB statement.
Initializing and Configuring the Bus
The TERMCTRL instruction provides operations that are used to initialize the bus: adapter
reset (RSET), interface clear (IFC), and remote enable (REN). Normally these three
operations are performed when a GPIB program starts, and need not be executed again unless
an error occurs. When used at the start of a GPIB program, these control operations should be
executed in the order discussed.
The RSET operation resets the adapter.
TERMCTRL GPIB,RSET
RESET ADAPTER
The IFC operation clears the GPIB interface, thus causing the entire bus to be made inactive.
TERMCTRL GPIB,IFC
INTERFACE CLEAR
The remote enable (REN) operation enables all the devices on the bus. Not all devices need to
be enabled in this manner; some are initialized to an enabled state. Check the manufacturer's
device description to see whether a remote enable is needed.
o
Chapter 6. General Purpose Interface Bus - IEEE Standard 488-1975
CO-205
General Purpose Interface Bus - IEEE Standard 488-1975
Programming for the GPIB Application
(co. tinued)
TERMCTRL GPIB,REN
PRINTEXT LISTADDR
TERMCTRL DISPLAY
LISTADDR TEXT
o
REMOTE ENABLE
SEND LISTENER ADDRESS
FORCE OUTPUT
LISTEN ADDRESS FOR ONE DEVICE
'% '
Configuring the Bus
The configure bus (CON) operation of the TERMCTRL instruction does two things: it assigns
the roles of talker and listener, and it can be used to write data to listeners.
In the following examples, the universal unlisten command (a question mark) is transmitted first,
followed by a talker address, and then by the list of listener addresses. The unlisten command is
a special message that resets all devices that were listeners to a nonlistening state.
Series/1 talks, and some device(s)
TERMCTRL
PRINTEXT
PRINTEXT
PRINTEXT
PRINTEXT
TERMCTRL
GPIB,CON
I?'
'u'
LISTADDR
'''.'
DISPLAY
LISTADDR TEXT '%'
listens:
CONFIGURE BUS
UNIVERSAL UNLISTEN COMMAND
SERIES/1 TALK ADDRESS
DEVICE LISTENER ADDRESS(ES)
DATA BLOCK TERMINATOR
FORCE OUTPUT
LISTEN ADDRESS
Series/1 sends data via CON:
TERMCTRL
PRINTEXT
PRINTEXT
PRINTEXT
PRINTEXT
PRINTEXT
TERMCTRL
GPIB,CON
'?U'
LISTADDR
'" , ,
DATA
, " :' \
DISPLAY
LISTADDR TEXT '%'
CONFIGURE BUS
(AS ABOVE)
DEVICE LISTENER ADDRESS (ES)
DATA SEPARATOR
SEND DEVICE DATA
DATA BLOCK TERMINATOR
FORCE OUTPUT
LISTEN ADDRESS
o
CO-206
SC34-0638
o
Programming for the GPIB Application (continued)
Some device talks, and Series/1 listens:
TERMCTRL
PRINTEXT
PRINTEXT
PRINTEXT
PRINTEXT
TERMCTRL
GPIB,CON
I?I
TALKADDR
151
I ": I
DISPLAY
TALKADDR TEXT lEI
CONFIGURE BUS
UNIVERSAL UNLISTEN COMMAND
DEVICE TALK ADDRESS
SERIES/1 LISTENER ADDRESS
DATA BLOCK TERMINATOR
FORCE OUTPUT
TALK ADDRESS
One device talks, and other device(s) listens:
TERMCTRL
PRINTEXT
PRINTEXT
PRINTEXT
PRINTEXT
TERMCTRL
c
GPIB,CON
I? I
TALKADDR
LISTADDR
I ": I
DISPLAY
LISTADDR TEXT 1%1
TALKADDR TEXT lEI
CONFIGURE BUS
UNIVERSAL UNLISTEN COMMAND
DEVICE TALK ADDRESS
OTHER LISTENER ADDRESS (ES)
DATA BLOCK TERMINATOR
FORCE OUTPUT
LISTEN ADDRESS
TALK ADDRESS
Enqueuing and Oequeuing GPIB
The ENQT instruction connects Series/1 to a GPIB adapter and excludes other sources from
accessing the adapter at the same time. You must specify the GPIB adapter that the Series/1
wants to communicate with. To do this, refer to the label of the IOCB instruction that identifies
the GPIB adapter.
The DEQT instruction releases the GPIB adapter previously enqueued.
If your program is connected to a GPIB adapter and issues a a LOAD instruction, the task
issuing the LOAD will be disconnected from the GPIB adapter, and the task being loaded will
be connected to the GPIB adapter. If this is not desirable, the program issuing the LOAD must
first issue a DEQT, followed by the LOAD, and then issue an ENQT to reconnect to the GPIB
adapter.
In the following example, the IOCB (GPIBIOCB) is initially enqueued. Next, the program
issues a DEQT to disconnect itself from the GPIB adapter. The program then issues a LOAD
instruction for the program NEWPROG, which now has the GPIB adapter connected to it.
After NEWPROG completes, the program reconnects to the GPIB adapter by issuing another
ENQT.
o
Chapter 6. General Purpose Interface Bus - IEEE Standard 488-1975
CO-207
General Purpose Interface Bus - IEEE Standard 488-1975
o
Programming for the GPIB Application (continued)
ENQT
GPIBIOCB
CONNECT TO GPIB
DEQT
LOAD
ENQT
NEWPROG
GPIBIOCB
DISCONNECT FROM GPIB
LOAD NEW PROGRAM
RECONNECT TO GPIB
GPIBIOCB IOCB
GPIB
Series/1 Sending Data to a Device
The Series/1 acts as talker and transmits data to the listener(s) with a PRINTEXT instruction.
The data actually goes to the GPIB adapter which in turn directs it to the designated device(s).
The following example shows what to code for Series/1 to send data to a device.
Example of writing character data:
TERMCTRL GPIB,WRIT
PRINTEXT DATA
TERMCTRL DISPLAY
DATA
TEXT
'IN; ,
WRITE TO GPIB
SEND DATA
FORCE OUTPUT
DEVICE DEPENDENT DATA
Example of writing hex data:
(note the simulated TEXT statement)
TERMCTRL GPIB,WRIT
PRINTEXT HEXDATA,XLATE=NO
TERMCTRL DISPLAY
WRITE TO GPIB
SEND HEX DATA
FORCE OUTPUT
\
DATA
HEXDATA
DATA
X'OiOi
X'03'
I
TEXT LENGTH/COUNT
DEVICE DEPENDENT DATA
Series/1 Receiving Data from a Device
Series/1 receives data transfers from GPIB devices with a READTEXT instruction.
This example shows how the Series/1 receives data being sent by a device. It is assumed that
the device appends an end-of-string character to the data to be sent. Since the device can send
o
CO-208
SC34-0638
o
Programming for the GPIB Application (continued)
a variable number of characters, the SE option is used in the READTEXT instruction to
suppress incorrect length record exceptions.
TERMCTRL GPIB,READ, (SE,EOS) ,X'OD'
READTEXT DATA
READ GPIB
READ INPUT DATA
Sending Data Between Devices
One device can send data to one or more other devices while the Series/1 merely monitors the
data transfer. This is done with the READTEXT instruction. The following example shows
how Series/1 allows the data transfer between the devices.
TERMCTRL GPIB,MON,(SE,EOS),X'OD'
READTEXT DATA
READ MONITOR
DUMMY READ
Polling the Devices
Your program can perform either a serial or parallel polling operation to determine the source of
a device interrupt. The TERMCTRL instruction performs polling.
Serial Polling Code these TERMCTRL instructions to perform serial polling (polling devices
in sequence):
•
TERMCTRL SPE (enable serial poll)
•
TERMCTRL SPL (read serial poll)
•
TERMCTRL SPD (disable serial poll).
The SPE command polls each device whose talker address has been specified. The SPL
command reads the poll status of each device. The poll status returned for each device consists
of two bytes: the talker address of the polled device (first byte) and the device status (second
byte). The status byte is device-dependent, and is usually expressed in hex. If it is, use
XLATE=NO on the appropriate READTEXT. The SPD command disables the serial poll
status reporting ability of the devices previously enabled through an SPE command.
TERMCTRL
PRINTEXT
TERMCTRL
TERMCTRL
READTEXT
TERMCTRL
GPIB,SPE
TALKADDR
DISPLAY
GPIB,SPL
STATUS,XLATE=NO
GPIB,SPD
SERIAL POLL ENABLE
TALK ADDRESS OF DEVICE
FORCE OUTPUT
READ SERIAL POLL
GET SERIAL POLL STATUS
SERIAL POLL DISABLE
"~I
'-I'
Chapter 6. General Purpose Interface Bus - IEEE Standard 488-1975
CO-209
General Purpose Interface Bus - IEEE Standard 488-1975
Programming for the GPIB Application (continued)
o
Parallel Polling: A parallel poll polls all enabled devices in parallel, with the poll status
encoded as a single byte. Device response to parallel polling is highly device-dependent; many
devices do not even acknowledge parallel polling.
Code the following TERMCTRL instructions to perform parallel polling:
TERMCTRL PPE (enable parallel poll)
TERMCTRL WPPL (write parallel poll command)
TERMCTRL RPPL (read parallel poll status)
•
TERMCTRL PPD (disable parallel poll)
TERMCTRL PPU (unconfigure parallel poll).
The PPE command enables the devices to respond to a parallel poll. You must supply two bytes
of information for each device to be polled. The first byte specifies the listener address. The
first four bits of the second byte have, by definition, the value of six. The fifth bit is the line
level (one or zero) which is the active level for the addressed device. The final three bits
indicate which GPIB data line is used to request service. Bit values zero through seven are used
to specify GPIB data lines one through eight.
Note: Some devices that respond to parallel polling may respond to a poll only in predefined
ways. Consult your device manual.
Since a parallel poll word is most conveniently expressed in numeric form, PRINTEXT with
XLATE=NO should be used. A TEXT statement must be simulated so that hex data can be
used. In the following example, the TEXT statement is simulated by the first DATA statement
containing the value X'0202'. This value corresponds to the length and count bytes of a TEXT
statement followed by another DATA statement that contains the two bytes of polling
information. In the example, a single device at listener address X'2S' is enabled to respond at
line level one on GPIB data line one.
TERMCTRL GPIB,PPE
PRINTEXT PPEMSG,XLATE=NO
PPEMSG
DATA
DATA
X'0202'
X'2568'
PARALLEL POLL ENABLE
SEND DATA
TEXT PARAMETERS
The actual polling of the devices is accomplished by a write parallel poll command (WPPL).
The resulting poll status byte is stored in the adapter until a read parallel poll status (RPPL) is
performed. The RPPL operation moves the status byte into the byte specified on the
TERMCTRL GPIB,RPPL statement.
o
CO-210
SC34-0638
o
Programming for the GPIB Application (continued)
TERMCTRL GPIB,WPPL
TERMCTRL GPIB,RPPL"RPPLDATA
RPPLDATA DATA
X'OO'
\
WRITE PARALLEL POLL STATUS
READ PARALLEL POLL STATUS
PARALLEL POLL STATUS BYTE
One device or all devices configured to respond to parallel polling can be unconfigured using the
parallel poll disable (PPD) or parallel poll unconfigure (PPU) command.
TERMCTRL GPIB,PPD
PRINTEXT LISTADDR
TERMCTRL DISPLAY
PARALLEL POLL DISABLE
LISTENER ADDRESS (ES)
FORCE OUTPUT
or
TERMCTRL GPIB,PPU
PARALLEL POLL UNCONFIGURE
Assigning Device Mode of Operation
0'
"
Local Mode Operation: Some GPIB devices can be operated by an attached panel as well as
via GPIB bus commands; this is called local mode operation. A device with this capability can
be enabled to operate in local mode by the go to local mode TERMCTRL GTL command.
Similarly, local mode can be disabled by the local lock out TERMCTRL LLO command. Both
of these commands must specify the listener addresses of the devices to be operated in this
mode.
TERMCTRL GPIB,GTL
PRINTEXT LISTADDR
TERMCTRL DISPLAY
GO TO LOCAL
LISTENER ADDRESS (ES)
FORCE OUTPUT
TERMCTRL GPIB,LLO
PRINTEXT LISTADDR
TERMCTRL DISPLAY
LOCAL LOCK OUT
LISTENER ADDRESS(ES)
FORCE OUTPUT
Device Group Operation: Some devices can have predefined operations which are executed
by a trigger command. These operations can be initiated by a group execute trigger
TERMCTRL GET command which must specify a list of listener addresses for the devices.
o
Chapter 6. General Purpose Interface Bus - IEEE Standard 488-1975
CO-211
General Purpose Interface Bus - IEEE Standard 488-1975
Programming for the GPIB Application (continued)
TERMCTRL GPIB,GET
PRINTEXT LISTADDR
TERMCTRL DISPLAY
o
GROUP EXECUTE TRIGGER
LIS~ENER ADDRESS (ES)
FORCE OUTPUT
Coding GPIB Functions
These coding examples demonstrate the steps necessary to communicate with a device
connected to the GPIB bus. In this sample case, the GPIB device is a plotter. Therefore, some
operations unique to the plotter are covered.
Following this section is a sample program that contains the coding segments shown below. In
the coding segments, the following plotter commands are used:
IN
PAx,y
OC
1M
Initialize plotter
Move pen to absolute position at x,y coordinates
Output current pen position
Initialize masks
Connecting to the GPIB Adapter
The program must first connect to the GPIB adapter with an ENQT instruction.
ENQT
GPIBIOCB IOCB
GPIBIOCB
CONNECT TO GPIB
GPIB
IOCB FOR GPIB ADAPTER
Initializing the Adapter
The program initializes the adapter and bus by means of the RSET and IFC operations.
TERMCTRL
TERMCTRL
GPIB,RSET
GPIB,IFC
RESET ADAPTER
CLEAR BUS
Enabling the GPIB Device
The plotter is remotely enabled with a REN command followed by its listener address.
TERMCTRL
PRINTEXT
GPIB,REN
'%@'
REMOTE ENABLE
THE PLOTTER
o
CO-212
SC34-0638
o
Programming for the GPIB Application (continued)
Clearing All Devices
All devices are cleared by a device clear command.
TERMCTRL
GPIB,DCL
CLEAR ALL DEVICES
Preparing to Send Data
At this point, the bus is configured so that the Series/1 can send data to the plotter, that is, the
Series/1 is enabled to talk, and the plotter is enabled to listen. The coding for this consists of
the universal unlisten command (question mark), followed by the talker and listener addresses,
the data block terminator, and a new line character (@) to force output.
SENDCON
c
TERMCTRL
PRINTEXT
GPIB,CON
SENDCON
TEXT
'?U%":@'
CONFIGURE BUS
S/1 TALKS, PLOTTER LISTENS
Writing Data to the Device
The Series/1 writes data to the plotter by issuing a GPIB write command. Then a series of
plotter commands are sent. PRINTNUM is used to convert numeric data to character form.
F5000
CURRPOS
TERMCTRL
PRINT EXT
PRINT EXT
PRINTNUM
PRINT EXT
PRINTNUM
PRINT EXT
PRINT EXT
TERMCTRL
GPIB,WRIT,TO
'IN; ,
'PA'
F5000
, ,
DATA
TEXT
F'5000'
LENGTH=14
,
,., ,
F5000
'OC; ,
DISPLAY
WRITE, TIMER OVERRIDE
INITIALIZE PLOTTER
MOVE PEN ABSOLUTE
X=5000
SEPARATOR
Y=5000
TERMINATOR
OUTPUT CURRENT PEN POSITION
FORCE OUTPUT
Preparing to Receive Data
Since the Series/1 requested data from the plotter, it must reconfigure the bus so that the plotter
talks and the Series/1 listens.
o
Chapter 6. General Purpose Interface Bus - IEEE Standard 488-1975
CO-213
General Purpose Interface Bus - IEEE Standard 488-1975
Programming for the GPIB Application (continued)
RECVCON
TERMCTRL
PRINTEXT
GPIB,CON
RECVCON
TEXT
'?E5":@'
o
CONFIGURE BUS
PLOTTER TALKS, S/1 LISTENS
Receiving Data From the GPIB Device
The actual read is performed by a GPIB READ operation. Since a variable number of
characters can be sent, incorrect length record (ILR) exceptions are suppressed with the SE
option. The end of data is indicated by an end-of-string (EOS) character. At this point, the
input data can be tested or displayed.
TERMCTRL
-READTEXT
GPIB,READ,(SE,EOS,TO),X'OD'
CURRPOS
READ CURRENT POSITION
Preparing Device to Issue Service Request (SRQ) Interrupts
To show the use of service request (SRQ) interrupts, the plotter will issue an SRQ upon receipt
of an invalid plotter command. First, the bus must be configured again.
(tc
'\
1,\___ )
ENQT
TERMCTRL
PRINTEXT
GPIBIOCB
GPIB,CON
SENDCON
CONNECT TO GPIB
CONFIGURE THE BUS
S/1 TALKS, PLOTTER LISTENS
Then plotter commands can be transmitted which initialize the plotter to issue the SRQ when an
error occurs, and to cause an error.
TERMCTRL
PRINTEXT
PRINTEXT
PRINTEXT
PRINTEXT
DEQT
GPIB,WRIT,TO
'IN; ,
'IM223,32,O;'
'XX; ,
SKIP=1
WRITE, TIMER OVERRIDE
INITIALIZE PLOTTER
TO SEND SRQ UPON ERROR
SEND INVALID COMMAND
FORCE OUTPUT
DISCONNECT FROM GPIB
Receiving Device's SRQ Interrupt
At this point the plotter issues an SRQ interrupt. The following code receives the interrupt and
posts the event. The preceding DEQT was necessary, since the attention list task would wait
until the GPIB adapter was dequeued. Note that the ECB is initialized to the "event not
occurred" condition. (This code appears elsewhere in the actual program sequence.)
o
CO-214
SC34-0638
o
Programming for the GPIB Application (continued)
POSTSRQ
SRQECB
ATTNLIST
($PF255,POSTSRQ),SCOPE=GLOBAL
EQU
POST
ENDATTN
SRQECB
SPACE
ECB
SPACE
o
*
POST EVENT
The program waits for the SRQ event to occur, and then continues operation.
WAIT
RESET
SRQECB
SRQECB
WAIT FOR SRQ
RESET ECB
Retrieving Device Status
To retrieve the plotter status, the program serially polls the plotter with the serial poll enable
(SPE) and read serial poll (SPL) commands. The talker address for the plotter must be
specified with the SPE. The SPL is accompanied by a READTEXT with XLATE=NO, because
the plotter status is most easily handled in numeric form. Finally, a serial poll disable is issued to
prevent the plotter from talking with status information.
STATUS
ENQT
TERMCTRL
PRINTEXT
TERMCTRL
READTEXT
TERMCTRL
GPIBIOCB
GPIB,SPE
TEXT
LENGTH=2
'E@'
GPIB,SPL
STATUS,XLATE=NO
GPIB,SPD
CONNECT TO GPIB
SERIAL POLL ENABLE
PLOTTER TALKER ADDRESS
READ SERIAL POLL
READ STATUS
SERIAL POLL DISABLE
o
Chapter 6. General Purpose Interface Bus - IEEE Standard 488-1975
CO-215
General Purpose Interface Bus - IEEE Standard 488-1975
Programming for the GPIB Application (continued)
GPIB Sample Program
Figure 74 shows the preceding coding segments as a complete sample program. An error testing
routine is called after each 110 operation.
GPIBEG
PROGRAM
START
*
*
EQU
*
START
ENQT
TERMCTRL
CALL
TERMCTRL
CALL
TERMCTRL
PRINTEXT
CALL
TERMCTRL
CALL
GPIBIOCB
GPIB,RSET
ERRTEST
GPIB,IFC
ERRTEST
GPIB,REN
'%@ ,
ERRTEST
GPIB,DCL
ERRTEST
**
*
CONFIGURE BUS SO THAT S/1 TALKS AND THE PLOTTER LISTENS.
**
*
INITIALIZE THE PLOTTER.
**
*
MOVE THE PEN TO (5000,5000) .
TERMCTRL
PRINTEXT
CALL
TERMCTRL
PRINTEXT
PRINTEXT
PRINTNUM
PRINTEXT
PRINTNUM
PRINTEXT
GPIB,CON
SENDCON
ERRTEST
SC34-0638
CONFIGURE BUS
S/1 TALKS, PLOTTER LISTENS
CHECK FOR ERRORS
GPIB,WRIT,TO WRITE, TIMER OVERRIDE
'IN; ,
INITIALIZE PLOTTER
'PA'
F5000
,
,,
F5000
'., ,
Figure 74 (Part 1 of 4). GPIB Sample Program
CO-216
CONNECT TO GPIB
RESET ADAPTER
CHECK FOR ERRORS
CLEAR BUS
CHECK FOR ERRORS
REMOTE ENABLE
THE PLOTTER
CHECK FOR ERRORS
CLEAR ALL DEVICES
CHECK FOR ERRORS
MOVE PEN ABSOLUTE
X=5000
SEPARATOR
Y=5000
TERMINATOR
o
o
Programming for the GPIB Application (continued)
**
*
**
*
**
*
*
*
**
*
**
*
COMMAND THE PLOTTER TO SEND ITS CURRENT POSITION.
PRINT EXT
TERMCTRL
CALL
10C;
I
DISPLAY
ERRTEST
OUTPUT CURRENT POSITION
FORCE OUTPUT
CHECK FOR ERRORS
CONFIGURE THE BUS SO THE PLOTTER TALKS, AND S/1 LISTENS.
TERMCTRL
PRINTEXT
CALL
GPIB,CON
RECVCON
ERRTEST
CONFIGURE BUS
PLOTTER TALKS, S/1 LISTENS
CHECK FOR ERRORS
READ THE CURRENT POSITION OF THE PLOTTER.
(SPECIFY SUPPRESS EXCEPTION, TIMER OVERRIDE,
END OF STRING CHAR = X'OD '
TERMCTRL
READTEXT
CALL
GPIB,READ, (SE,EOS,TO) ,X'OD'
CURRPOS
READ CURRENT POSITION
CHECK FOR ERRORS
ERRTEST
DISPLAY CURRENT POSITION OF PLOTTER.
DEQT
PRINTEXT
PRINTEXT
PRINTEXT
EJECT
ENQT
DISCONNECT FROM GPIB
'@CURRENT PLOTTER POSITION = I
CURRPOS
DISPLAY CURRENT POSITION
SKIP=1
GPIBIOCB
CONNECT TO GPIB
CONFIGURE THE BUS SO THAT S/1 TALKS AND PLOTTER LISTENS.
TERMCTRL
PRINTEXT
CALL
GPIB,CON
SENDCON
ERRTEST
CONFIGURE THE BUS
S/1 TALKS, PLOTTER LISTENS
CHECK FOR ERRORS
Figure 74 (Part 2 of 4). GPIB Sample Program
o
Chapter 6. General Purpose Interface Bus - IEEE Standard 488-1975
CO-217
General Purpose Interface Bus - IEEE Standard 488-1975
Programming for the GPIB Application (continued)
**
*
INITIALIZE THE PLOTTER TO SEND AN SRQ UPON AN ERROR.
**
*
CAUSE A PLOTTER ERROR.
*
**
*
*
**
*
*
TERMCTRL GPIB,WRIT,TO
PRINTEXT- , IN; ,
PRINTEXT 'IM223,32,O;'
PRINTEXT
PRINTEXT
CALL
'XX; ,
SKIP=1
ERRTEST
o
WRITE, TIMER OVERRIDE
INITIALIZE PLOTTER
TO SEND SRQ UPON ERROR
SEND INVALID COMMAND
FORCE OUTPUT
CHECK FOR ERRORS
DISCONNECT FROM GPIB
DEQT
WAIT FOR THE SRQ, AND POLL THE PLOTTER TO GET ITS STATUS.
WAIT
RESET
ENQT
TERMCTRL
PRINTEXT
CALL
TERMCTRL
READTEXT
CALL
TERMCTRL
CALL
SRQECB
SRQECB
GPIBIOCB
GPIB,SPE
'E@'
ERRTEST
GPIB,SPL
STATUS,XLATE=NO
ERRTEST
GPIB,SPD
ERRTEST
WAIT FOR SRQ
RESET EVENT
CONNECT TO GPIB
SERIAL POLL ENABLE
PLOTTER TALKER ADDRESS
CHECK FOR ERRORS
READ SERIAL POLL
READ STATUS
CHECK FOR ERRORS
SERIAL POLL DISABLE
CHECK FOR ERRORS
DEQT
GPIBIOCB
DISCONNECT FROM GPIB
If)
('
',,"-
DISPLAY PLOTTER STATUS.
PRINTEXT
PRINTNUM
PRINTEXT
'@PLOTTER STATUS
STATUS,MODE=HEX
SKIP=1
=
I
DISPLAY STATUS
PROGSTOP
Figure 74 (Part 3 of 4). GPIB Sample Program
o
CO-218
SC34-0638
o
Programming for the GPIB Application (continued)
** THIS ATTENTION LIST TASK RECEIVES CONTROL WHEN
* AN SRQ INTERRUPT IS POSTED.
*
ATTNLIST
($PF255,POSTSRQ),SCOPE=GLOBAL
*
POSTSRQ EQU
*SRQECB
POST
POST EVENT
ENDATTN
**
SUBROUTINE TO CHECK FOR AND DISPLAY GPIB TERMINAL ERRORS.
*
*
*
*
TASKRC
0
GPIBIOCB
SRQECB
F5000
CURRPOS
STATUS
SUBROUT
MOVE
GET TASK RETURN CODE
TASKRC,GPIBEG
(TASKRC,NE,-1)
ERROR?
IF
DISCONNECT FROM GPIB
DEQT
PRINTEXT '@GPIB TERMINAL I/O ERROR ='
PRINTNUM TASKRC,MODE=HEX
PRINTEXT SKIP=1
PROGSTOP
ENDIF
RETURN
DATA
IOCB
ECB
DATA
TEXT
TEXT
** CONFIGURATION
*
SENDCON TEXT
RECVCON
*
ERRTEST
TEXT
F'O'
GPIB
0
F'5000'
LENGTH=14
LENGTH=2
IOCB FOR GPIB ADAPTER
SRQ EVENT
INFORMATION.
'?U%":@'
'?E5":@'
S/1 TALKS, PLOTTER LISTENS
PLOTTER TALKS, S/1 LISTENS
ENDPROG
END
Figure 74 (Part 4 of 4). GPIB Sample Program
o
Chapter 6. General Purpose Interface Bus - IEEE Standard 488-1975
CO-219
General Purpose Interface Bus - IEEE Standard 488-1975
Interacting with the GPIB Application (Using $GPIBUT1)
o
The $GPIBUTI utility enables you to interactively control and transfer data to and from GPIB
devices. This utility can also be used as a diagnostic tool to check out the application program
interface and the attached devices.
The $GPIBUTI commands are listed below. To obtain this list at your terminal, enter a
question mark in response to the prompting message, COMMAND(?):
COMMAND ( ? ) :
CH - DEFINE END CHARACTER
CP - CHANGE GPIB PARTITION
DO - DEFINE DEVICE
EN
- END THE PROGRAM
GP - GPIB CONTROL
LOeB - LI ST DEV I CE CONTROL BLOCK
RE
- READ DATA
RS -RESET I/O ADAPTER
ST - READ ERROR STATUS
SU - SUSPEND PROGRAM
WR - WRITE DATA
"ATTN - PGPIB.. TO POST
"ATTN - GPRESUME.. TO RESUME PROGRAM
COMMAND(?):
If a $GPIBUTI command fails, use the attention list command PGPIB to terminate the failing
operation. If the PGPIB command is used, you must issue an RS command (or RSET if GP
sub commands are used) to reset the adapter.
Defining End Character (CH)
The CH command defines or changes the ending character that is added to output data.
COMMAND(?}:
CHARACT~R
1
2
1
eH
TO BE APPENDED TO OUTPUT DATA
-~
NOW
IS
NONE
CARRIAGE RETURN
L tNE FEED
= END OF TEXT
=
==
4 = USERSPEC~FJED HEX BYTE
5= NONE
SELECT CODE:
3
END CHARACTER IS NOW ETX
COMMANDO):
()
CO-220
SC34-0638
o
Interacting with the GPIB Application (Using $GPIBUT1) (continued)
Changing GPIB Partition (CP)
The CP command changes the partition to which the GPIB adapter is connected. The partition
is initially defined at system generation.
COMMAND(?):
CP 2
PARTITION CHANGED TO 2
COMMAND (?) :
Cp
PARTITION NUMBER (NOW IS
2):
PARTITION NUMBER NOT CHANGED
COMMAND(7):
Defining Device (DO)
The DD command prompts for the name of the GPIB adapter. This name is specified in the
TERMINAL configuration statement. The name specified is used for all enqueues of the
adapter until another DD command is issued.
o
COMMAND(7):
DO
NEW GP I B TERM I NAL . NAME=- GP I B
COMMANO(?):
Ending The Program (EN)
The EN command ends the $GPIBUTI utility.
~~:_O_M_MA_N_.D_{_f)_;;~.. ~.~E*~.____~~....-~~~~~____~_____~__..-....-..______________,~
Controlling GPIB (GP)
The GP command enables you to enter the GPIB bus command options that can be specified on
the TERMCTRL instruction, as described in the Language Reference.
When GP is entered and followed by a bus command, $GPIBUTI prompts for additional data,
depending upon the specific command. For example, the CON (configure) command requires
both configuration and programming data. For the REN (remote enable) command, a list of
GPIB device addresses must be included.
o
Where appropriate, $GPIBUTI performs PRINTEXT /READTEXT operations as part of the
execution of a GP command, inserting delimiters as needed. In some cases, one delimiter is a
user-defined end character. The end character can be defined by the CH command.
Chapter 6. General Purpose Interface Bus - IEEE Standard 488-1975
CO-221
General Purpose Interface Bus - IEEE Standard 488-1975
o
Interacting with the GPIB Application (Using $GPIBUT1) (continued)
CONFIGURATION DATA:
GPIB 'COMMANO(?}:RtAD
O'TION(~E~EOS,TO,EOI):
OPTION(SE,EOS;TO,EOI):
EOSBYTE (HEX): 00
QPTION( 5E,EO$ ,TO,E,O I):
TRANSLATE INPUT1 Y
SE
WARNING
ros
EOBOR
EO~REQUIRED
.
.~.
WARNING -SE'MAY:BE NEEDED
(x '00 I).,
HOW MANY CHARACTERS (MAX=OEFAULT::80):
~,_:_;_:_:(_N_~_: _\_:_LT_E~ _T_O_
••• _M_.__________________________________________
~~
Listing Device Control Block (LOCB)
The LDCB command lists the contents of the current GPIB device control block (DCB). The
DCB describes the last GPIB operation performed. However, the information provided may
require that you use the GPIB Adapter manual. The items listed include:
•
Address of the GPIB terminal control block (CCB)
•
Address of the GPIB device control block (DCB)
•
Status of the DCB control word, specifically:
Cycle steal status key (that is, the address space of the data buffer)
GPIB operation mnemonic (for an undefined operation, '****')
()
CO-222
SC34-0638
()
Interacting with the GPIB Application (Using $GPIBUT1) (continued)
Status of the chaining, input, suppress exception (SE), end of string (EOS), timer
override (TO), and end of identify (EOI) bits, if they are set.
•
End of string character
•
Address of the residual status block (RSB)
•
Chain address
•
Byte count for the data transfer
•
Address of the data buffer
•
Contents of the data buffer, expressed as:
A string of hexadecimal words
EBCDIC characters
ASCII characters.
The DCB is checked for certain error conditions, including:
•
DCB words two or three not equal to zero
•
RSB address not equal to zero, and suppress exception set
•
Chain address nonzero and chaining bit set.
If the byte count is odd, the last byte in the string of hex words is not part of the buffer and
should be disregarded. Because the buffer data can be either EBCDIC or ASCII, depending on
the application, it is displayed in both character codes. In most cases, the ASCII data displayed
will be accurate. An inappropriate translation is displayed as a blank line.
The following example illustrates a DCB used in the execution of:
TERMCTRL GPIB,CON,TO
PRINTEXT '?U%":@'
()
Chapter 6. General Purpose Interface Bus - IEEE Standard 488-1975
CO-223
General Purpose Interface Bus - IEEE Standard 488-1975
Interacting with the GPIB Application (Using $GPIBUT1) (continued)
o
CONTROL WORD
,CYCLESTEAL~EYIS O·
TIMEROVERR ID.E SET
DEVICE OPERATION I scoN
BYTE 'COUNT IS
5
DATA ADDRESS IS 1102
DATAINHE:X FORMAT IS:
3F552522 2COO
DAtA JNTERPREtED AS EBCDIC IS:
'1U%'·:
COMMAND (1):
Reading Data (RE)
(11---',
The RE command reads data from the GPIB adapter. You can also specify GPIB options
(TERMCTRL functions), translation, and the number of characters to be read.
"'\,~o)
COMMAND~~):
READ
oPtrON(SE,EOS,TO,EOI) :
optlorHsE,EOS,TO,EOI ):
EO~BYTE(IiEXl:
,00
OPT I ON(SE,tOS ,TO, EO 1) ,,~
'TRANS,l",ATE 'rNPUT1Y'
SE
WARNING - EOS OREOI REQUIRED •••
EOS
WARN ING - SE MAY ,BE NEEDED
(X'on;')
HOW MANY CHARACTERS , (MAX=DEFAULT::80):
VALUE DEFAULTED TO 80
'
o
CPMMAND( 1):
----~~----------------~--~--~~~--~~--~~'~
RS - Resetting the GPIB Adapter (RS)
The RS command issues a device reset to the adapter. Any pending interrupt or busy condition
is cleared when this command is executed.
o
CO-224
SC34-0638
()
Interacting with the GPIB Application (Using $GPIBUT1) (continued)
COMMAND(?):
RS
RESET ADAPTER?
Y
COMMAND(?):
Reading Error Status (ST)
The ST command displays the status information contained in the adapter cycle steal status
words and the residual status block (RSB).
COMMAND(?):
ST
Y
READ STATUS?
CYCLE STEAL STATUS BLOCK (HEX)
o
RESIDUAL ADDRESS =
B45A
RESIDUAL BYTE COUNT =
0050
(RESERVED) =
0000
(RESERVED) =
0000
ERROR STATUS =
8000
BUS STATUS (AFTER POWER ON) = 0008
BUS STATUS (CURRENT) =
OOOA
SPE DEVICE ADDRESS =
0000
DCB SPECIFICATION CHECK =
0000
(RESERVED) =
0000
DCB ADDRESS =
1238
RESIDUAL STATUS BLOCK (HEX)
RESIDUAL BYTE COUNT
RSB FLAGS =
(RESERVED) =
(RESERVED) =
(RESERVED) =
RESET ADAPTER?
=
0000
0000
0000
0000
0000
Y
NO DATA RECEIVED
COMMAND (?):
Suspending $GPIBUT1 (SU)
The SU command suspends the operation of $GPIBUTI until you tell it to resume using
GPRESUME. This enables you to run $GPIBUTI concurrently with a GPIB application from
the same terminal.
COMMAND(?):
SU
$GPIBUTl SUSPENDED
Chapter 6. General Purpose Interface Bus -IEEE Standard 488-1975
CO-225
General Purpose Interface Bus - IEEE Standard 488-1975
Interacting with the GPIB Application (Using $GPIBUT1) (continued)
c
Writing Data (WR)
The WR command writes data to the GPIB adapter. You can specify GPIB options
(TERMCTRL functions) and translation.
COMMANDO) :WR
OPTIONlsE,EOS,TO,EOI}:
WRLTEHEX.DATA?
ENTER TEXT:
IS THE DATA OK?
COMMAND(?):
Y
WR
OPTION(SE,EOS,TO,EOI):
WRITE HEX DATA?
Y
ENTER . HEX. WORDS:
IS THE DATA OK?
OAOO .0102
Y
COMMAND{?):
o
Posting GPIB Operation Completion (PGPIB)
Sometimes a GPIB operation waits indefinitely, such as if a device fails to respond to an
operation in which timer override (TO) is specified. The PGPIB attention command can be
used to complete the operation; it cancels the operation by simulating its completion. However,
after a PGPIB, the GPIB adapter is still in a busy state, so it must be reset.
GP IB COMMAND (?):
READ
OPT ION (SE~EOS, TO,EO I):
TRANSLATE INPUT?
TO
Y
HOW MANY CHARACTERS· (MAX=DEFAULT=80):
VALUE DEFAULTED TO 80
DATA REtE! VED:
GP IB COMMAND (?) :.
RESET ADAPTER?
RSET
Y
~'
(,~)
CO-226
SC34-0638
o
Interacting with the GPIB Application (Using $GPIBUT1) (continued)
Resuming $GPIBUT1 Operation (GPRESUME)
If $GPIBUTI has been suspended using the SU command, the GPRESUME attention command
can be used to resume it.
>
GPRESUME
$GPIBUTl RESUMED
COMMAND (1):
Debugging Applications with $GPIBUT1
Along with tools such as $DEBUG, $GPIBUTI can be used to debug an executing GPIB
application. This can be done from one terminal by using the suspend and resume commands.
Using $L, load both $GPIBUTI and the application program from a terminal. (The application
program can also be loaded using $DEBUG.) First load $GPIBUTI and then suspend it with
the SU command. Application debugging can then proceed until you need to use a $GPIBUTI
function. At that point, use GPRESUME to reactivate $GPIBUTl.
o
The list DCB (LDCB) and display status (ST) commands are helpful in this context because
they interpret the effects of GPIB operations. In addition, PGPIB can be used to complete a
GPIB operation which is in an indefinite wait state.
o
Chapter 6. General Purpose Interface Bus - IEEE Standard 488-1975
CO-227
General Purpose Interface Bus - IEEE Standard 488-1975
Interacting with the GPIB Application (Using $GPIBUT1) (continued)
$GPIBUT1 Utility Example
o
Figure 75 shows many of the $GPIBUTI utility operations. The attached device is a plotter.
>
$CP 2
>
$L $GPIBUTl
$GP I BUTl
45P, LP= 0000
$GPIBUTl - GPIB UTILITY
USING GPIB TERMINAL GPIBl
COMMAND(?):
DD
NEW GPIB TERMINAL NAME = GPIB3
GPIB3 IS NOT A GPIB TERMINAL
RETRY?
Y
Figure 7S (Part t of 9). GPIB Utility Example
NEW GPIB TERMINAL NAME = GPIB
COMMAND (?):
CP2
PARTITION CHANGED TO 2
COMMAND (?):
CH
CHARACTER TO BE APPENDED TO OUTPUT DATA -- NOW IS NONE
1
2
3
4
5
= CARRIAGE RETURN
= LINE FEED
= END OF TEXT
= USER SPECIFIED HEX BYTE
= NONE
SELECT CODE:
3
END CHARACTER NOW IS ETX
Figure 75 (Part 2 of 9), GPlB Utility Example
o
CO-228
SC34-0638
o
Interacting with the GPIB Application (Using $GPIBUT1) (continued)
CHARACTER TO BE APPENDED TO OUTPUT DATA -- NOW IS ETX
1 = CARRIAGE RETURN
2 = LI NE FEED
3 = END OF TEXT
4 = USER SPECIFIED HEX BYTE
5 = NONE
SELECT CODE:
5
END CHARACTER NOW IS NONE
COMMAND (1): GP
GPIB COMMAND (1):
CON
OPTION(SE,EOS,TO,EOI):
OPTION(SE,EOS,TO,EOI):
CONFIGURATION DATA:
PROGRAMMING DATA (OR
PROGRAMMING DATA (OR
PROGRAMMING DATA (OR
o
TO
1U%
NONE):
NONE):
NONE):
CONFIGURATION DATA: 1E5
PROGRAMMING DATA (OR NONE):
PROGRAMMING DATA (OR NONE):
CONFIGURATION DATA:
IN;
OE;
NONE
Figure 75 (Part 3 of 9). GPIB Utility Example
o
Chapter 6. General Purpose Interface Bus - IEEE Standard 488-1975
CO-229
General Purpose Interface Bus - IEEE Standard 488-1975
c
Interacting with the GPIB Application (Using $GPIBUT1) (continued)
GPI B ~OMMAtfD ( ?):
({tAD
OPT,ION(SE:,EO$;TO~EO.r):
OPTION (SE, EOS, TO,gO,1 ):
SE
WARNING- EOS OREOI
EOS
WARNING..;. SE MAY BE NEEDED
EOS BX-rE(HEX): .0oixi,QO)
OPIION(SE,EOS,IO,EOI}:
TRANSLATE INPUT? y
HOW MANY CHARACTERS (MAX=DEFAULT=80):
TO 80
VALUE~EFAULTED
o
GP IBCOMMAND (?) :
CON
OPTION(SE,EOS,TO,EOI):
CONFIGURATION DATA:
PROGRAMM ING DATA (OR
PROGRAMMING DATA (OR
PROGRAMMING DATA (OR
?U%
NONE): IN;
NONE):lM223,32,O;
NONE): XX;
****** SRQ RECEIVED ******
Figure 75 (Part 4 of 9). GPIB Utility Example
PROGRAMMING DATA (OR NONE):
CONFIGURATION DATA:
GPIB COMMAND (?): SPE
OPTION(~E,EOS,TO,EOI):
TALKER ADDRESS LIST:
IS THE DATA.OK?
GPIB COMMAND (?):
E
Y
SPL
WARNING - SPE MUST HAVE JUST BEEN EXECUTED
TRANSLATE INPUT?
l~
•
DATA RECEIVED:
4578
.. . . .
WARN I NG
N
...
~ AN SPD MAY NOW BE REQU I RED
)
Figure 75 (Part 5 of 9). GPIB Utility Example
o
CO-230
SC34-0638
o
Interacting with the GPIB Application (Using $GPIBUT1) (continued)
GPIB COMMAND (?):
SPD
OPTION(SE,EOS,TO,EOI}:
GPIB COMMAND (?):
READ
OPT10N(SE,EOS,TO,EOI}:
TRANSLATE INPUT?
TO
Y
HOW MANY CHARACTERS (MAX=DEFAULT=80):
VALUE DEFAULTED TO 80
Figure 75 (Part 6 of 9). GPIB Utility Example
>
PGPIB
DATA RECEIVED:
GPf8;COMMAND (?):
c
READ
'QPTlON(SE,EOS,TO,EOI):
TRANSLATE INPUT? Y
HOW MANY CHARACTERS (MAX=DEFAULT=80)
VALUE DEFAULTED TO 80
'~ERRQR
CODE = 0002
RESET ADAPTER?
Y
Figure 75 (Part 7 of 9). GPIB Utility Example
O~f'I'9,~TsE ,E OS, TO, EO n:
'TRANSlATE I NPUT? Y
'H~~::'~ANY
CHARACTERS (MAX=DEFAUL T=80)
VALUE DEFAULTED TO 80
.• ER~6,g;iC'QDE = 0180
c·':[l ,~~~i~~};~g~P~:D~:~U~TATUS AVA ILABlE
Rk~~ :~t~.T'US? y'
o
Figure 75 (Part 8 of 9). GPIB Utility Example
Chapter 6. General Purpose Interface Bus - IEEE Standard 488-1975
CO-231
General Purpose Interface Bus - IEEE Standard 488-1975
Interacting with the GPIB Application (Using $GPIBUT1) (continued)
RESIDUAL' ADDRESS =
RESIDUAL B)'TE'COUNT =
(RESERVED):;
B45A
0050
'0000
(RES~RVEQ) =
0000
ERROR STATUS =
8000
ausstAfus (AFTER POWER ON) =0068
BUS STATUS (CURR~NT)~=
OOOA
SPE DEVICE ADDRESS ~
0000
DCBSPECIFICATION CHECK =
0000
(RESERVED) =
0000
Dca ADDRESS =
1238
RESIDUAL STATUS BLOCK (HEX)
RESIDUAL BYTE COUNT =0000
RSB fLAGS =
0000
(RESERVED) =
0000
(RESERVED) =
0000
(RESERVED) =
0000
RESET ADAPTER?
Y
NO DATA RECE1VED
GPIB COMMAND (?):
END
Figure 75 (Part 9 of 9). GPIB Utility Example
o
CO-232
SC34-0638
o
Detecting Errors During GPIB Operations
To control the GPIB bus and the attached devices, you should check the return code after each
operation. In general, the application program performs error recovery by retrieving and
analyzing the adapter cycle steal status block or residual status block. The manual General
Purpose Interface Bus (GPIB) Adapter - RPQ D02118 Custom Feature contains detailed
information on cycle steal status and the residual status block. The methods available to the
application program for detecting possible errors and retrieving the return codes returned are
described below.
GPIB errors can be detected in the same manner as other EDX terminal errors: by testing the
first word of the task control block after an I/O instruction, or by coding an error routine
(identified by TERMERR= in the PROGRAM statement). Except for return code 3 (busy
after reset), the application program should handle GPIB return codes like other terminal errors.
An application program can initialize a GPIB bus by means of the TERMCTRL GPIB,RSET
statement. This generates an interface clear (IFC) bus command. All GPIB devices on the bus
must initialize themselves in response to this command. If the application program issues
another command before a device can complete initialization, the busy after reset condition will
occur. One solution is to cause the program to wait long enough for the reset operation to
complete (this takes about 350 milliseconds). Another is to code the TERMCTRL GPIB
command (which follows the reset) with the timer override (TO) option.
o
For exception conditions, the first byte of the error code indicates whether a read or write
operation was requested. A value of 1 in the first byte indicates a read exception, while a 2
indicates a write exception. The second byte of the error code is the interrupt status byte (ISB)
which contains further information on the exception.
Examining Interrupt Status Byte
The ISB can be examined to determine whether the exception condition resulted from an
application program, hardware, or system error. Unless otherwise noted, the ISB bits below
describe the condition when the bit is on.
Bit 0
Unless bit 2 is on, indicates that cycle steal status should be retrieved via the
TERMCTRL GPIB,STAT statement.
Bit 1
Indicates a delayed command rejection which suggests a system error or an
inappropriate/ unusual TERMCTRL GPIB statement.
Bit 2
Indicates an incorrect length re.cord, which means that the number of characters
read from GPIB was less than specified in the input buffer. If the system buffer
(contained in the terminal control block) was used, then the associated
TERMCTRL GPIB,READ statement should contain the suppress exceptions (SE)
option.
Bit 3
Indicates a device control block specification error, which may be a system error.
Word 8 of the cycle steal status block indicates the cause.
o
Chapter 6. General Purpose Interface Bus - IEEE Standard 488-1975
CO-233
General Purpose Interface Bus - IEEE Standard 488-1975
Detecting Errors During GPIB Operations (continued)
Bit 4
Indicates a storage data check, which means that there is a parity problem with
main storage.
Bit 5
Indicates an invalid storage address was passed to the GPIB adapter. This can be a
system problem or a problem with the application program buffer.
Bit 6
Indicates that the GPIB adapter tried to use an invalid storage key. This can be a
system problem or a problem with the application program buffer.
Bit 7
Indicates that an interface data parity error was detected.
o
Examining Cycle Steal Status Block
If bit zero of the ISB is on, word 4 of the cycle steal status block can be examined to determine
the source of the error. The bits in word 4 given below describe the condition when the bit is
on.
Bit 0
The GPIB adapter timed out while waiting to receive data from the bus. To
prevent this, specify timer override (TO) on the TERMCTRL GPIB,READ
statement.
Bit 2
The GPIB adapter timed out while waiting to send data to the bus. To prevent this,
specify timer override (TO) on the TERMCTRL GPIB,WRIT statement.
Bit 4
End of string (EOS) was specified on a TERMCTRL GPIB,READ statement, but
the buffer was filled before the EOS character was received.
Bit 5
End of information (EOI) was specified on a TERMCTRL GPIB,READ statement,
but the buffer was filled before EOI was received.
Retrieving Cycle Steal Status
When a GPIB operation terminates with an exception, an II-word cycle steal status block is
available. To retrieve it, the application should issue a TERMCTRL GPIB,STAT instruction
specifying an area in storage to contain the status block.
STATDATA
TERMCTRL GPIB,STAT"STATDATA
RETRIEVE STATUS
*
*
*
DATA
BLOCK FOR STATUS
11 FlO
I
()
CO-234
SC34-0638
o
Detecting Errors During GPIB Operations (continued)
Retrieving Residual Status Block
If a GPIB READ or read monitor (MON) operation specifies the suppress exception (SE)
option, the 5-word residual status block is available. To retrieve it the application should issue a
TERMCTRL GPIB,RSB instruction specifying an area in storage to contain the status block.
RSBDATA
TERMCTRL GPIB,RSB"RSBDATA
RETRIEVE STATUS
*
*
*
DATA
BLOCK FOR STATUS
SF'O'
o
o
Chapter 6. General Purpose Interface Bus - IEEE Standard 488-1975
CO-235
Notes
c
o
CO-236
SC34-0638
o
Glossary of Terms and Abbreviations
This glossary defines terms and abbreviations used in the Series/1 Event Driven Executive software publications. All software and
hardware terms pertain to EDX. This glossary also serves as a supplement to the IBM Data Processing Glossary, GC20-1699.
o
$SVSLOGA, $SVSLOGB. The name of the alternate system
logging device. This device is optional but, if defined, should be
a terminal with keyboard capability, not just a printer.
asynchronous communications control adapter. An ASCII
terminal attached via #1610, #2091 with #2092, or #2095 with
#2096 adapters.
$SVSLOG. The name of the system logging device or operator
station; must be defined for every system. It should be a terminal
with keyboard capability, not just a printer.
attention key. The key on the display terminal keyboard that, if
pressed, tells the operating system that you are entering a
command.
$SVSPRTR. The name of the system printer.
attention list. A series of pairs of 1 to 8 byte EBCDIC strings
and addresses pointing to EDL instructions. When the attention
key is pressed on the terminal, the operator can enter one of the
strings to cause the associated EDL instructions to be executed.
abend. Abnormal end-of-task. Termination of a task prior to its
completion because of an error condition that cannot be resolved
by recovery facilities while the task is executing.
ACCA. See asynchronous communications control adapter.
address key. Identifies a set of Series/1 segmentation registers
and represents an address space. It is one less than the partition
number.
address space. The logical storage identified by an address key.
An address space is the storage for a partition.
application program manager. The component of the Multiple
Terminal Manager that provides the program management
facilities required to process user requests. It controls the
contents of a program area and the execution of programs within
the area.
o
application program stub. A collection of subroutines that are
appended to a program by the linkage editor to provide the link
from the application program to the Multiple Terminal Manager
facilities.
backup. A copy of data to be used in the event the original data
is lost or damaged.
base record slots. Space in an indexed file that is reserved for
based records to be placed.
base records. Records are placed into an indexed file while in
load mode or inserted in process mode with a new high key.
basic exchange format. A standard format for exchanging data
on diskettes between systems or devices.
binary synchronous device data block (BSCDDB). A control
block that provides the information to control one Series/1
Binary Synchronous Adapter. It determines the line
characteristics and provides dedicated storage for that line.
~
Glossary of Terms and Abbreviations
CO-237
Glossary of Terms and Abbreviations
o
block. (1) See data block or index block. (2) In the Indexed
Method, the unit of space used by the access method to contain
indexes and data.
block mode. The transmission mode in which the 3101 Display
Station transmits a data data stream, which has been edited and
stored, when the SEND key is pressed.
BSCAM. See binary synchronous communications access
method.
be used to contain control blocks or data that will be accessed by
more than one program.
completion code. An indicator that reflects the status of the
execution of a program. The completion code is displayed or
printed on the program's output device.
constant. A value or address that remains unchanged thoughout
program execution.
binary synchronous communications access method. A form
of binary synchronous I/O control used by the Series/1 to
perform data communications between local or remote stations.
controller. A device that has the capability of configuring the
G PI B bus by designating which devices are active, which devices
are listeners, and which device is the talker. In Series/1 GPIB
implementation, the Series/1 is always the controller.
BSCOOB. See binary synchronous device data block.
conversion. See update.
buffer. An area of storage that is temporarily reserved for use in
performing an input/ output operation, into which data is read or
from which data is written. See input buffer and output buffer.
control station. In BSCAM communications, the station that
supervises a multipoint connection, and performs polling and
selection of its tributary stations. The status of control station is
assigned to a BSC line during system generation.
bypass label processing. Access of a tape without any label
processing support.
cross-partition service. A function that accesses data in two
partitions.
CCB. See terminal control block.
central buffer. The buffer used by the Indexed Access Method
for all transfers of information between main storage and indexed
files.
character image. An alphabetic, numeric, or special character
defined for an IBM 4978 Display Station. Each character image
is defined by a dot matrix that is coded into eight bytes.
character image table. An area containing the 256 character
images that can be defined for an IBM 4978 Display Station.
Each character image is coded into eight bytes, the entire table of
codes requiring 2048 bytes of storage.
cross-partition supervisor. A supervisor in which one or more
supervisor modules reside outside of partition 1 (address space
0).
data block. In an indexed file, an area that contains control
information and data records. These blocks are a multiple of 256
bytes.
data record. In an indexed file, the records containing customer
data.
data set. A group of records within a volume pointed to by a
directory member entry in the directory for the volume.
character mode. The transmission mode in which the 3101
Display Station immediately sends a character when a keyboard
key is pressed.
data set control block (OSCB). A control block that provides
the information required to access a data set, volume or directory
using READ and WRITE.
cluster. In an indexed file, a group of data blocks that is pointed
to from the same primary-level index block, and includes the
primary-level index block. The data records and blocks
contained in a cluster are logically contiguous, but are not
necessarily physically contiguous.
data set shut down. An indexed data set that has been marked
(in main storage only) as unusable due to an error.
COO (change of direction). A character used with ACCA
terminal to indicate a reverse in the direction of data movement.
cold start. Starting the spool facility by erasing any spooled jobs
remaining in the spool data set from any previous spool session.
command. A character string from a source external to the
system that represents a request for action by the system.
OCE. See directory control entry.
device data block (OOB). A control block that describes a disk
or diskette volume.
direct access. (1) The access method used to READ or WRITE
records on a disk or diskette device by specifying their location
relative the beginning of the data set or volume. (2) In the
Indexed Access Method, locating any record via its key without
respect to the previous operation. (3) A condition in terminal I/O
where a READTEXT or a PRINTEXT is directed to a buffer which
was previously enqueued upon by an 10CB.
common area. A user-defined data area that is mapped into the
partitions specified on the SYSTEM definition statement. It can
o
CO-238
SC34-0638
o
directory. (1) A series of contiguous records in a volume that
describe the contents in terms of allocated data sets and free
space. (2) A series of contiguous records on a device that
describe the contents in terms of allocated volumes and free
space. (3) For the Indexed Access Method Version 2, a data set
that defines the relationship between primary and secondary
indexed files (secondary index support).
directory control entry (DCE). The first 32 bytes of the first
record of a directory in which a description of the directory is
stored.
external label. A label attached to the outside of a tape that
identifies the tape visually. It usually contains items of
identification such as file name and number, creation data,
number of volumes, department number, and so on.
external name (EXTRN). The 1- to 8-character symbolic
EBCDIC name for an entry point or data field that is not defined
within the module that references the name.
FCA. See file control area.
FCB. See file control block.
directory member entry (OM E). A 32-byte directory entry
describing an allocated data set or volume.
display station. An IBM 4978,4979, or 3101 display terminal or
similar terminal with a keyboard and a video display.
DME. See directory member entry.
DSCB. See data set control block.
dynamic storage. An increment of storage that is appended to a
program when it is loaded.
end-of-data indicator. A code that signals that the last record of
a data set has been read or written. End-of-data is determined
by an end-of-data pointer in the DME or by the physical end of
the data set.
ECB. See event control block.
EDl. See Event Driven Language.
emulator. The portion of the Event Driven Executive supervisor
that interprets EDL instructions and performs the function
specified by each EDL statement.
end-of-tape (EOT). A reflective marker placed near the end of a
tape and sensed during output. The marker signals that the tape
is nearly full.
enter key. The key on the display terminal keyboard that, if
pressed, tells the operating system to read the information you
entered.
event control block (ECB). A control block used to record the
status (occurred or not occurred) of an event; often used to
synchronize the execution of tasks. ECBs are used in conjunction
with the WAIT and POST instructions.
Event Driven Language (EDL). The language for input to the
Event Driven Executive compiler ($EDXASM), or the Macro and
Host assemblers in conjunction with the Event Driven Executive
macro libraries. The output is interpreted by the Event Driven
Executive emulator.
EXIO (execute input or output). An EDL facility that provides
user controlled access to Series/1 input/output devices.
file. A set of related records treated as a logical unit. Although
file is often used interchangeably with data set, it usually refers to
an indexed or a sequential data set.
file control area (FCA). A Multiple Terminal Manager data area
that describes a file access request.
file control block (FCB). The first block of an indexed file. It
contains descriptive information about the data contained in the
file.
file control block extension. The second block of an indexed
file. It contains the file definition parameters used to define the
file.
file manager. A collection of subroutines contained within the
program manager of the Multiple Terminal Manager that provides
common support for all disk data transfer operations as needed
for transaction-oriented application programs. It supports
indexed and direct files under the control of a single callable
function.
floating point. A positive or negative number that can have a
decimal point.
formatted screen image. A collection of display elements or
display groups (such as operator prompts and field input names
and areas) that are presented together at one time on a display
device.
free pool. In an indexed data set, a group of blocks that can be
used for either data blocks or index blocks. These differ from
other free blocks in that these are not initially assigned to specific
logical positions in the file.
free space. In an indexed file, records blocks that do not
currently contain data, and are available for use.
free space entry (FSE). An 8-byte directory entry defining an
area of free space within a volume or a device.
FSE. See free space entry.
general purpose interface bus. The IEEE Standard 488-1975
that allows various interconnected devices to be attached to the
GPIB adapter (RPQ 002118).
o
Glossary of Terms and Abbreviations
CO-239
Glossary of Terms and Abbreviations
c
GPIB. See general purpose interface bus.
group. A unit of 100 records in the spool data set allocated to a
spool job.
H exchange format. A standard format for exchanging data on
diskettes between systems or devices.
host assembler. The assembler licensed program that executes
in a 370 (host) system and produces object output for the
Series/1. The source input to the host assembler is coded in
Event Driven Language or Series/1 assembler language. The
host assembler refers to the System/370 Program Preparation
Facility (5798-NNQ).
host system. Any system whose resources are used to perform
services such as program preparation for a Series/1. It can be
connected to a Series/1 by a communications link.
IACB. See indexed access control block.
IAR. See instruction address register.
index register (#1. #2). Two words defined in EDL and
contained in the task control block for each task. They are used
to contain data or for address computation.
input buffer. (1) See buffer. (2) In the Multiple Terminal
Manager, an area for terminal input and output.
input output control block (lOCB). A control block containing
information about a terminal such as the symbolic name, size and
shape of screen, the size of the forms in a printer; or an optional
reference to a user provided buffer.
instruction address register OAR). The pointer that identifies
the machine instruction currently being executed. The Series/1
maintains a hardware IAR to determine the Series/1 assembler
instruction being executed. It is located in the level status block
(LSB).
integer. A positive or negative number that has no decimal
point.
interactive. The mode in which a program conducts a
continuous dialogue between the user and the system.
ICB. See indexed access control block.
liB. See interrupt information byte.
image store. The area in a 4978 that contains the character
image table.
immediate data. A self-defining term used as the operand of an
instruction. It consists of numbers, messages or values which
are processed directly by the computer and which do not serve as
addresses or pointers to other data in storage.
index. In an indexed file, an ordered collection of pairs of keys
and pointers, used to sequence and locate records.
index block. In an indexed file, an area that contains control
information and index entries. These blocks are a multiple of 256
bytes.
indexed access control block (lACB/ICB). The control block
that relates an application program to an indexed file.
indexed access method. An access method for direct or
sequential processing of fixed-length records by use of a
record's key.
internal label. An area on tape used to record identifying
information (similar to the identifying information placed on an
externallabell. Internal labels are checked by the system to
ensure that the correct volume is mounted.
interrupt information byte (liB). In the Multiple Terminal
Manager, a word containing the status of a previous input/ output
request to or from a terminal.
invoke. To load and activate a program, utility, procedure, or
subroutine into storage so it can run.
job. A collection of related program execution requests
presented in the form of job control statements, identified to the
jobstream processor by a JOB statement.
job control statement. A statement in a job that specifies
requests for program execution, program parameters, data set
definitions, sequence of execution, and, in general, describes the
environment required to execute the program.
job stream processor. The job processing facility that reads job
control statements and processes the requests made by these
statements. The Event Driven Executive job stream processor is
$JOBUTIL.
indexed data set. Synonym for indexed file.
indexed file. A file specifically created, formatted and used by
the Indexed Access Method. An indexed file is sometimes called
an indexed data set.
index entry. In an indexed file, a key-pointer pair, where the
pointer is used to locate a lower-level index block or a data block.
jumper. (1) A wire or pair of wires which are used for the
arbitrary connection between two circuits or pins in an
attachment card. (2) To connect wire(s) to an attachment card or
to connect two circuits.
key. In the Indexed Access Method, one or more consecutive
characters used to identify a record and establish its order with
respect to other records. See also key field.
()
CO-240
SC34-0638
o
key field. A field. located in the same position in each record of
an indexed file. whose content is used for the key of a record.
level status block (LSB). A Series/1 hardware data area that
contains processor status. This area is eleven words in length.
library. A set of contiguous records within a volume. It contains
a directory. data sets and / or available space.
line. A string of characters accepted by the system as a single
input from a terminal; for example. all characters entered before
the carriage return on the teletypewriter or the ENTER key on the
display station is pressed.
new high key. A key higher than any other key in an indexed
file.
non labeled tapes. Tapes that do not contain identifying labels
(as in standard labeled tapes) and contain only files separated by
tapemarks.
listener. A controller or active device on a GPIB bus that is
configured to accept information from the bus.
null character. A user-defined character used to define the
unprotected fields of a formatted screen.
load mode. In the Indexed Access Method. the mode in which
records are loaded into base record slots in an indexed file.
option selection menu. A full screen display used by the
Session Manager to point to other menus or system functions.
one of which is to be selected by the operator. (See primary
option menu and secondary option menu.)
load point. (1) Address in the partition where a program is
loaded. (2) A reflective marker placed near the beginning of a
tape to indicate where the first record is written.
lock. In the Indexed Access Method. a method of indicating that
a record or block is in use and is not available for another request.
logical screen. A screen defined by margin settings. such as the
TOPM. BOTM. LEFTM and RIGHTM parameters of the
TERMINAL or IOCB statement.
LSB. See level status block.
mapped storage. The processor storage that you defined on the
SYSTEM statement during system generation.
member. A term used to identify a named portion of a
partitioned data set (PDS). Sometimes member is also used as a
synonym for a data set. See data set.
menu. A formatted screen image containing a list of options.
The user selects an option to invoke a program.
menu-driven. The mode of processing in which input consists of
the responses to prompting from an option menu.
message. In data communications. the data sent from one
station to another in a single transmission. Stations
communication with a series of exchanged messages.
o
multivolume file. A data file that. due to its size. requires more
than one unit of recording media (such as tape reel or disk pack)
to contain the entire file.
link edit. The process of resolving external symbols in one or
more object modules. A link edit is performed with $EDXLlNK
whose output is a loadable program.
load module. A single module having cross references resolved
and prepared for loading into storage for execution. The module
is the output of the $UPDATE or $UPDATEH utility.
()
multiple terminal manager. An Event Driven Executive licensed
program that provides support for transaction-oriented
applications on a Series/1. It provides the capability to define
transactions and manage the programs that support those
transactions. It also manages mUltiple terminals as needed to
support these transactions.
output buffer. (1) See buffer. (2) In the Multiple Terminal
Manager. an area used for screen output and to pass data to
subsequent transaction programs.
overlay. The technique of reusing a single storage area allocated
to a program during execution. The storage area can be reused
by loading it with overlay programs that have been specified in
the PROGRAM statement of the program or by calling overlay
segments that have been specified in the OVERLAY statement of
$EDXLlNK.
overlay area. A storage area within a program reserved for
overlay programs specified in the PROGRAM statement or
overlay segments specified in the OVERLAY statement in
$EDXLlNK.
overlay program. A program in which certain control sections
can use the same storage location at different times during
execution. An overlay program can execute concurrently as an
asynchronous task with other programs and is specified in the
EDL PROGRAM statement in the main program.
overlay segment. A self-contained portion of a program that is
called and sequentially executes as a synchronous task. The
entire program that calls the overlay segment need not be
maintained in storage while the overlay segment is executing. An
overlay segment is specified in the OVERLAY statement of
$EDXLlNK or $XPSLlNK (for initialization modules).
overlay segment area. A storage area within a program or
supervisor reserved for overlay segments. An overlay segment
area is specified with the OVLAREA statement of $EDXLlNK.
multifile volume. A unit of recording media. such as tape reel or
disk pack. that contains more than one data file.
Glossary of Terms and Abbreviations
CO-241
Glossary of Terms and Abbreviations
parameter selection menu. A full screen display used by the
Session Manager to indicate the parameters to be passed to a
program.
partition. A contiguous fixed-sized area of storage. Each
partition is a separate address space.
performance volume. A volume whose name is specified on
the DISK definition statement so that its address is found during
IPL, increasing system performance when a program accesses
the volume.
physical timer. Synonym for timer (hardware).
polling. In data communications, the process by which a
multipoint control station asks a tributary if it can receive
messages.
precision. The number of words in storage needed to contain a
value in an operation.
prefind. To locate the data sets or overlay programs to be used
by a program and to store the necessary information so that the
time required to load the prefound items is reduced.
process mode. In the Indexed Access Method, the mode in
which records can be retrieved, updated, inserted or deleted.
o
processor status word (PSW). A 16-bit register used to (1)
record error or exception conditions that may prevent further
processing and (2) hold certain flags that aid in error recovery.
program. A disk- or diskette-resident collection of one or more
tasks defined by a PROGRAM statement; the unit that is loaded
into storage. (See primary task and secondary task.)
program header. The control block found at the beginning of a
program that identifies the primary task, data sets, storage
requirements and other resources required by a program.
program/storage manager. A component of the Multiple
Terminal Manager that controls the execution and flow of
application programs within a single program area and contains
the support needed to allow multiple operations and sharing of
the program area.
protected field. A field in which the operator cannot use the
keyboard to enter, modify, or erase data.
PSW. See processor status word.
primary file. An indexed file containing the data records and
primary index.
primary file entry. For the Indexed Access Method Version 2,
an entry in the directory describing a primary file.
OCB. See queue control block.
00. See queue descriptor.
OE. See queue element.
primary index. The index portion of a primary file. This is used
to access data records when the primary key is specified.
primary key. In an indexed file, the key used to uniquely identify
a data record.
primary-level index block. In an indexed file, the lowest level
index block. It contains the relative block numbers (RBNs) and
high keys of several data blocks. See cluster.
primary menu. The program selection screen displayed by the
Multiple Terminal Manager.
primary option menu. The first full screen display provided by
the Session Manager.
primary station. In a Series/1 to Series/ 1 attachment. the
processor that control communication between the two
computers. Contrast with secondary station.
primary task. The first task executed by the supervisor when a
program is loaded into storage. It is identified by the PROGRAM
statement.
priority. A combination of hardware interrupt level priority and a
software ranking within a level. Both primary and secondary
tasks will execute asynchronously within the system according to
the priority assigned to them.
queue control block (OCB). A data area used to serialize access
to resources that cannot be shared. See serially reusable
resource.
queue descriptor (00). A control block describing a queue built
by the DEFINEQ instruction.
queue element (OE). An entry in the queue defined by the
queue descriptor.
quiesce. To bring a device or a system to a halt by rejection of
new requests for work.
quiesce protocol. A method of communication in one direction
at a time. When sending node wants to receive, it releases the
other node from its quiesced state.
record. (1) The smallest unit of direct access storage that can be
accessed by an application program on a disk or diskette using
READ and WRITE. Records are 256 bytes in length. (2) In the
Indexed Access Method, the logical unit that is transferred
between $IAM and the user's buffer. The length of the buffer is
defined by the user. (3) In BSCAM communications, the portions
of data transmitted in a message. Record length (and, therefore,
message length) can be variable.
recovery. The use of backup data to re-create data that has
been lost or damaged.
o
CO-242
SC34-0638
o
reflective marker. A small adhesive marker attached to the
reverse (nonrecording) surface of a reel of magnetic tape.
Normally, two reflective markers are used on each reel of tape.
One indicates the beginning of the recording area on the tape
(load point), and the other indicates the proximity to the end of
the recording area (EOT) on the reel.
relative block address (RBA). The location of a block of data on
a 4967 disk relative to the start of the device.
relative record number. An integer value identifying the
position of a record in a data set relative to the beginning of the
data set. The first record of a data set is record one, the second
is record two, the third is record three.
relocation dictionary (RLD). The part of an object module or
load module that is used to identify address and name constants
that must be adjusted by the relocating loader.
remote management utility control block (RCB). A control
block that provides information for the execution of remote
management utility functions.
reorganize. The process of copying the data in an indexed file to
another indexed file in a manner that rearranges the data for more
optimum processing and free space distribution.
o
restart. Starting the spool facility w the spool data set contains
jobs from a previous session. The jobs in the spool data set can
be either deleted or printed when the spool facility is restarted.
return code. An indicator that reflects the results of the
execution of an instruction or subroutine. The return code is
usually placed in the task code word (at the beginning of the task
control block).
roll screen. A display screen which is logically segmented into
an optional history area and a work area. Output directed to the
screen starts display at the beginning of the work area and
continues on down in a line-by-line sequence. When the work
area gets full, the operator presses ENTER/SEND and its contents
are shifted into the optional history area and the work area itself
is erased. Output now starts again at the beginning of the work
area.
secondary option menu. In the Session Manager, the second in
a series of predefined procedures grouped together in a
hierarchical structure of menus. Secondary option menus provide
a breakdown of the functions available under the session
manager as specified on the primary option menu.
secondary task. Any task other than the primary task. A
secondary task must be attached by a primary task or another
secondary task.
secondary station. In a Series/1 to Series/1 attachment, the
processor that is under the control of the primary station.
sector. The smallest addressable unit of storage on a disk or
diskette. A sector on a 4962 or 4963 disk is equivalent to an
Event Driven Executive record. On a 4964 or 4966 diskette, two
sectors are equivalent to an Event Driven Executive record.
selection. In data communications, the process by which the
multipoint control station asks a tributary station if it is ready to
send messages.
self-defining term. A decimal, integer, or character that the
computer treats as a decimal, integer, or character and not as an
address or pointer to data in storage.
sensor based I/O control block (SBIOCB). A control block
containing information related to sensor I/O operations.
sequential access. The processing of a data set in order of
occurrence of the records in the data set. (1) In the Indexed
Access Method, the processing of records in ascending collating
sequence order of the keys. (2) When using READ/WRITE, the
processing of records in ascending relative record number
sequence.
serially reusable resource (SRR). A resource that can only be
accessed by one task at a time. Serially reusable resources are
usually managed via (1) a QCB and ENQ/DEQ statements or (2) an
ECB and WAIT/POST statements.
service request. A device generated signal used to inform the
controller that service is required by the issuing device.
SBIOCB. See sensor based I/O control block.
GPIB
second-level index block. In an indexed data set, the
second-lowest level index block. It contains the addresses and
high keys of several primary-level index blocks.
session manager. A series of predefined procedures grouped
together as a hierarchical structure of menus from which you
select the utility functions, program preparation facilities, and
language processors needed to prepare and execute application
programs. The menus consist of a primary option menu that
displays functional groupings and secondary option menus that
display a breakdown of these functional groupings.
secondary file. See secondary index.
secondary index. For the Indexed Access Method Version 2, an
indexed file used to access data records by their secondary keys.
Sometimes called a secondary file.
o
secondary key. For the Indexed Access Method Version 2, the
key used to uniquely identify a data record.
shared resource. A resource that can be used by more than one
task at the same time.
secondary index entry. For the Indexed Access Method
Version 2, this an an entry in the directory describing a secondary
index.
Glossary of Terms and Abbreviations
CO-243
Glossary of Terms and Abbreviations
shut down. See data set shut down.
source module/program. A collection of instructions and
statements that constitute the input to a compiler or assembler.
Statements may be created or modified using one of the text
editing facilities.
spool job. The set of print records generated by a program
(including any overlays) while engueued to a printer designated as
a spool device.
spool session. An invocation and termination of the spool
facility.
spooling. The reading of input data streams and the writing of
output data streams on storage devices, concurrently with job
execution, in a format convenient for later processing or output
operations.
system partition. The partition that contains the root segment
of the supervisor (partition number 1, address space 0).
o
talker. A controller or active device on a GPIB bus that is
configured to be the source of information (the sender) on the
bus.
tape device data block (TDB). A resident supervisor control
block which describes a tape volume.
tapemark. A control character recorded on tape used to
separate files.
task. The basic executable unit of work for the supervisor. Each
task is assigned its own priority and processor time is allocated
according to this priority. Tasks run independently of each other
and compete for the system resources. The first task of a
program is the primary task. All tasks attached by the primary
task are secondary tasks.
SRQ. See service request.
stand-alone dump. An image of processor storage written to a
diskette.
stand-alone dump diskette. A diskette supplied by IBM or
created by the $DASDI utility.
standard labels. Fixed length BO-character records on tape
containing specific fields of information (a volume label
identifying the tape volume, a header label preceding the data
records, and a trailer label following the data records).
static screen. A display screen formatted with predetermined
protected and unprotected areas. Areas defined as operator
prompts or input field names are protected to prevent accidental
overlay by input data. Areas defined as input areas are not
protected and are usually filled in by an operator. The entire
screen is treated as a page of information.
station. In BSCAM communications, a BSC line attached to the
Series/1 and functioning in a point-to-point or multipoint
connection. Also, any other terminal or processor with which the
Series/1 communicates.
subroutine. A sequence of instructions that may be accessed
from one or more points in a program.
supervisor. The component of the Event Driven Executive
capable of controlling execution of both system and application
task code word. The first two words (32 bits) of a task's TCB;
used by the emulator to pass information from system to task
regarding the outcome of various operations, such as event
completion or arithmetic operations.
task control block (TCB). A control block that contains
information for a task. The information consists of pointers, save
areas, work areas, and indicators required by the supervisor for
controlling execution of a task.
task supervisor. The portion of the Event Driven Executive that
manages the dispatching and switching of tasks.
()
TCB. See task control block.
terminal. A physical device defined to the EDX system using the
TERMINAL configuration statement. EDX terminals include
directly attached IBM displays, printers and devices that
communicate with the Series/1 in an asynchronous manner.
terminal control block (CCB). A control block that defines the
device characteristics, provides temporary storage, and contains
links to other system control blocks for a particular terminal.
terminal environment block (TEB). A control block that
contains information on a terminal's attributes and the program
manager operating under the Multiple Terminal Manager. It is
used for processing requests between the terminal servers and
the program manager.
piogiams.
system configuration. The process of defining devices and
features attached to the Series/1.
SYSGEN. See system generation.
system generation. The processing of defining I/O devices and
selecting software options to create a supervisor tailored to the
needs of a specific Series/1 hardware configuration and
application.
terminal screen manager. The component of the Multiple
Terminal Manager that controls the presentation of screens and
communications between terminals and transaction programs.
terminal server. A group of programs that perform all the
input/ output and interrupt handling functions for terminal devices
under control of the Multiple Terminal Manager.
()
CO-244
SC34-0638
o
terminal support. The support provided by EDX to manage and
control terminals. See terminal.
timer. The timer features available with the Series/1 processors.
Specifically, the 7840 Timer Feature card (4955 only) or the native
timer (4952, 4954, and 4956). Only One or the other is supported
by the Event Driven Executive.
update. (1) To alter the contents of storage or a data set. (2) To
convert object modules, produced as the output of an assembly
or compilation, or the output of the linkage editor, into a form that
can be loaded into storage for program execution and to update
the directory of the volume On which the loadable program is
stored.
trace range. A specified number of instruction addresses within
which the flow of execution can be traced.
user exit. (1) Assembly language instructions included as part of
an EDL program and invoked via the USER instruction. (2) A
point in an IBM-supplied program where a user written routine
can be given control.
transaction oriented applications. Program execution driven by
operator actions, such as responses to prompts from the system.
Specifically, applications executed under control of the Multiple
Terminal Manager.
variable. An area in storage, referred to by a label, that can
contain any value during program execution.
transaction program. See transaction-oriented applications.
transaction selection menu. A Multiple Terminal Manager
display screen (menu) offering the user a choice of functions,
such as reading from a data file, displaying data on a terminal, or
waiting for a response. Based upon the choice of option, the
application program performs the requested processing
operation.
vary offline. (1) To change the status of a device from online to
offline. When a device is offline, no data set can be accessed on
that device. (2) To place a disk or diskette in a state where it is
unknown by the system.
vary online. To place a device in a state where it is available for
use by the system.
vector. An ordered set or string of numbers.
o
tributary station. In BSCAM communications, the stations
under the supervision of a control station in a multipoint
connection. They respond to the control station's polling and
selection.
unmapped storage. The processor storage in your processor
that you did not define On the SYSTEM statement during system
generation.
volume. A disk, diskette, or tape subdivision defined using
$INITDSK or $TAPEUT1.
volume descriptor entry (VDE). A resident supervisor control
block that describes a volume on a disk or diskette.
volume label. A label that uniquely identifies a single unit of
storage media.
unprotected field. A field in which the operator can use the
keyboard to enter, modify or erase data. Also called
non-protected field.
o
Glossary of Terms and Abbreviations
CO-24S
o
()
o
CO-246
SC34-0638
o
Index
The following index contains entries for this book only. See the Library Guide and Common Index for a Common
Index to all Event Driven Executive books.
o
o
Special Characters
$$X21 DS data set
description CO-49
$BSCTRCE utility
description CO-33
$BSCUT1 utility
commands CO-35
invoking CO-35
$BSCUT2 utility
change hard-copy device CO-43
commands CO-39
description CO-38
invoking CO-39
$CAPGM, channel attach program CO-145
$GPIBUT1 utility
description CO-220
example CO-228
use in debugging applications CO-227
$HCFUn utility CO-139
$RMU
See Remote Management Utility ($RMU)
$RMUPA CO-97
A
abort
Series /1 -to- Series /1 write CO-194
acquire use of BSC line CO-17
ADAPTER statement CO-13
ADAPTER= operand, BSCLINE statement CO-13
allocate
trace file data set CO-33
ALLOCATE function, $RMU
control character flow CO-73
for program data set CO-71
receive status message CO- 71
required fields CO- 72
send request CO-71
terminate function CO-71
application programs, BSCAM CO-16
attach
BSC lines CO-8
B
binary synchronous communications (BSC)
communications features CO-9
line connections CO-7
Remote Management Utility ($RMU) CO-57
sample programs CO-109
test BSCAM CO-38
trace printing utility, $BSCUT1 CO-34
trace utility, $BSCTRCE CO-33
binary synchronous communications access method (BSCAM)
Index
CO-247
Index
$BSCTRCE, invoking CO-33
acquire use of BSC line CO-17
allocate trace file data set CO-33
basic programming functions CO-16
BSCWRITE I instruction CO-20
buffers, use of CO -18
communications indicator panel, installing CO-45
continue write operations CO-22
control block, coding CO-17
control characters
for continue write CO-23
for initial write CO-20
for special writes CO-25
control station CO-8
conversation mode of transmission CO-15
data links, use of CO-7
define
BSC line type CO-12
BSC lines to supervisor CO-12
delay
receiving messages CO-27
write operation CO-24
DLE character, use of CO-14
EDL instruction set CO-16
end
read operation CO-28
write operation CO-25
error recovery CO-29
format trace files for output CO-34
hardware
configuration, determining CO-8
requirements CO-8
initial write operations CO-20
interacting with CO-32
line connections, use of CO-7
nontransparent data transmission CO-14
overview CO-5
planning for CO-6
point-to-point connection CO-7
poll/select
address CO-13
sequences CO-20
programming for CO-16
read
data stream CO-28
ENQ character CO-28
operation CO-16, CO-26
transparent/nontransparent data CO-38
types, selecting CO-26
READ sampie program CO-31
receiving
data CO-26
first message CO-27
subsequent messages CO-27
requesting repeat of message CO-28
responding to poll/select CO-28
sample programs CO-29
sending
data CO-19
tranparent data in blocks CO-15
special considerations for local operations CO-ll
special write operations CO-23
standard data transmission, uses of CO-14
standard mode of transmission CO-15
supervisor
module CO-14
support, including CO-12
terminology CO-6
test read and write capability CO-39
trace I/O activity CO-33
transmission, modes of CO-15
transparent data transmission CO-14
types of data transmitted CO-14
utilities CO-32
write
continue CO-22
end operation CO-25
initial CO-20
operation CO-16, CO-19, CO-25
programming sequence CO-25
types, selecting CO-19
WRITE sample program CO-29
blocking factor
$RMU PASSTHRU data set CO-66
$RMU source data set CO-66
$RMU standard data set CO-65
BSC communications features
communications indicator panel, use with CO-ll
jumpering for direct-connect operations CO-ll
jumpering for multipoint tributary operation CO-ll
modem eliminators, use with CO-ll
modems, use with CO-ll
multifunction attachment CO-l0
single-line control, high speed (2075 feature card) CO-9
single-line control, high speed (2080 feature card) CO-9
single-line control, medium speed (2074 feature card) CO-9
4-line adapter CO-l0
8-line control CO-l0
BSC control characters
use with continue writes CO-23
use with initial writes CO-20
use with special wri~ CO-25
BSC I/O exerciser ($BSCU~CO-38
BSC line address default, ($RMU) CO-64
BSC lines
acquiring use of CO-17
addresses, determining CO-8
attaching and controlling CO-8
defining line type CO-12
defining to supervisor CO-' 2
in multipoint connection CO-8
in point-to-point connection CO-7
trace I/O activity on CO-33
BSC read types
BSCREAD C CO-27
BSCREAD D CO-27
BSCREAD E CO-28
BSCREAD I CO-27
BSCREAD P CO-28
BSCREAD Q CO-28
o
o
CO-248
SC34-0638
o
o
BSCREAD R CO-28
BSCREAD U CO-28
BSC single-line control
high speed, 2075 feature card CO-9
high speed, 2080 feature card CO-9
medium speed, 2074 feature card CO-9
BSC trace records, dump CO-34
BSC 4-line adapter CO-l0
BSC 8-line control CO-l0
BSCAM
See binary synchronous communications access method
(BSCAM)
BSCCLOSE instruction
use of CO-17
BSCIOCB statement
forX.21 CO-17
using CO-17
BSCLINE statement
ADAPTER= operand CO-13
address default for $RMU CO-64
TYPE= operand CO-12
TYPE= operand for X.21 use CO-12
use with $RMU CO-59
BSCOPEN instruction
forX.21 CO-17
use of CO-17
BSCREAD instruction
C-type CO-27
D-type CO-27
E-type CO-28
I-type CO-27
P-type CO-28
Q-type CO-28
R-type CO-28
U-type CO-28
BSCWRITE instruction
C-type CO-22
D-type CO-24
E-type CO-25
EX-type CO-25
I-type CO-20
N-type CO-24
Q-type CO-24
U-type CO-24
UX-type CO-24
BTAM/BTAM-ES, channel attach considerations CO-149
buffer
use in BSCAM CO-18
buffer size default, ($RMU) CO-65
c
o
CA instructions CO-148
call progress signals for X.21 CO-56
CH command ($GPIBUTl) CO-220
change
BSC line address default, $RMU CO-64
buffer size default, $RMU CO-65
GPIB partition CO-221
host system ID, $RMU CO-63
remote system ID, $RMU CO-63
storage size default, $RMU CO-64
channel attach
$CAPGM CO-145
$CHANUTl utility CO-155
assembling application program CO-150
BTAM considerations CO-149
change device address (CA) CO-156
close a port (CACLOSE) CO-154
code control block for port (CAIOCB) CO-152
commands CO-155
device (4993) CO-146
EDL instruction set CO-148
enable / disable a trace (TR) CO-156
end utility (EN) CO-156
error handling CO-149
functions supported CO-146
hardware considerations CO-146
invoking CO-155
issue I/O CO-152
link-edit application program CO-150
open a port (CAOPEN) CO-152
overview CO-145
perform a trace (TR) CO-156
plan to use CO-145
power on device CO-148
print trace data (CAPRINT) CO-155
print trace data (PR) CO-156
programs for CO-148
read from a port (CAREAD) CO-152
receive data from host (CAREAD) CO-152
sample programs CO-157
send data to host (CAWRITE) CO-153
software considerations CO-146
start a device (ST) CO-156
start device (CASTART) CO-151
stop a device (CASTOP) CO-154
stop a device (SP) CO-156
tailor channel attach program CO-147
trace Series /1 I/O (CATRAC E) CO -155
write to a port (CAWRITE) CO-152
communications applications, writing
for $RMU CO-66
for BSCAM CO-16
for channel attach CO-148
for Host Communication Facility CO-132
for Series/l-to-Series/1 attachment CO-179
communications features
jumpering CO-11
communications indicator panel
for X.21 display/function select switch settings CO-47
functions monitored CO-46
selecting line to monitor CO-45
communications utilities
$BSCTRCE CO-33
$BSCUTl CO-34
$BSCUT2 CO-38
$CHANUTl CO-155
$GPIBUT1 CO-220
Index
CO-249
Index
$HCFUT1 CO-139
$S1S1UT1 CO-194
connect host and remote systems, $RMU CO-59
connection record for X.21 CO-49
continue write operations, BSCAM CO-22
control block, use with BSCAM CO-17
control characters, BSC CO-20
control data transfers, $RMU
echo host data CO-84
perform echo test CO-84
receive data from host CO- 78
receive data from remote system CO-82
send data to host CO-82
send data to remote system CO-78
control data transfers, Host Communication Facility
receive data from host CO-134
send data to host CO-134
control program execution, $RMU
execute program CO-86
terminate $RMU CO-90
controlling BSC lines CO-8
conversation response mode, BSCAM CO-15
count message, Remote Management Utility CO-69
CP command ($GPIBUT1) CO-221
D
data links, selecting CO-7
data links, types of CO-7
data message, Remote Management Utility CO-69
data types transmitted by BSCAM CO-14
data-link=escape (DLE) character CO-14
DO command ($GPIBUT1) CO-221
define
BSC line to supervisor CO-12
BSC line types CO-12
end character (GPIB) CO-220
GPIB device CO-221
remote system
defaults CO-62
requirements CO-60
responses to host CO-.67
delay receiving messages with BSCAM CO-27
delay transmission write operation CO-24
delete
data set ($RMU) CO-74
DELETE function, $RMU
control character flow CO-75
receive status message CO-74
required fields CO- 75
send request CO-74
terminate function CO-74
determine
BSC hardware configuration CO-8
device error codes for X.21 CO-55
direct-connect operations, BSCAM CO-11
OLE character, use of CO-14
dump
storage partition ($RMU) CO-76
-DUMP function, $RMU
BSC trace records CO-34
control character flow CO-77
receive status message CO-76
required fields CO-76
send request CO-76
terminate function CO- 76
o
E
echo test, ($RMU) CO-84
EN command ($GPIBUT1) CO-221
end
BSCAM write operation CO-25
read operation with BSCAM CO-28
error handling
$RMU CO-69
BSCAM error recovery CO-29
error log for X.21 CO-52
EXEC function, $RMU
allocate free space CO-87
control character flow CO-89
data set passing CO-87
parameter passing CO-87
required fields CO-88
send request CO-86
specify partition CO-87
execute
program
with $RMU CO-86
exerciser, BSC line ($BSCUT2) CO-38
F
FE command ($HCFUT1) CO-141
format
BSC trace files CO-34
G
General Purpose Interface Bus
configuration CO-201, CO-206
cycle steal status CO-234
data transfers CO-208
device addresses CO-200
device group operation CO...,,211
device modes CO-200
error handling CO-233
initialization CO-201, CO-205
interrupt handling CO-202
interrupt status byte CO-233
loading programs CO-207
overview CO -199
parallel polling CO-210
planning to use CO-199
sample program CO-216
o
CO-2S0
SC34-0638
o
serial polling CO-209
service requests (SRQ) CO-202
system generation CO -199
terminal I/O considerations CO-204
translated data (XLATE=NO) CO-204
universal unlisten CO-206
user buffer CO-204
GP command ($GPIBUT1) CO-221
GPIB control CO-221
GPRESUME command ($GPIBUT1) CO-227
H
c
hardware
requirements
$RMU remote system CO-60
for BSCAM CO-8
Host Communications Facility
$HCFUT1 utility CO-139
control data transfers CO-133
data set characteristics CO-129
data transfer rate CO-132
host data sets CO-128
host storage CO-132
installation requirements CO-128
obtain time and date CO-136
open host data set CO-130
overview CO-127
perform status functions CO-135
plan for CO-128
programming for CO-132
submit job to host CO-135
system status data set CO-130
TP instructions CO-132
host data set, HCF
characteristics CO -129
naming conventions CO-128
open CO-130
record sizes CO-129
variable-length records CO -130
host programming for $RMU CO-66
host system 10, change ($RMU) CO-63
host system requirements, $RMU CO-61
J
jumper
for direct-connect operations, BSCAM CO-11
for multipoint tributary stations CO-11
L
LOCB command ($GPIBUT1) CO-222
leased lines CO- 7
limited conversational transmission mode, use by
BSCAM CO-15
list
device control block (GPIB) CO-222
local operations, BSCAM CO-11
M
manage data sets, $RMU
allocate CO-71
delete CO-74
dump storage to data set CO-76
messages
$RMU
count CO-69
data CO-69
header CO-67
status CO-67
mode of transmission, $RMU CO-60
modem eliminators CO-ll
modems CO-ll
monitor
BSC lines CO-45
multifunction attachment
use in BSC CO-l0
multipoint
connections CO-8
control station CO-8
special considerations CO-ll
tributary station CO-8
N
I
I/O, exerciser ($BSCUT2) CO-38
10CHECK function, $RMU
control character flow CO-95
required fields CO-94
send request CO-94
initial write operations, BSCAM CO-20
initialize
GPIB CO-201
install communications indicator panel CO-45
installation requirements, HCF CO-128
internal clocking, jumpering for CO-ll
no data record, PASSTHRU function of $RMU CO-l08
nonswitched lines CO-7
nontransparent (standard) data CO -14
o
output BSC trace files CO-34
o
Index
CO-2St
Index
p
PASSTHRU function, $RMU
abrupt termination CO-98
$RMUPA program CO-97
attention interrupt, use of CO-96
conduct a session CO-102
control character flow CO-100
deadlock CO-97
indefinite waits CO-98
no data record CO-108
overview CO-96
program end record CO-108
programming considerations CO-96
programs not to be run under CO-96
programs that run under CO-96
record blocking CO-108
record types CO-102, CO-104
request for data record CO-107
required fields CO-99
sample program CO-117
send request CO-99
system generation for CO-96
text/PF key record CO-104
timeouts CO-98
virtual terminal support CO-96
with $DEBUG CO-125
perform status functions, Host Communication Facility
delete record from system status data set CO-135
retrieve record from system status data set CO-135
write to system status data set CO-135
PGPIB command ($GPIBUT1) CO-226
plan for $RMU operations CO-59
point-to-point station CO-7
poll / select address CO-13
poll/select sequences, sending CO-20
post
GPIB operation complete CO-226
print
trace file on printer/terminal CO-35
program end record, PASSTHRU function of $RMU CO-108
Program Function key record, PASSTHRU function of
$RMU CO-104
programming sequence, BSCAM write operations CO-25
R
RE command
$GPIBUT1 CO-224
$HCFUT1 CO-141
read
data
data stream with BSCAM eO-28
ENQ character with BSCAM CO-28
error handling CO-29
records from host ($HCFUT1) CO-140
using $GPIBUT1 CO-224
with BSCAM CO-27, CO-28
READDATA command ($HCFUT1) CO-139
CO-2S2
SC34-0638
READOBJ command ($HCFUT1) CO-140
READ80 command ($HCFUT1) CO-140
receive
first message with BSCAM CO-27
subsequent message with BSCAM CO-27
RECEIVE function, $RMU
control character flow eO-80
overview CO-78
receive count message CO-79
receive status message eO-79
record length overrun CO-79
record padding CO-79
required fields eO-80
sample program CO-111
send empty data set CO-79
send request CO-78
specify data set type CO- 79
specify record blocking CO-79
specify starting record CO-80
terminate function eO-79
records
sizes, host data sets (HCF) CO-129
Remote Management Utility ($RMU)
allocate data sets CO-71
blocking factor
PASSTHRU data set CO-66
source data set CO-66
standard data set CO-65
BSC line address default CO-64
Bse line connections CO-59
BSCWRITE CX instruction eO-66
BSeWRITE IX instruction CO-66
buffer size default CO-55
conduct PASSTHRU session CO-102
control data transfers CO-78
control program execution CO-86
count message CO-69
data message CO-69
data transfers CO-78
delete data sets CO-74
dump storage to data set eO-76
echo host data eO-84
EDL BSe instructions, use of CO-66
error handling CO-69
establish PASSTHRU session CO-99
execute program CO-86
hardware for remote system CO-60
host programming for eO-66
host system ID CO-63
host system requirements CO-61
invoke on remote system CO-58
manage data sets CO-70
mode of transmission CO-60
overview CO-57
PASSTHRU function CO-96
perform echo test CO-84
plan for operations CO-59
receive data from host eO-78
receive data from remote system eO-82
remote system ID eO-63
o
o
o
o
o
requests, fields required CO-70
sample programs CO-l09
send data
to host CO-82
to remote system CO-78
sending messages to host CO-67
software for remote system CO-61
status error conditions CO-67
status message CO-67
storage considerations CO-60
storage size default CO-64
terminate $RMU CO-90
verify identities between systems CO-94
virtual terminals, use of CO-61
remote system
$RMU defaults CO-62
$RMU requirements CO-60
10, change ($RMU) CO-63
request
for data record, PASSTHRU function of $RMU CO-107
repeat of message with BSCAM CO-28
to $RMU, required fields CO-70
reset
GPIB adapter CO-224
respond to poll/select with BSCAM CO-28
RS command ($GPIBUT1) CO-224
s
sample programs
$RMU multifunction CO-l09
$RMU PASSTHRU function CO-117
$RMU RECEIVE function CO-lll
$RMU SEND function CO-115
for BSCAM CO-29
for channel attach CO-157
for Host Communication Facility CO-136
for Series/1-to-Series/l attachment CO-183
SE command ($HCFUT1) CO-141
send
data in standard mode with BSCAM CO-15
first message with BSCAM CO-20
poll/select sequences CO-20
subsequent messages with BSCAM CO-22
transparent data in blocks CO-15
SEND function, $RMU
send request CO-82
communications flow CO-83
control character flow CO-83
overview CO-82
receive status message CO-82
required fields CO-83
sample program CO-115
specify data set type CO-82
specify record blocking CO-82
specify starting record CO-82
terminate function CO-82
Series/1-to-Series/l attachment
$S1S1 UT1 utility CO-194
abort write operation CO-194
application programs CO-179
data transfers CO-176
define attached processor CO-195
echo test CO-195
enqueue other processor CO-180
error recovery CO-182
identify enqueued processor CO-180
IPL function CO-182
IPL other processor CO-196
obtain status of operation CO-197
overview CO-175
perform control functions CO-180
posting an event control block (ECB) CO-176
processor relationships CO-176
program synchronization CO-181
programming considerations CO-181
read data from other processor CO-196
receive data CO-180
reconfiguring CO-181
reset device CO-197
sample programs CO-183
send data CO-180
using direct I/O CO-181
write data to other processor CO-198
service request (SRQ) CO-202
SHUTDOWN function, $RMU
allocate free space CO-91
control character flow CO-93
data set passing CO-91
parameter passing CO-91
required fields CO-92
run another program CO-90
send request CO-90
specify partition CO-91
signal special conditions with BSCAM CO-23
software requirements, $RMU remote system CO-61
special write operations, BSCAM CO-23
specify
buffers for use with BSCAM CO-18
ST command ($GPIBUT1) CO-225
standard data, transmission by BSCAM CO-14
standard mode of transmission, BSCAM CO-15
status commands ($HCFUT1) CO-141
status data set, Host Communications Facility CO-130
status message, Remote Management Utility CO-67
STIMER instruction CO-97
in Series/ l-to-Series/ 1 error recovery CO-183
with PASSTHRU function CO-97
storage
considerations, $RMU CO-60
size default, ($RMU) CO-64
SU command ($GPIBUT1) CO-225
SU command ($HCFUT1) CO-141
submit
job to host ($HCFUn) CO-141
job to host, Host Communication Facility CO-135
suspend
$GPIBUTl CO-225
switched lines CO- 7
Index
CO-253
Index
system generation
for BSCAM CO-12
for BSCX21 CO-12
for channel attach CO-146
for GPIB CO-199
for Host Communications Facility CO-128
for host system, $RMU CO-61
for remote system, $RMU CO-61
for X.21 support CO-48
system status data set, HCF
data entry CO-131
index entry CO-131
key entry CO-131
organization CO-131
T
terminate Remote Management Utility CO-90
terminating GPIB operation CO-220
terminology, BSCAM CO-6
test
BSC definitions CO-38
text record, PASSTHRU function of $RMU CO-104
TP instruction
functions CO-132
trace
BSC activities CO-33
I/O on BSC line CO-33
utility for BSC CO-33
trace printing utility for BSC CO-34
transfer
data set from host ($HCFUT1) CO-139
transfer rates for data, Host Communications Facility CO-132
transmission modes, BSCAM CO-15
transmit
binary data with BSCAM CO-14
text data with BSCAM CO-14
transparent data transmission, use by BSCAM CO-14
tributary station addresses CO-13
TYPE= operand, BSCLINE statement CO-12
v
w
o
WR command ($GPIBUT1) CO-226
WR command ($HCFUT1) CO-141
WRAP function, $RMU
control character flow CO-85
overview CO-84
required fields CO-85
send request CO-84
write
data to the GPIB adapter CO-226
x
X.21 circuit switched network support
$$X21 DS data set CO-48, CO-49
$BSCTRCE utility CO-33
attaching and jumpering the 2080 card CO-48
BSCIOCB statement CO-51
BSCLINE TYPE= parameter CO-13
BSCOPEN statement CO-51
call progress signals CO-56
coding example for BSCLINE TYPE= parameter CO-49
connection record data set
building a connection record CO-50
delay value field CO-50
example records CO-51
network information field CO-50
record name field CO-50
retry count field CO-50
determining the connection type you need CO-49
device error codes CO-55
network requirements CO-48
system generation CO-48
X.21 error logging CO-52
X21 RECYY default record CO-49
X21 RN operand CO-51
2080 high speed feature card description CO-1O
X21 RECYY default record for X.21 CO-49
X21 RN operand CO-51
1·~.
U
2
verify
SSC communications CO-38
identities of systems, $RMU CO-94
virtual terminals
use with $RMU CO-61
2074 feature card CO-9
2075 feature card CO-9
2080 synchronous communications feature card
attaching and jumpeiing
description CO-1O
4
4993 channel attach device CO-146
o
CO-2S4
SC34-0638
.0
s : :i~~ Series/1 Event Driven Executive
Publications Order Form
Instructions:
Order:
1.
Complete the order form, supplying all of the
requested information. (Please print or type.)
Description
2.
If you are placing the order by phone, dial
Order
number
Reference books:
1-800-1 BM-24G8.
3.
If you are mailing your order, fold the order
form as indicated, seal with tape, and mail.
We pay the postage.
Ship to:
Name:
Address:
Communications Guide
SC34-0638
Extended Address Mode and
Performance Analyzer User Guide
SC34-0591
Installation and System Generation Guide
SC34-0646
Language Reference
SC34-0643
Library Guide and Common Index
SC34-0645
Messages and Codes
SC34-0636
Operator Commands and Utilities Reference
SC34-0644
Guides and reference cards:
o
City:
State:
Zip:
Bill to:
Customer number:
Name:
Address:
Customization Guide
SC34-0635
Event Driven Language Drogramming Guide
SC34-0637
Operation Guide
SC34-0642
Problem Determination Guide
SC34-0639
Language Reference Card
SX34-0165
Operator Commands and Utilities
Reference Card
SX34-0164
Conversion Charts Reference Card
SX34-0163
Reference Card Envelope
SX34-0166
City:
State:
Zip:
Binders:
o
Your Purchase Order No.:
3-ring easel binder with 1 inch rings
SR30-0324
Phone: (
3-ring easel binder with 2 inch rings
SR30-0327
Signature:
Standard 3-ring binder with 1 inch rings
SR30-0329
Standard 3-ring binder with 1 1/2 inch rings
SR30-0330
Standard 3-ring binder with 2 inch rings
SR30-0331
Diskette binder (Holds eight 8-inch diskettes.)
S830-0479
Date:
Oty.
I
I
I
I
Publications Order Form
~
...
c:
Q
c:"
0
l>
0::s
0
IQ
r
5'
~
Please Do Not Staple
Fold and tape
Fold and tape
.................................................................................................................................................................................... ~
111111
NO POSTAGE
NECESSARY
IF MAILED
IN THE
UNITED STATES
BUSINESS REPLY- MAIL
FIRST CLASS
PERMIT NO. 40
o
ARMONK, N.Y.
POSTAGE Will BE PAID BY ADDRESSEE:
I BM Corporation
1 Culver Road
Dayton, New Jersey 08810
.................................................................................................................................................................................... J
Please Do Not Staple
Fold and tape
Fold and tape
-
-- ------_
- -. -
®
International Business Machines Corporation
o
IBM Series/1 Event Driven Executive
Communications Guide
Order No. SC34-0638-0
o
READER'S
COMMENT
FORM
This manual is part of a library that serves as a reference source for systems analysts, programmers, and
operators of IBM systems. You may use this form to communicate your comments about this publication,
its organization, or subject matter, with the understan'ding that IBM may use or distribute whatever
information you supply in any way it believes appropriate without incurring any obligation to you.
Your comments will be sent to the author's department for whatever review and action, if any, are deemed
appropriate.
Note: Copies oflRlIJ puhlications are not stocked at the location to which this form is addressed.
Please direct allY requests for copies ofpublicatiol1s, or for assistance in using your IBM system, to
your I B1I1 represell tative or to the IBM branch office serving your locali(v.
(1)
+-'
o
Z
o
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 or you may mail directly to the address
in the Edition Notice on the back of the title page.)
I
I
I
I
I
()
SC34-0638-0
Printed in U.S.A.
C
M'
~
"'Tl
o
c:
~
o
Reader's Comment Form
:l
o
\C
C
:l
ro
Fold and tape
Fold and tape
Please Do Not Staple
I" II
NO POSTAGE
NECESSARY
IF MAILED
IN THE
UNITED STATES
BUSINESS REPLY MAIL
FIRST CLASS
PERMIT NO. 40
o
ARMONK, N.Y.
POSTAGE WILL BE PAID BY ADDRESSEE:
International Business Machines Corporation
I nformation Development, Department 28B
3405 (I nternal Zip)
P.O. Box 1328
Boca Raton, Florida 33432
Fold and tape
Please Do Not Staple
Fold and tape
- ----- ---- ---,-
-
®
o
--- - ---- ---.-_
-
---
'"
International Business Machines Corporation
SC34-0638-0
SC34-0638-0
Program Numbers : 5719-XS5 , 5719-XX6,
5719-LM6, 5719-CX1, 5799-PGH
File Number : Sl-30
Pri nted in U .S.A .
Source Exif Data:
File Type : PDF File Type Extension : pdf MIME Type : application/pdf PDF Version : 1.3 Linearized : No XMP Toolkit : Adobe XMP Core 4.2.1-c043 52.372728, 2009/01/18-15:56:37 Create Date : 2013:01:03 10:37:27-08:00 Modify Date : 2013:01:03 19:45:56-08:00 Metadata Date : 2013:01:03 19:45:56-08:00 Producer : Adobe Acrobat 9.52 Paper Capture Plug-in Format : application/pdf Document ID : uuid:06e100ea-9382-4617-87be-c62638efa407 Instance ID : uuid:53dc71a0-ae0f-4d51-abc8-69967bb36410 Page Layout : SinglePage Page Mode : UseNone Page Count : 274EXIF Metadata provided by EXIF.tools