bsc equivalence link programmingpublic.dhe.ibm.com/systems/power/docs/systemi/v5r4/en_us/...figures...

AS/400 Advanced Series IBM

BSC Equivalence LinkProgrammingVersion 4

SC41-5445-00

Take Note!

Before using this information and the product it supports, be sure to read the general information under “Notices” on page vii.

First Edition (August 1997)

This edition applies to the licensed program IBM Operating System/400 (Program 5769-SS1), Version 4 Release 1 Modification 0,and to all subsequent releases and modifications until otherwise indicated in new editions.

Make sure that you are using the proper edition for the level of the product.

Order publications through your IBM representative or the IBM branch serving your locality. If you live in the United States, PuertoRico, or Guam, you can order publications through the IBM Software Manufacturing Solutions at 800+879-2755. Publications are notstocked at the address given below.

IBM welcomes your comments. A form for readers’ comments may be provided at the back of this publication. You can also mailyour comments to the following address:

IBM CorporationAttention Department 542IDCLERK3605 Highway 52 NRochester, MN 55901-7829 USA

or you can fax your comments to:

United States and Canada: 800+937-3430Other countries: (+1)+507+253-5192

If you have access to Internet, you can send your comments electronically to [email protected]; IBMMAIL, toIBMMAIL(USIB56RZ).

When you send information to IBM, you grant IBM a nonexclusive right to use or distribute the information in any way it believesappropriate without incurring any obligation to you.

Copyright International Business Machines Corporation 1997. All rights reserved.Note to U.S. Government Users — Documentation related to restricted rights — Use, duplication or disclosure is subject torestrictions set forth in GSA ADP Schedule Contract with IBM Corp.

Contents

Notices . . . . . . . . . . . . . . . . . . . . . . viiProgramming Interface Information . . . . . . viiTrademarks and Service Marks . . . . . . . viii

About This Book . . . . . . . . . . . . . . . . ixWho Should Use This Book . . . . . . . . . . . ixPrerequisite and Related Information . . . . . ixInformation Available on the World Wide Web ix

Chapter 1. Introduction to the BinarySynchronous CommunicationsEquivalence Link . . . . . . . . . . . . . . 1-1

Remote Systems Supported . . . . . . . . . 1-1Communications Lines Supported . . . . . . 1-2Data Formats Supported . . . . . . . . . . . 1-3

Chapter 2. Configuring BSCEL . . . . . . 2-1Defining the BSCEL Configuration . . . . . . 2-1

Chapter 3. Running BSCEL . . . . . . . . 3-1Vary On and Vary Off Support . . . . . . . . 3-1

Chapter 4. Writing Application Programs 4-1Using an Intersystem Communications

Function File . . . . . . . . . . . . . . . . . . 4-1Specifying the Program Device Entry

Commands . . . . . . . . . . . . . . . . . . 4-2Comparing the Program Device Entry

Command and Configuration Parameters . 4-7Determining Record Lengths . . . . . . . . . 4-8Starting a Session . . . . . . . . . . . . . . . 4-9

Open or Acquire Operation . . . . . . . 4-10Starting a Transaction . . . . . . . . . . . . 4-10

Evoke Function . . . . . . . . . . . . . . 4-11RMTBSCEL Considerations . . . . . . . 4-11Security Function . . . . . . . . . . . . . 4-12

Sending Data . . . . . . . . . . . . . . . . . 4-12Write Operation . . . . . . . . . . . . . . 4-12Subdevice Selection Function . . . . . . 4-13End-of-Group Function . . . . . . . . . . 4-13Variable-Length-Data Function . . . . . 4-14

Receiving Data . . . . . . . . . . . . . . . . 4-14Read Operation . . . . . . . . . . . . . . 4-14Invite Function . . . . . . . . . . . . . . . 4-14Read-from-Invited-Program-Devices

Operation . . . . . . . . . . . . . . . . . 4-14Record-Identification Function . . . . . . 4-14Variable-Length-Data Function . . . . . 4-14Waiting for a Display File, an ICF File,

and a Data Queue . . . . . . . . . . . . 4-15

Notifying the Remote Program of Problems 4-15Fail Function . . . . . . . . . . . . . . . . 4-15

Using Additional Functions and Operations 4-15Request-to-Write Function . . . . . . . . 4-15Allow-Write Function . . . . . . . . . . . 4-16Cancel-Invite Function . . . . . . . . . . 4-16Timer Function . . . . . . . . . . . . . . . 4-16Get-Attributes Operation . . . . . . . . . 4-17

Ending a Transaction . . . . . . . . . . . . 4-17Detach Function . . . . . . . . . . . . . . 4-17

Ending a Session . . . . . . . . . . . . . . . 4-17Release Operation . . . . . . . . . . . . 4-17End-of-Session Function . . . . . . . . . 4-18

Using Response Indicators . . . . . . . . . 4-18Receive-End-of-Group . . . . . . . . . . 4-18Receive-Turnaround . . . . . . . . . . . 4-19Receive-Detach . . . . . . . . . . . . . . 4-19

Using the Input/Output Feedback Area . . 4-19Using Return Codes . . . . . . . . . . . . . 4-19

Chapter 5. BSCEL Considerations . . . . 5-1Program Start Request Considerations . . . 5-1

Syntax for Program Start Requests . . . . 5-1Formats for Program Start Requests . . . 5-3Continuation Format for Program Start

Requests . . . . . . . . . . . . . . . . . . 5-4Examples of Program Start Requests . . 5-4Program Start Requests Received from

Remote Systems . . . . . . . . . . . . . . 5-5Program Start Requests Sent by the

AS/400 System . . . . . . . . . . . . . . 5-6Failed Program Start Requests . . . . . . . . 5-6Prestarting Jobs for Program Start Requests 5-8Remote System Considerations . . . . . . . 5-8

BSCEL Commands . . . . . . . . . . . . . 5-9Receiving Null Records . . . . . . . . . . . 5-9Using 3740 Data Entry Systems . . . . 5-10Using Office Systems . . . . . . . . . . . 5-10

Programming Considerations . . . . . . . . 5-11BSCEL Online Messages . . . . . . . . 5-11The Reverse-Interrupt Indicator . . . . . 5-12Binary Synchronous Communications

Considerations . . . . . . . . . . . . . . 5-13

Appendix A. Language Operations, DDSKeywords, and System-Supplied Formats A-1

Language Operations . . . . . . . . . . . . . A-1Supported DDS Keywords . . . . . . . . . . A-3System-Supplied Formats . . . . . . . . . . . A-3

Copyright IBM Corp. 1997 iii

Appendix B. Return Codes, Messages,and Sense Codes . . . . . . . . . . . . . . B-1

Return Codes . . . . . . . . . . . . . . . . . . B-1Major Code 00 . . . . . . . . . . . . . . . . . B-1Major Code 02 . . . . . . . . . . . . . . . . . B-4Major Code 03 . . . . . . . . . . . . . . . . . B-7Major Code 04 . . . . . . . . . . . . . . . . . B-9Major Codes 08 and 11 . . . . . . . . . . . B-10Major Code 34 . . . . . . . . . . . . . . . . B-11Major Code 80 . . . . . . . . . . . . . . . . B-12Major Code 81 . . . . . . . . . . . . . . . . B-16Major Code 82 . . . . . . . . . . . . . . . . B-22Major Code 83 . . . . . . . . . . . . . . . . B-32

Appendix C. BSC Control Codes andProtocols . . . . . . . . . . . . . . . . . . . C-1

Appendix D. EBCDIC and ASCII CharacterSets . . . . . . . . . . . . . . . . . . . . . . D-1

EBCDIC Character Set . . . . . . . . . . . . D-1ASCII Character Set . . . . . . . . . . . . . . D-2

Appendix E. Binary SynchronousCommunications Configuration Example E-1

Configuring for BSCEL Communications . . E-1Configuring the System/36 for BSCEL

Communications . . . . . . . . . . . . . . E-1Configuring the AS/400 System for BSCEL

Communications . . . . . . . . . . . . . . E-2

Appendix F. BSCEL Application FlowExamples . . . . . . . . . . . . . . . . . . . F-1

Appendix G. Example Programs . . . . . G-1

COBOL/400 Source Program for LocalSystem . . . . . . . . . . . . . . . . . . . . . G-1

Configuration . . . . . . . . . . . . . . . . . G-1Program Files . . . . . . . . . . . . . . . . G-1Program Explanation . . . . . . . . . . . . G-5

COBOL/400 Source Program for RemoteSystem . . . . . . . . . . . . . . . . . . . . G-12

Configuration . . . . . . . . . . . . . . . . G-12Program Files . . . . . . . . . . . . . . . G-12Program Explanation . . . . . . . . . . . G-15

RPG/400 Source Program for Local System G-21Configuration . . . . . . . . . . . . . . . . G-21Program Files . . . . . . . . . . . . . . . G-21Program Explanation . . . . . . . . . . . G-24

RPG/400 Source Program for RemoteSystem . . . . . . . . . . . . . . . . . . . . G-29


ILE C/400 Source Program for LocalSystem . . . . . . . . . . . . . . . . . . . . G-36


ILE C/400 Source Program for RemoteSystem . . . . . . . . . . . . . . . . . . . . G-44


Bibliography . . . . . . . . . . . . . . . . . . H-1AS/400 Books . . . . . . . . . . . . . . . . H-1Other Related Books . . . . . . . . . . . . H-1

Index . . . . . . . . . . . . . . . . . . . . . . . X-1

iv BSC Equivalence Link Programming V4R1

Figures

1-1. BSCEL Example CommunicationsNetwork Configuration . . . . . . . . 1-3

4-1. BSCEL Control Characters ThatCannot Be Used as RecordSeparator Characters . . . . . . . . 4-5

4-2. Comparing Configuration CommandParameters and Program DeviceEntry Command Parameters . . . . 4-8

5-1. Syntax for Program Start Requests 5-15-2. Coding Positions for a Program Start

Request . . . . . . . . . . . . . . . . 5-25-3. Continuation Format for Program

Start Requests . . . . . . . . . . . . 5-45-4. *EXEC Format for Program Start

Request . . . . . . . . . . . . . . . . 5-55-5. Continuation Format for Program

Start Request . . . . . . . . . . . . . 5-55-6. Session Activity . . . . . . . . . . . 5-55-7. Reason Codes for Rejected Program

Start Requests . . . . . . . . . . . . 5-7A-1. ICF Operations Supported by

BSCEL . . . . . . . . . . . . . . . . A-1A-2. ICF Operations and Equivalent

Language Statements . . . . . . . . A-2B-1. Actions for Return Code 0000 . . . B-2C-1. BSC Line Protocols and Control

Characters . . . . . . . . . . . . . . C-1D-1. EBCDIC Character Set . . . . . . . D-1D-2. ASCII Character Set . . . . . . . . . D-2F-1. Communications between Two

AS/400 Application Programs . . . F-1F-2. Communications between an AS/400

System and a Remote Device NotUsing BSCEL . . . . . . . . . . . . . F-2

F-3. Communications between an AS/400System and a Remote System UsingMultiple Files . . . . . . . . . . . . . F-3

F-4. Starting an AS/400 System from aRemote System . . . . . . . . . . . F-4

F-5. An AS/400 System Receiving Datafrom an Office System . . . . . . . F-6

F-6. An AS/400 System Sending Data toan Office System . . . . . . . . . . . F-7

G-1. Communication between a LocalAS/400 Program and a RemoteAS/400 Program . . . . . . . . . . . G-1

G-2. DDS for the BSCELICF File Usedby the Local System (COBOL/400Language) . . . . . . . . . . . . . . G-2

G-3. DDS for the Database File Used inBSCEL Data Transfer on the LocalSystem (COBOL/400 Language) . G-3

G-4. DDS for the Printer File on the LocalSystem (COBOL/400 Language) . G-4

G-5. COBOL/400 Source Program for theLocal System . . . . . . . . . . . . . G-7

G-6. DDS for the BSCELICF ProgramFile Used by the Remote System(COBOL/400 Language) . . . . . G-13

G-7. DDS for the Database File Used inBSCEL Data Transfer Program onthe Remote System (COBOL/400Language) . . . . . . . . . . . . . G-14

G-8. DDS for the Printer File on theRemote System (COBOL/400Language) . . . . . . . . . . . . . G-14

G-9. COBOL/400 Source Program forthe Remote System . . . . . . . . G-16

G-10. DDS for the BSCELICF File Usedby the Local System (RPG/400Language) . . . . . . . . . . . . . G-22

G-11. DDS for the Database File Used inBSCEL Data Transfer on the LocalSystem (RPG/400 Language) . . G-23

G-12. DDS for the Printer File on theLocal System (RPG/400Language) . . . . . . . . . . . . . G-23

G-13. RPG/400 Source Program for theLocal System . . . . . . . . . . . . G-25

G-14. DDS for the BSCELICF ProgramFile Used by the Remote System(RPG/400 Language) . . . . . . . G-29

G-15. DDS for Database File Used inBSCEL Data Transfer Programs onthe Remote System (RPG/400Language) . . . . . . . . . . . . . G-30

G-16. DDS for the Printer File on theRemote System (RPG/400Language) . . . . . . . . . . . . . G-31

G-17. RPG/400 Source Program for theRemote System . . . . . . . . . . G-33

G-18. DDS for the SRCICFF File Usedby the Local System (ILE C/400Language) . . . . . . . . . . . . . G-37

G-19. DDS for the Database File Used inBSCEL Data Transfer on the LocalSystem (ILE C/400 Language) . . G-38

Copyright IBM Corp. 1997 v

G-20. DDS for the Printer File on theLocal System (ILE C/400Language) . . . . . . . . . . . . . G-39

G-21. ILE C/400 Source Program for theLocal System . . . . . . . . . . . . G-41

G-22. DDS for the TGTICFF File Used bythe Remote System (ILE C/400Language) . . . . . . . . . . . . . G-46

G-23. DDS for Database File Used inBSCEL Data Transfer Programs onthe Remote System (ILE C/400Language) . . . . . . . . . . . . . G-47

G-24. DDS for the Printer File on theRemote System (ILE C/400Language) . . . . . . . . . . . . . G-47

G-25. ILE C/400 Source Program for theRemote System . . . . . . . . . . G-49

vi BSC Equivalence Link Programming V4R1

Notices

References in this publication to IBM products, programs, or services do not imply that IBM intends tomake these available in all countries in which IBM operates. Any reference to an IBM product, program,or service is not intended to state or imply that only that IBM product, program, or service may be used.Subject to IBM's valid intellectual property or other legally protectable rights, any functionally equivalentproduct, program, or service may be used instead of the IBM product, program, or service. The evaluationand verification of operation in conjunction with other products, except those expressly designated by IBM,are the responsibility of the user.

IBM may have patents or pending patent applications covering subject matter in this document. The fur-nishing of this document does not give you any license to these patents. You can send license inquiries,in writing, to the IBM Director of Licensing, IBM Corporation, 500 Columbus Avenue, Thornwood, NY10594, U.S.A.

Licensees of this program who wish to have information about it for the purpose of enabling: (i) theexchange of information between independently created programs and other programs (including this one)and (ii) the mutual use of the information which has been exchanged, should contact the software interop-erability coordinator. Such information may be available, subject to appropriate terms and conditions,including in some cases, payment of a fee.

Address your questions to:

IBM CorporationSoftware Interoperability Coordinator3605 Highway 52 NRochester, MN 55901-7829 USA

This publication could contain technical inaccuracies or typographical errors.

This publication may refer to products that are announced but not currently available in your country. Thispublication may also refer to products that have not been announced in your country. IBM makes nocommitment to make available any unannounced products referred to herein. The final decision toannounce any product is based on IBM's business and technical judgment.

This publication contains examples of data and reports used in daily business operations. To illustratethem as completely as possible, the examples include the names of individuals, companies, brands, andproducts. All of these names are fictitious and any similarity to the names and addresses used by anactual business enterprise is entirely coincidental.

This publication contains small programs that are furnished by IBM as simple examples to provide anillustration. These examples have not been thoroughly tested under all conditions. IBM, therefore, cannotguarantee or imply reliability, serviceability, or function of these programs. All programs contained hereinare provided to you "AS IS". THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FORA PARTICULAR PURPOSE ARE EXPRESSLY DISCLAIMED.

Programming Interface Information

This Programming provides programming information needed to use the binary synchronous communica-tions equivalence link (BSCEL) with the AS/400 system. The BSC Equivalence Link Programming containsno programming interfaces for customers.

Copyright IBM Corp. 1997 vii

Trademarks and Service Marks

The following terms, denoted by an asterisk (*) in this publication, are trademarks of the IBM Corporationin the United States or other countries or both:

Microsoft, Windows, and the Windows 95 logo are trademarks or registered trademarks of Microsoft Cor-poration.

PC Direct is a trademark of Ziff Communications Company and is used by IBM Corporation under license.

UNIX is a registered trademark in the United States and other countries licensed exclusively throughX/Open Company Limited.

C-bus is a trademark of Corollary, Inc.

Java and HotJava are trademarks of Sun Microsystems, Inc.

Other company, product, and service names, which may be denoted by a double asterisk (**), may betrademarks or service marks of others.

Application System/400AS/400C/400COBOL/400FORTRAN/400IBM

ILEOperating System/400OS/400RPG/400Series/1400

viii BSC Equivalence Link Programming V4R1

About This Book

This book supplies the programming informationyou need to use the binary synchronous commu-nications equivalence link (BSCEL) with the IBMAS/400 system.

For a list of related publications, see the “Bibli-ography.”

Who Should Use This Book

This book is intended for application programmerswho write communications programs that useBSCEL. It has information for IBM AS/400 pro-grammers and for programmers on other systemsand devices that communicate with BSCEL on theAS/400 system.

You should be able to program in the languageyou use and be familiar with the following informa-tion:

General communications concepts. AS/400communications concepts are covered in thebook, System Operation.

AS/400 system programming terminology,mainly work station terminology.

Terminology of the remote system.

Binary synchronous communications asdescribed in the General Information—BinarySynchronous Communications, GA27-3004.

Communications configuration informationdescribed in the Communications Configura-tion.

Intersystem communications function (ICF)support described in the ICF Programming.

Prerequisite and RelatedInformation

For information about other AS/400 publications(except Advanced 36), see either of the following:

The Publications Reference book, SC41-5003,in the AS/400 Softcopy Library.

The AS/400 Information Directory, a unique,multimedia interface to a searchable databasethat contains descriptions of titles availablefrom IBM or from selected other publishers.The AS/400 Information Directory is shippedwith the OS/400 operating system at nocharge.

Information Available on theWorld Wide Web

More AS/400 information is available on the WorldWide Web. You can access this information fromthe AS/400 home page, which is at the followinguniform resource locator (URL) address:

http://www.as4ðð.ibm.com

Select the Information Desk, and you will be ableto access a variety of AS/400 information topicsfrom that page.

Copyright IBM Corp. 1997 ix

x BSC Equivalence Link Programming V4R1

Chapter 1. Introduction to the Binary SynchronousCommunications Equivalence Link

BSC Equivalence Link Programming supplies dis-tributed data processing support to the IBM* Appli-cation System/400* (AS/400*) system users whowant to communicate with a remote system ordevice using binary synchronous communications(BSC). Binary synchronous communications(BSC) is a data communications line protocol thatuses a standard set of transmission controlcharacters 1 and control character sequences tosend binary-coded data over a communicationsline. Binary synchronous communicationsequivalence link (BSCEL) support is the inter-system communications function (ICF) support onthe AS/400 system that provides binary synchro-nous communications with a remote system ordevice. BSCEL also supplies online and batchcommunications between application programs ondifferent BSC systems. AS/400 application pro-grams can be written in the Integrated LanguageEnvironment (ILE) C/400*, ILE COBOL/400*, ILEFORTRAN/400*, or ILE RPG/400* programminglanguages.

This chapter lists the remote systems, commu-nications lines, and data formats supported byBSCEL and presents an example showing anAS/400 configuration of a BSCEL communicationsnetwork.

Remote Systems Supported

BSCEL communicates with another AS/400system that has BSC or BSCEL support. You canalso use an AS/400 system with BSCEL supportto communicate with any of the following IBMsystems:

System/38 with BSC support

System/36 with SSP-ICF BSCEL support orwith SSP BSC telecommunications support

System/34 with SSP-ICF BSCEL support orwith SSP BSC telecommunications support

Systems using BSC to communicate as if theywere System/3s:

– Series/1*– System/7 with Modular System Program/7

(MSP/7)

Systems using BSC to communicate as if theAS/400 system were a System/3 terminal:

– OS/VS, or DOS/VSE with Basic Telecom-munications Access Method (BTAM)

– IBM 3705, 3720, 3725 using NetworkControl Programs (NCP), including emu-lation programs and partitioned emulationprograms

IBM 3741 Model 2 Data Station or Model 4Programmable Work Station

Systems or devices using BSC to communi-cate as if they were 3741 devices:

– IBM 5110 or 5120 Computer– IBM 5231 Data Collection Controller

Model 2 (in transmit mode only)– IBM 5260 Point-of-Sale Terminal– IBM 5280 Distributed Data System

Systems or devices using BSC to communi-cate as office systems:

– IBM 6640 Document Printer– IBM 6670 Information Distributor– 430, 440, 442, 450, and 452 Information

Processors– IBM 5520 Administrative System– IBM 6580 Displaywriter System

IBM 3747 Data Converter

IBM 3750 Switching System (except in theUnited States and Canada)

BSCEL allows you to communicate with any ofthese remote systems or devices by handling thedata passed between the AS/400 system and theremote system. BSCEL does not distinguishbetween any of these remote systems or devicesin the way it handles the data passed between theAS/400 system and the remote system. UsingBSCEL, you can start a program on the remote

1 A transmission control character is a special character included in a message to control communications over a data link.

Copyright IBM Corp. 1997 1-1

system or the remote system can start a programon the local AS/400 system.

The AS/400 system supplies a configurationoption for BSCEL to handle 3740 multiple files oroffice systems documents. BSCEL handles anycommunications line protocol needed to connectyour AS/400 system to the remote system.

BSCEL does not emulate the IBM 3780 data com-munication terminal. However, BSCEL can com-municate with devices that use 3780implementation.

BSCEL supports some of the standard features ofthe 3780 protocol, such as point-to-point commu-nications, record blocking, IRS record separatorcharacter, EBCDIC transparent text mode, andblank compression when transparent text mode isnot used. BSCEL does not support other featuresof the 3780 protocol, such as audible alarm, con-versational mode, and multipoint data link control.Refer to the book, Component Information for theIBM 3780 Data Communication Terminal, for addi-tional information about the features of the 3780terminal.

The user program must handle any unique consid-erations for remote system data streams.

Communications LinesSupported

The AS/400 system can have more than one BSCcommunications line active at the same time.Each communications line is identified by one ofthe following types (all lines do not have to be thesame type):

Point-to-point switched

– Manual answer – Automatic answer – Manual dial

– Automatic dial

Point-to-point nonswitched

Multipoint tributary

By using point-to-point communications lines:

BSCEL supports only one communicationssession at a time on each line.

A communications program, using BSCEL,cannot share a communications line withanother communications program.

By using multipoint tributary communications lines:

BSCEL supports more than one communica-tions session on each line. (Each commu-nications session is associated with a differentBSC device description.)

BSCEL can share a communications line withanother communications program.

A communications program can conduct morethan one session at the same time on a multipointtributary line if each session uses a different BSCdevice description. A communications programcan conduct more than one session at the sametime, each on a different point-to-point line, if eachsession uses a different BSCEL configuration.

A communications program can also conduct ses-sions consecutively on one line. After one sessionends, another session on the same line can bestarted immediately. However, in any session,only one transaction is active at a time. Onetransaction must end before another one begins.(Transactions are discussed in “Starting aTransaction” on page 4-10.)

Figure 1-1 is an example of a BSCEL networkthat connects the AS/400 system and remotesystems with various line types. (For informationon creating a BSCEL configuration, seeChapter 2, and the CommunicationsConfiguration.)

1-2 BSC Equivalence Link Programming V4R1

System/36

Tributary Tributary

Host

System

Remote Systems

Multipoint

Nonswitched

BSCEL

BSCEL

CPF

Point-to-Point

Switched

Point-to-Point

Switched

BSCEL

BSC Communications

Support

Your Program

System/38

AS/400

System

ICF Data Management

AS/400 System

Point-to-Point

Nonswitched

RSLS351-7

Figure 1-1. BSCEL Example Communications Network Configuration

Data Formats Supported

BSCEL supports the following data formats. (Forinformation about data formats and how they arespecified, see “Comparing the Program DeviceEntry Command and Configuration Parameters”on page 4-7 and “Specifying the Program DeviceEntry Commands” on page 4-2.)

Data records that are not blocked either intransparent text mode 2 or not in transparenttext mode

Blocked data records in either transparent textmode or not in transparent text mode

Blocked data records with record separatorsnot in transparent text mode

Blocked data records with intermediate-text-block (ITB) characters not in transparent textmode

Blocked data records with blank compressionnot in transparent text mode

Blocked data records with blank truncation ineither transparent text mode or not in trans-parent text mode

3740 multiple files (with null records sepa-rating the files)

Office systems, with end-of-text (ETX) controlcharacters separating the documents

Use the same data format for both the sendingand receiving systems. (Data formats aredescribed in detail in “Syntax for Program StartRequests” on page 5-1.)

BSCEL also supplies EBCDIC and ASCII trans-lation. (You must specify EBCDIC or ASCII as thevalue of the CODE parameter on the Create LineDescription for BSC (CRTLINBSC) command.)

2 A method of transmission in which only transmission control characters preceded by the DLE control character are processed astransmission control characters.

Chapter 1. Introduction to BSCEL 1-3

The AS/400 system processes all data in EBCDICcharacters.

If the remote system uses ASCII characters,BSCEL translates the following characters:

Output data to ASCII, before sending it to theremote system

Input data from the remote system toEBCDIC, before passing it to the AS/400 com-munications program.


Chapter 2. Configuring BSCEL

This chapter describes the commands used forconfiguring BSCEL.

When using BSCEL configuration commands, youcan enter the commands in one of two ways:

Using the command prompt. Enter thecommand and press F4 (Prompt). A promptmenu is shown for the command.

Using direct entry. Enter the command andits parameters following the syntax describedin the CL Reference book.

The following is a brief introduction of the com-mands you use to configure BSCEL. For a com-plete description of these and related commands,see the Communications Configuration book andthe online help.

Defining the BSCELConfiguration

The AS/400 system with BSCEL support permitscreating and storing many BSCEL configurationdescriptions on the system. Each configurationdescription name must be unique. On a point-to-point line, only one BSCEL configuration can beactive at a time. On a multipoint line, multipleBSCEL configurations can be active.

A BSCEL configuration consists of a BSC line,controller, and device description. You createthese descriptions using the following commandsin the order listed:

Create Line Description (BSC) (CRTLINBSC) Create Controller Description (BSC)

(CRTCTLBSC) Create Device Description (BSC)

(CRTDEVBSC)

The Retrieve Configuration Source (RTVCFGSRC)command can also be used to retrieve CLcommand source to create existing configurationobjects.

The Rename Object (RNMOBJ) command can beused to change the name of a configuration objectin a library.

To change one or more of the attributes of aBSCEL configuration, use the following com-mands:

Change Line Description (BSC) (CHGLINBSC) Change Controller Description (BSC)

(CHGCTLBSC) Change Device Description (BSC)

(CHGDEVBSC)

Certain parameters for the configuration com-mands can only be changed when the configura-tion description is varied off. If the configurationdescription is varied off to make changes, youmust vary on the configuration description afterthe changes are made. This permits using thenew attributes for your session.

To display the status of the line, controller, anddevice descriptions for BSCEL, use the Work Con-figuration Status (WRKCFGSTS) command. Thiscommand allows you to determine if the BSC lineis available for use. The Retrieve ConfigurationStatus (RTVCFGSTS) command can also beused.

To delete a BSCEL configuration description, usethe following commands:

Delete Line Description (DLTLIND) Delete Controller Description (DLTCTLD) Delete Device Description (DLTDEVD)


Chapter 3. Running BSCEL

This chapter contains the information you need torun BSCEL.

Vary On and Vary Off Support

Once BSCEL is configured, you can use the VaryConfiguration (VRYCFG) command to activate anddeactivate the line, controller, and devicedescriptions used by BSCEL.

The VRYCFG command prepares the localAS/400 system to communicate with the remotesystem. The remote system must also be pre-pared to communicate with the AS/400 system.

Use the VRYCFG command and specifySTATUS(*ON) to vary on the configurationdescriptions. On a multipoint line, the AS/400system automatically responds when it is selectedor polled after the line description, controllerdescription, and device description are varied on.

Use the VRYCFG command and specifySTATUS(*OFF) to vary off the configureddescriptions. When you vary off a configuration,the association between BSCEL and the commu-nications line is broken. There are no more userprogram communications on the line.

For additional information concerning the VaryConfiguration (VRYCFG) command, refer to theCommunications Management book.

The VRYCFG command has the following param-eters (the default values are underlined):

CFGOBJSpecifies the name of the description for theline, controller, or device to be varied on or offor a list of names of configuration elements ofthe same description type, such as line, con-troller, or device.

CFGTYPESpecifies the type of configuration descriptionto be varied on or off.

*LIN: The line is varied.

*CTL: The controller is varied.

*DEV: The device is varied.

STATUSSpecifies the status to which the configurationobject is to be varied.

*ON: The object is varied on.

*OFF: The object is varied off.

RANGESpecifies what configuration elements shouldbe varied, such as only the configurationelement specified (*OBJ) or the configurationelement specified and its attached configura-tion elements (*NET). For lines, the attachedconfiguration elements are controllers anddevices. For controllers, the configuration ele-ments are devices. Devices are considerednot to have attached configuration elements.For devices, there is no difference betweenspecifying RANGE(*OBJ) or RANGE(*NET).

*NET: All downline attached configurationelements are varied.

*OBJ: Only the specified objects are varied.

VRYWAITSpecifies whether the BSC line description isvaried on asynchronously or synchronously.Specify how long the system waits for vary onto be completed (for synchronous vary on)after which the communications file is openedand the session is acquired.

*CFGOBJ: The VRYWAIT parameter valuespecified in the line description is used.

*NOWAIT: The system does not wait for varyon completion. The line is varied on asyn-chronously.

vary-on-wait: Specify a value ranging from 15through 180 seconds in 1-second intervals.The system waits until either the line is variedon or the timer expires before completing theVRYCFG command.

ASCVRYOFFSpecifies whether the vary off is asynchro-nous. This parameter is not allowed whenSTATUS(*ON) is specified.

*NO: The vary off is synchronous.

*YES: The vary off is asynchronous.


RESETSpecifies if a reset is to be done for theinput/output processor (IOP) associated withthe object.

*NO: The associated IOP is not reset.

*YES: The associated IOP is reset.


Chapter 4. Writing Application Programs

This chapter describes the BSCEL parametersused to define an intersystem communicationsfunction (ICF) file, as well as how to use commu-nications operations and functions to:

Start and end a communications session Start and end a communications transaction Send and receive data Notify your program of errors Use response indicators

This chapter also discusses the input/output (I/O)feedback area (which contains the results of readand write operations) and return code processing.

Using an IntersystemCommunications Function File

The intersystem communications function(ICF) is a function of the operating system thatallows a program to communicate interactivelywith another program or system. An ICF file mustbe created before your application can useBSCEL. The ICF file is used to describe howdata is presented to the program with which yourprogram is communicating, and how data isreceived from that program. If you are using datadescription specifications (DDS) keywords, use theCreate Intersystem Communications Function File(CRTICFF) command to create an ICF file. If youare using the system-supplied formats (such as$$SEND), you do not need to create an ICF file.The ICF file QICDMF, which is in the libraryQSYS, is supplied by IBM for communications.Appendix A provides a list of the DDS keywordsand system-supplied formats supported byBSCEL.

The ICF file is a system object of type *FILE witha specific user interface. This interface is madeup of a set of commands and operations. Thecommands allow you to manage the attributes ofthe file and the operations allow a program to usethe file. Commands allow you to create, delete,change and display the file description.

The following commands are valid for BSCEL, andare described in detail in the ICF Programmingbook.

CRTICFF The Create ICF File commandallows you to create an ICF file.

CHGICFF The Change ICF File commandallows you to change the file attri-butes of the ICF file.

OVRICFF The Override ICF File commandallows you to temporarily changethe file attributes of the ICF file atrun time. These changes are onlyin effect for the duration of the joband do not affect other users ofthe file.

DLTF The Delete File command allowsyou to delete a file from thesystem.

DSPFD The Display File Descriptioncommand displays the filedescription of any file on thesystem. This information may beprinted or displayed.

DSPFFD The Display File Field Descriptioncommand displays the descriptionof the fields in any file on thesystem. This information may beprinted or displayed.

ADDICFDEVE The Add ICF Device Entrycommand allows you to perma-nently add a program device entrythat contains a program devicename, remote location informa-tion, and session level attributesto an ICF file.

CHGICFDEVE The Change ICF Device Entrycommand allows you to perma-nently change the program deviceattributes previously added withthe ADDICFDEVE command.

OVRICFDEVE The Override ICF Device Entrycommand allows you to:

Temporarily add the programdevice entry, the remotelocation information, and thesession level attributes to theICF file.

Temporarily change aprogram device entry with the


specified remote locationinformation and session levelattributes for an ICF file.These changes are only ineffect for the job.

RMVICFDEVE The Remove ICF Device Entrycommand allows you to perma-nently remove the program deviceentry previously added to an ICFfile with the ADDICFDEVEcommand or changed with theCHGICFDEVE command.

Specifying the Program DeviceEntry Commands

The following describes the parameters for theADDICFDEVE, CHGICFDEVE, and OVRICFDEVEcommands and lists the valid values for eachparameter for BSCEL. The default values areunderlined.

FILESpecifies the name and library of the ICF fileto which you are adding or changing theprogram device entry. The FILE parameter isnot available on the OVRICFDEVE command.

*LIBL: BSCEL uses the library list to locatethe ICF file.

*CURLIB: BSCEL uses the current library forthe job to locate the ICF file. If no currentlibrary entry exists in the library list, BSCELuses QGPL.

library-name: A 1- to 10-character value thatspecifies the library where the ICF file islocated.

filename: A 1- to 10-character value thatspecifies the name of the ICF file.

PGMDEVSpecifies the program device name beingdefined in the ICF file. The total number ofprogram devices that can be added (andactive) to an ICF file is determined by theMAXPGMDEV parameter on the CRTICFF orCHGICFF command. Specify a programdevice as follows:

program-device-name: A 1- to 10-charactervalue that specifies the program device namebeing defined. This name is used on device-

specific input and output operations to identifythe program device and the attributes. Thisprogram device name must be uniquethroughout the entries for the ICF file. BSCELallows only one program device name foreach remote location to be active in the file atone time.

RMTLOCNAMESpecifies the remote location name with whichyour program communicates.

*REQUESTER: The name used to refer tothe communications device through which theprogram was started. The session that isassigned when the program device is acquiredis the same session that receives the remoteprogram start request. If the program is notstarted as a result of a program start request,the acquire operation for the program devicefails. The target program , the program thatis started on the remote system at the requestof the source system, always uses*REQUESTER as the remote location name inthe ICF file to connect to the session that thesource program , the program that starts asession with a remote system, uses to sendthe program start request. You can specify*REQUESTER only once in the file.*REQUESTER is valid only for a target com-munications job. If you specify *REQUESTERin any other type of job, an escape messageis sent when the program device is acquired.There is no default for this parameter.

remote-location-name: A 1- to 8-charactervalue that specifies the name of the remotelocation with which your source program iscommunicating. This name is used by theAS/400 system and matches theRMTLOCNAME parameter in the CreateDevice Description for BSC (CRTDEVBSC)command. The remote location does notneed to exist at the time these commands run,but must exist (the configuration descriptionthat contains this RMTLOCNAME must bevaried on) at the time the program acquiresthe program device. You may add a givenremote location name many times using dif-ferent program device names. When aprogram is running, only one program devicename associated with each BSCEL remotelocation may be acquired to the file at any onetime.


FMTSLTSpecifies the record format selection used forinput operations.

*PGM: The program determines what recordformats are selected. If an input (read) opera-tion with a record format name is specified,that format is always selected. If an inputoperation without a record format is specified,the default format (the first record format inthe file) is always selected. This also meansthat if there are any record identification(RECID) keywords specified in the datadescription specifications (DDS) for the file,they are not taken into consideration when therecord is selected.

*RECID: The RECID keywords specified inDDS for the file are used to specify recordselection. If there are no RECID keywords inthe file, an error message is sent and theacquire operation for the program device fails.

*RMTFMT: BSCEL does not support thisvalue. If you specify this value, the acquireoperation for the program device fails.

CMNTYPESpecifies which type of communicationsparameters show on the prompt screen. Thisparameter is used only for the purpose ofprompting. You should specify the value*BSCEL or *ALL for this parameter.

*BSCEL: The prompt for allBSCEL-supported attributes.

Note: When you specify *REQUESTER forthe remote location name (RMTLOCNAME),you are only prompted for the attributes of theformat select parameter (FMTSLT) and thesecure from override parameter (SECURE).

BLOCKSpecifies whether the system or the userblocks and deblocks transmitted records.With this parameter, you can specify one ofthe following conditions for record formatting:

No blocking/deblocking: The recordformat described in the ICF file is theformat for both the record and the block.

User blocking/deblocking: You mustprovide the BSC controls needed todescribe the record format to the system.

System blocking with record separatorcharacters: You specify the record sepa-

rator character used by the system todetermine record boundaries within theblock.

System blocking of fixed-length records:The system uses fixed-length records, andblocks and deblocks records accordingly.

Specify these conditions as follows:

*DEVD: BSCEL uses the block option speci-fied in the device description. The block infor-mation in the device description is specified inthe BLOCK parameter and the SEPCHARparameter of the CRTDEVBSC command andthe CHGDEVBSC command.

*NONE: Blocking and deblocking are notdone by the system.

*ITB: Records are blocked or deblockedbased on the location of an intermediate-text-block (ITB) character . This control char-acter divides a block of text into smallergroups of text for an intermediate block check.For input files, a record is delimited bylocating the next ITB character. An end-of-text (ETX) or end-of-transmission-block (ETB)character is used also as an ITB character todelimit a block. An end-of-text (ETX) char-acter is a BSC transmission control characterused to end a logical set of records thatbegan with the start-of-text character. Anend-of-transmission-block (ETB) characteris a BSC transmission control character usedto end a block of records. For output files, anITB character is added after the record. If it isthe last character of the block, the ITB isreplaced by an ETX or ETB character.

*IRS: Records are blocked or deblockedbased on the location of an interrecord-separator (IRS) character. The interrecord-separator (IRS) character is a transmissioncontrol character used to separate recordswithin a block of data. For input files, a recordis delimited by locating the next IRS character.For output files, an IRS character is addedafter the record.

*NOSEP: A record separator character is notcontained in the block that is sent to orreceived from the device. The system blocksand deblocks the records using a fixed-lengthrecord, as specified in the ICF file formatspecifications.

Chapter 4. Writing Application Programs 4-3

*USER: Your program provides all controlcharacters (including record separator charac-ters, BSC framing characters, and transpar-ency characters) necessary to send records.

When sending records, BSCEL scans thebuffer for the last non-blank byte to determinethe length of the data to be sent. For thisreason, you must make sure that the unusedportion of the buffer contains blanks, or anerror occurs.

When receiving records, you must be awarethat the received text ends with an ETB or anETX control character. BSCEL pads theremaining buffer space with blanks. Thismethod of blocking allows you to send andreceive variable-length data blocks by using asingle record format capable of accommo-dating the maximum block length. Except forpadding and truncating with blanks, BSCELpasses the data to and from the system whenuser blocking is specified. Before selectingthis option, you should understand BSC meth-odology. You cannot specify BLOCK(*USER)when you specify RMTBSCEL(*YES).

BLOCK(*USER) specifies that the applicationprogram will fully construct a transmissionblock (including all record separators, BSCframing characters, transparency characters,and so on). The data in the user’s buffer on awrite operation will be transmitted as a singletransmission block, unaltered except for theadding of leading pad characters, synchroni-zation characters, block check characters,trailing pad characters, and data-link-escape(DLE) character 1 insertions (as required fortransparent mode). In addition, BSCELsupport removes all trailing blanks in thebuffer before sending the data. Therefore, thelast non-blank character in the buffer must bea valid BSC end frame character.

When receiving data with BLOCK(*USER)specified, the data received is passed to theapplication program unaltered, except for theremoval of the BSC pad characters, synchro-nization characters, block check characters,and transparency control DLE characters(unless the DLE precedes an STX). Any

trailing bytes in the buffer are filled withblanks.

The transparency selection(TRNSPY(*YES/*NO)) is ignored whenBLOCK(*USER) is specified. To effect trans-parent transmission of a block of data, theapplication program must prefix the block withDLESTX. BSC support will insert any addi-tional DLE characters required in the block.Any other DLEs (except for the first DLE) aretreated as data characters by the BSCsupport.

Variable length transmission blocks arenormally required when using theBLOCK(*USER) option. Therefore, the recordformat used on write operations should belarge enough to contain the maximum blocksize to be written. The application programmust ensure that all trailing bytes are blanks.BSCEL support then truncates all bytes in thebuffer following the ETB or ETX to determinethe number of bytes to transmit.

When using BLOCK(*USER), BSCEL uses*EOT for the value of the GRPSEP parameter;therefore, it is the responsibility of the applica-tion program to construct or recognize datagroup boundaries.

The BLOCK(*USER) option must be used tosend header (SOH) data or to recognize thereceipt of header data. All other BLOCKoptions treat an SOH as an STX.

*SEP: Records are blocked or deblockedbased on the location of a user-specifiedrecord separator character. For input files, arecord is delimited by locating the next recordseparator character. For output files, a recordseparator character is added after the record.

record-separator-character: A value thatspecifies a unique, 1-byte record separatorcharacter. This value corresponds to theSEPCHAR parameter on the CRTDEVBSCcommand and the CHGDEVBSC command.The record separator character can be speci-fied as 2 hexadecimal characters, as inBLOCK(*SEP FD), or the character can bespecified as a single character by specifying avalue ranging from 0 to 9 or A to F, as in

1 A BSC transmission control character used to indicate that the next character is a control character, not a data character.


BLOCK(*SEP A). If a record separator char-acter is not specified, BSCEL uses the recordseparator character hex 1E.

Do not use the following BSC control charac-ters as record separator characters:

Note: Do not use hex 00 as a record sepa-rator character for a session in which a sourceprogram starts a target program. (An evokefunction or a program start request can beused to start a target program.) If you usehex 00 as a record separator character,BSCEL uses *NOSEP as the value of theBLOCK parameter. The value *NOSEP indi-cates that fixed-length record blocking is used.

If you specify any BLOCK parameter valueother than *NONE or *USER, records areblocked as required by the system for outputand are deblocked on input.

Blocking can be done with or without recordseparator characters. If you specifyTRNSPY(*YES), the records can be blockedwithout record separator characters by speci-fying BLOCK(*NOSEP), or the records can betransmitted one record at a time by specifyingBLOCK(*NONE). By specifyingBLOCK(*USER), you can block records toinclude the BSC transparency controls.

If you specify TRNSPY(*NO), all blockingoptions are valid. The record length, when

used, is obtained from the ICF file. Amaximum of 512 records are blocked fortransmitting. When the system blocks anddeblocks the records, record separator char-acters and control characters are not passedto your program as data.

RCDLENSpecifies the maximum record length (inbytes) for data sent and received. If a recordis longer than the specified maximum recordlength, an error occurs when you send orreceive the record.

*DEVD: BSCEL uses the record length fromthe device description.

record-length: A value that specifies thelength of the longest record you expect tosend or receive in this session. Valid valuesare 1 to 8192. For additional informationabout determining the record length of data,refer to “Determining Record Lengths” onpage 4-8.

BLKLENSpecifies the maximum block length (in bytes)for data sent and received. The block lengthmust be at least as long as the record length(RCDLEN) and cannot be greater than themaximum buffer size (MAXBUFFER) specifiedwith the line description (CRTLINBSCcommand). BSCEL checks to ensure that themaximum block length meets these require-ments. If it does not, BSCEL fails the acquireoperation for the current session ifRMTBSCEL(*YES) is specified. BSCEL failsthe first input or output operation ifRMTBSCEL(*NO) is specified.

*DEVD: BSCEL uses the block length fromthe device description (CRTDEVBSCcommand).

block-length: A value that specifies the lengthof the largest block of data records you expectto send and receive in this session. Validvalues are 1 to 8192. This value does notinclude record separator characters whenblocking is used. However, because somereceiving devices can include those charactersin the count, you might have to either lowerthe BLKLEN value at the AS/400 system orraise the value (if possible) at the remotesystem or device to match the device require-ments and the operating environment.

Figure 4-1. BSCEL Control Characters ThatCannot Be Used as Record Separator Characters

EBCDIC(Hex)

ASCII(Hex)

BSC Control Characters

01 01 SOH (start-of-header)02 02 STX (start-of-text)03 03 ETX (end-of-text)10 10 DLE (data-link escape)1D 1D IGS (interchange group

separator)1F 1F ITB (intermediate group

separator)26 17 ETB (end-of-transmission

block)2D 05 ENQ (enquiry)32 16 SYN (synchronization)37 04 EOT (end-of-

transmission)3D 15 NAK (negative acknowl-

edgement)


In addition to the record separator character,the following BSC control characters are notincluded when determining the block length:

STX ETX ETB SYN PAD DLE BCC

TRNSPYSpecifies if data is sent in transparent textmode. Transparent text mode allows you tosend all 256 extended binary-coded decimalinterchange code (EBCDIC) character codes.Use this function when sending packed orbinary data fields or data fields that containcharacters that duplicate BSC control charac-ters.

*DEVD: BSCEL uses the text transparencyoption specified in the device description(CRTDEVBSC command).

*NO: Text transparency is not used.

*YES: Text transparency is used.

You cannot specify TRNSPY(*YES) when youspecify CODE(*ASCII) on the Create LineDescription for BSC (CRTLINBSC) command.If you do, BSCEL fails the acquire operationfor the current session if RMTBSCEL(*YES) isspecified. BSCEL fails the first input or outputoperation if RMTBSCEL(*NO) is specified.

You can only specify TRNSPY(*YES) whenyou specify BLOCK(*NONE),BLOCK(*NOSEP), or BLOCK(*USER). Thisparameter is not relevant for received datasince the data stream determines the trans-parency of received data.

If you specify TRNSPY(*YES) withBLOCK(*USER), BSCEL ignores the transpar-ency indicator during write operations. Youmust give the correct controls in the data tosend transparent data, which can contain anyhexadecimal value. For example, you mustfirst specify the data-link-escape (DLE) andstart-of-text (STX) control characters. Thesystem provides the remaining control charac-ters for transparent data transmission.

DTACPRSpecifies if blanks in the data are compressedfor output and decompressed for input.

*DEVD: BSCEL uses the data compressionoption specified in the device description(CRTDEVBSC command).

*NO: Blanks in the data are not compressedor decompressed.

*YES: Blanks in the data are compressedand decompressed. Data must not containthe inter-group separator (IGS) character(value hex 1D).

If you specify DTACPR(*YES) when youspecify BLOCK(*USER), BSCEL ignores thedata compression indicator. You cannotspecify DTACPR(*YES) when you specifyTRNSPY(*YES) or BLOCK(*ITB). If you do,BSCEL issues an error message when youattempt the acquire operation.

TRUNCSpecifies if trailing blanks are truncated fromoutput records.

*DEVD: BSCEL uses the truncation optionspecified in the device description(CRTDEVBSC command).

*NO: Trailing blanks are not truncated fromoutput records.

*YES: Trailing blanks are truncated fromoutput records.

If you specify TRUNC(*YES) when you specifyBLOCK(*USER) or DTACPR(*YES), BSCELignores the truncation indicator. You cannotspecify TRUNC(*YES) with BLOCK(*NOSEP)or BLOCK(*ITB). If you do, BSCEL issues anerror message when you attempt an acquireoperation.

GRPSEPSpecifies a separator for groups of data (theseparator follows the last data record in thegroup).

*DEVD: BSCEL uses the group separatoroption specified in the device description(CRTDEVBSC command).

*EOT: An end-of-transmission (EOT) controlcharacter follows the last data record. Anend-of-transmission (EOT) character is thecontrol character used to end transmissionwith the remote system.


*DEV3740: A null record (STXETX) followsthe last data record.

*OFCSYS: An end-of-text (ETX) control char-acter follows the last data record.

If you specify BLOCK(*USER), BSCEL uses*EOT for the value of the GRPSEP parameter.If you specify either *DEV3740 or *OFCSYS,BSCEL ignores this value whenBLOCK(*USER) is specified.

RMTBSCELSpecifies the type of BSCEL session with theremote system.

*DEVD: BSCEL uses the remote sessionvalue specified in the device description(CRTDEVBSC command).

*NO: The remote system cannot recognizeBSCEL commands or messages. Forexample, the remote system is a 3741 DataEntry Station, an Office System, a 5230 DataCollection System, or a System/38.

*YES: The remote system can recognize theBSCEL transaction starting commands, trans-action ending commands, and online mes-sages. For example, the remote system isanother AS/400 system, a System/36, or aSystem/34 with BSCEL support.

INLCNNSpecifies how the connection is made on thecommunications line for the session beingstarted. This parameter applies only toswitched communications lines.

*CTLD: BSCEL uses the switch type speci-fied in the controller description (CRTCTLBSCcommand).

*DIAL: The local system starts the call (theremote system answers).

*ANS: The local system answers the call (theremote system calls).

SECURESpecifies if this program device is protectedfrom the effects of override commands atlower call levels. (This parameter is specifiedonly on the OVRICFDEVE command.)

*NO: This program device override is not pro-tected from other program device overrides.Its values can be overridden by any programdevice override commands at lower call levels.

*YES: This program device override is pro-tected from other program device overrides.Its values cannot be overridden by anyprogram device override commands at lowercall levels.

Comparing the Program DeviceEntry Command andConfiguration Parameters

The parameter values from the configuration com-mands are used for any BSCEL session in anyICF file, unless those values are changed by theprogram device entry commands.


Figure 4-2. Comparing Configuration Command Parameters and Program Device Entry Command Parameters

Description Configuration Command Parameter

Program DeviceEntry CommandParameter

File and library name – FILE1Program device name – PGMDEVRemote location name RMTLOCNAME RMTLOCNAME2Format selection processing forinput – FMTSLTCommunications type – CMNTYPEBlock information BLOCK BLOCKRecord separator character SEPCHAR BLOCKMaximum user record length RCDLEN RCDLENMaximum block length BLKLEN BLKLENTransparency TRNSPY TRNSPYData compression indicator DTACPR DTACPRTrailing blanks truncated TRUNC TRUNCSeparator for groups of data GRPSEP3 GRPSEP3Remote session indicator RMTBSCEL RMTBSCELSwitch type for session start INLCNN4 INLCNNSecure from override indicator – SECURE5 1 This parameter is only valid on the ADDICFDEVE and CHGICFDEVE commands.

2 If you specify RMTLOCNAME(*REQUESTER) on the command, BSCEL ignores any of the data format parametersyou specify, as well as the INLCNN parameter. (Data format parameters are BLOCK, SEPCHAR, RCDLEN,BLKLEN, TRNSPY, DTACPR, TRUNC, GRPSEP, and RMTBSCEL.) Instead, the remote program start requestdetermines the data format parameters for this session.

If you intend to use the default device description value (*DEVD) for other parameters, you must specify the sameremote location name for the configuration parameter and the program device entry parameter.

3 The value of the GRPSEP parameter cannot be specified on a remote program start request. The local andremote systems are each responsible for setting this value correctly before the program start request is sent by thesource program.

4 You specify this parameter when you create the controller description (CRTCTLBSC command).

5 This parameter is only valid on the OVRICFDEVE command.

Figure 4-2 shows the relationship between theBSCEL parameters for the program device entrycommands (ADDICFDEVE, CHGICFDEVE, andOVRICFDEVE) and the configuration commands.If there is no configuration parameter that corre-sponds to a program device entry parameter, it ismarked with a dash (–). Except where noted, youspecify all configuration parameters when youcreate the device description (CRTDEVBSCcommand).

The ADDICFDEVE and CHGICFDEVE programdevice entry commands cause permanentchanges for any BSCEL session that uses thespecified program device. The OVRICFDEVEprogram device entry command causes job-levelchanges (as long as the OVRICFDEVE command

remains in effect) for any BSCEL session thatuses the specified program device.

For additional information about the relationship ofthese commands, refer to the ICF Programming.

Determining Record Lengths

The record length for an output operation is deter-mined by the record format specified.

If you are using user-defined formats, therecord length is determined by the record defi-nition in the ICF file. You can use theVARLEN keyword to change the length of thedata being sent. If you use VARLEN, thevalue specified for the variable length cannot


be greater than the length of the record defi-nition.

If you are using system-supplied formats, youspecify the length in the first four bytes of thedata.

The record length for an input operation is deter-mined by the record format specified.

If you are using user-defined formats, eitheryou specify the record format in your program,or it is selected by the system, based on theinput data. You must ensure that your ICF filehas a default format with a length equal to thelongest record you expect your program toreceive.

If you are using system-supplied formats andthe system-supplied QICDMF ICF file, theinput length is always 4096, unless you over-ride or change the MAXRCDLEN parameteron the OVRICFF or CHGICFF commands.

After the record length is determined, it is checkedfor errors as follows:

The record length must not be greater thanthe maximum record length (MAXRCDLEN)value specified on the CRTICFF or OVRICFFcommand.

The record length must not be greater thanthe application program's maximum recordlength.

The record length must not be greater thanthe maximum user record length (RCDLEN)for the communications session. You specifythe value for the RCDLEN parameter on theCRTDEVBSC, CHGDEVBSC, ADDICFDEVE,CHGICFDEVE, and OVRICFDEVE com-mands.

The record length must not be greater thanthe maximum block length (BLKLEN), if recordblocking is used for the communicationssession. You specify the value for theBLKLEN parameter on the CRTDEVBSC,CHGDEVBSC, ADDICFDEVE, CHGICFDEVE,and OVRICFDEVE commands.

The record length must not be greater thanthe maximum buffer size (MAXBUFFER) forthe communications session. You specify thevalue for the MAXBUFFER parameter on theCRTLINBSC and CHGLINBSC commands.

Following are specific return codes your programcan receive for record length errors:

Return code 3401 on an input operation, whenthe length of data received is greater than therecord length for the input operation.

Return code 8187 on an input or output oper-ation, when the maximum user record length(RCDLEN), or the maximum block length(BLKLEN) is greater than the maximum buffersize (MAXBUFFER) and RMTBSCEL(*NO) isspecified. See “RMTBSCEL Considerations”on page 4-11 for information on how tospecify RMTBSCEL(*NO).

Return code 8287 on an acquire operationwhen the maximum user record length(RCDLEN), or the maximum block length(BLKLEN) is greater than the maximum buffersize (MAXBUFFER), and RMTBSCEL(*YES)is specified. See “RMTBSCELConsiderations” on page 4-11 for informationon how to specify RMTBSCEL(*YES).

Return code 828B on an acquire operationwhen the maximum user record length(RCDLEN) is greater than the maximum blocklength (BLKLEN).

Return code 831F on an output operation,when the record length is greater than themaximum record length (MAXRCDLEN), orthe record length is greater than the applica-tion program's maximum record length, or therecord length is greater than the maximumuser record length (RCDLEN).

If your program cannot specify a record lengththat is large enough to receive the data, youmust end your program and change either therecord length associated with the input opera-tion, or the value of the RCDLEN parameter.

Starting a Session

A communications session is a logical connectionbetween two systems through which a localprogram can communicate with a program at aremote location. A communications session isestablished with an acquire operation and isended with a release operation or end-of-sessionfunction.


Open or Acquire Operation

Your program must open an ICF file and acquire aprogram device before it can direct any input oroutput operations to the program device. Onlyprogram devices defined to the file by theADDICFDEVE, CHGICFDEVE, or OVRICFDEVEcommand can be acquired.

You can acquire a program device implicitly usingthe open operation or explicitly using the acquireoperation. The acquire operation is performedautomatically as part of the open operation if youspecify a program device name or theACQPGMDEV parameter for the ICF file on theCRTICFF, CHGICFF, or OVRICFF command. Fora description of the open operation, see the ICFProgramming.

Source Program: In a source program, afteropening the ICF file, use an acquire operation tostart the session. The program device name onthe acquire operation identifies the session andmust match the program device name specified inan associated ADDICFDEVE, CHGICFDEVE, orOVRICFDEVE command. Any values specifiedfor the data format parameters on theADDICFDEVE, CHGICFDEVE, or OVRICFDEVEcommand are used for the session.

For a point-to-point line, the acquire operationreserves the local AS/400 system line. Once yourprogram starts the session, no other local AS/400program can start a session on that line until yoursession ends. If you specify RMTBSCEL(*YES)for your session and the remote system is alsousing BSCEL, the communications line is reservedat the remote system. While this line is reserved,no other remote program can start a session onthis line until your session ends.

If you specify RMTBSCEL(*YES) for your sessionand you are using a switched line, the switchedconnection is made when the acquire operation isprocessed. If you specify RMTBSCEL(*NO) foryour session using a switched line, the connectionis made when the first input or output operation isprocessed.

For a multipoint line, your program or other localAS/400 programs can start more than one session

on the local AS/400 line. However, each sessionmust be directed to a different device description.

Target Program: A target program (and thesession) on the AS/400 system is started whenthe AS/400 system receives a program startrequest from the remote system. Before yourtarget program can send or receive data, it mustfirst make a logical connection to the sourceprogram. This logical connection is made whenyour target program uses an acquire operation.

The program device name on the acquire opera-tion identifies the session. This name must matchthe program device name specified in an associ-ated ADDICFDEVE, CHGICFDEVE, orOVRICFDEVE command. You must specify arequesting device for the remote location(RMTLOCNAME(*REQUESTER)) on theADDICFDEVE, CHGICFDEVE, or OVRICFDEVEcommand for the target program that is started bya program start request.

Any values specified for the ADDICFDEVE,CHGICFDEVE, or OVRICFDEVE commandparameters that are not required parameters areignored, except for the format select (FMTSLT)parameter. If you specify a remote format withFMTSLT(*RMTFMT), the acquire operation fails.The local AS/400 system BSCEL configurationparameters are used for the session unlessparameters are sent on the program start requestto override them.

Program start requests are discussed further in“Program Start Request Considerations” onpage 5-1.

Starting a Transaction

A transaction is a logical connection between twoprograms. Use the evoke function to start a trans-action between your program and a program on aremote system. If you start a program on aremote system, you must specify whether theremote system recognizes BSCEL commands. Ifsecurity is required on the remote system, use thesecurity function to pass security information withthe evoke function. The following sections discussthese considerations.


Evoke Function

Use the evoke function to start a transaction afteryou start a session. If you specifyRMTBSCEL(*YES) for the session started by yoursource program, the evoke function attempts tostart a program on the remote system.

Your program can use an evoke function onlyafter it starts a session. You can use more thanone evoke function in a BSCEL session.However, only one transaction at a time is active.The previous transaction must end before you usethe next evoke function.

If a remote program start request started yourprogram, do not use an evoke function afteracquiring a program device that has a remotelocation specified as a requesting device(RMTLOCNAME(*REQUESTER)). The sessionand transaction have already been started with theprogram on the remote system.

With the evoke function your program can specifythe following information:

The name of the program with which yourprogram is communicating

The library in which the other program exists(optional)

User-defined program initialization parameters(optional)

Security information

BSCEL does not support the synchronization levelkeyword with the evoke function.

For information on how to code the evoke func-tion, refer to the ICF Programming and the DDSReference.

RMTBSCEL Considerations

The type of transaction started by an evoke func-tion is determined by the type of remote sessionyou specify on the ADDICFDEVE, CHGICFDEVE,or OVRICFDEVE program device entry commandsor on the CRTDEVBSC or CHGDEVBSC config-uration commands. Specify RMTBSCEL(*NO)when your program communicates with othersystems or devices (such as a System/38 or a3741 Data Entry Station) that cannot recognizeBSCEL commands and online messages. SpecifyRMTBSCEL(*YES) when your program communi-

cates with other systems that are also usingBSCEL.

Specifying RMTBSCEL(*NO): When youspecify RMTBSCEL(*NO) and your program hasstarted a session, you can issue the evoke func-tion to start a transaction, but it does not start aprogram on the remote system. BSCEL assumesthe program on the remote system is alreadyactive. Because the evoke function does notcause line transmission, the parameters specifiedwith the evoke function are not sent and areignored by BSCEL. If an evoke function is notused, the first input or output operation starts thetransaction.

The evoke function is optional when you specifyRMTBSCEL(*NO).

If you want to convert your program to use othercommunications types, use the evoke function tostart a transaction when you specifyRMTBSCEL(*NO).

Specifying RMTBSCEL(*YES): When youspecify RMTBSCEL(*YES) and your program hasstarted a session, the evoke function starts atransaction and also starts a program on theremote system with a program start request. TheRMTBSCEL(*YES) parameter causes BSCEL tobuild and send the program start request. Youcan specify the following parameters with theevoke function:

The name of the target program to be started.This is a required parameter with a maximumlength of 8 bytes.

The name of the library containing the targetprogram. This is an optional parameter with amaximum length of 8 bytes.

User-defined parameters for the targetprogram. These are optional parameters witha maximum combined length of 118 bytes.The target program defines the number andformat of the parameters.

Note: If you specify program initializationparameters (user-defined parameters) with theevoke function, each parameter that is sentshould be equal in length to the correspondingparameter specified in the target program. If itis longer than the parameter length in thetarget program, truncation occurs. If it is


shorter than the parameter length in the targetprogram, results that are not predictable mayoccur.

Security parameters. These are optionalparameters.

See “Syntax for Program Start Requests” onpage 5-1 for more information on the parametersyou specify with the evoke function.

Security Function

When you specify RMTBSCEL(*YES) and use anevoke function, you may need to provide securityinformation for the program start request thatBSCEL sends to the remote system. You mustprovide security information if there is security onthe remote system.

Use the security function with the evoke functionto pass the following security parameters:

The password. This is an optional parameterwith a maximum length of 4 bytes.

The user identifier. This is an optional param-eter with a maximum length of 8 bytes.

BSCEL does not support the profile ID parameterand ignores it if you specify it with the securityinformation.

Sending Data

You can send data during a transaction using thewrite operation. With the write operation, you canspecify the end of a group of records or subdeviceselection. You can also change the record lengthusing the variable-length-data function. (See“Determining Record Lengths” on page 4-8.)

Write Operation

The write operation issues a data record from yourprogram to the remote system in this session.BSCEL sends the record in the data format speci-fied by the configuration parameters or by theADDICFDEVE, CHGICFDEVE, or OVRICFDEVEcommand. When you use a write operation, itissues one data record to BSCEL and returns

control to your program without waiting for theoperation to be completed.

Your program can only use a write operationduring a transaction. To use a write operationwithout sending any data, specify an output recordlength of zero.

Note: If you specify BLOCK(*USER), you mustspecify an output record length of at least two oran error will occur.

If the last function your program used before awrite operation was an invite function, and data isnot available, the write operation causes animplicit cancel-invite. If data is available, yourprogram receives return code 0412 (output excep-tion occurred). Your program must issue an inputoperation to receive the data before it can issuean output operation. (See Appendix B for moreinformation on return code 0412.)

Combining Write with Other Oper-ations and Functions: You can combinethe write operation with several communicationsoperations and functions. For example, if youcombine a write operation with a read operation orinvite function, BSCEL sends an end-of-transmission indication to the remote system. Ifyou specify GRPSEP(*DEV3740) for this session,BSCEL sends a null record after the last datarecord, and then sends the end-of-transmissionindication. If you specify GRPSEP(*OFCSYS) forthis session, BSCEL sends an end-of-text (ETX)control character after the last data record, andthen sends the end-of-transmission (EOT) indi-cation. BSCEL then requests input data from theremote system. With an invite function, controlreturns to your program without waiting for theremote system to send the data. After an invite,your program must use a read or read-from-invited-program-devices operation to obtain thedata. A read-from-invited-program-devicesoperation is an input operation that waits for inputfrom any one of the invited program devices for auser-specified time. Use the timer function or theWAITRCD parameter on the CRTICFF, CHGICFF,or OVRICFF command to limit the waiting time forthe read-from-invited-program-devices operation.

If you specify an output record length of zerowhen the communications line is in a contention


state 2, no line transmission will occur if youcombine the write operation with any of the fol-lowing functions or operations:

Allow-write function Invite function Read operation Detach function with RMTBSCEL(*NO)

Specifying Record Blocking: If you donot specify record blocking when you use a writeoperation, BSCEL sends one data record to theremote system for each write operation. If you dospecify record blocking, BSCEL blocks datarecords before sending them to the remotesystem.

When you specify record blocking and issue con-secutive write operations (without a read operationor invite function), your program is normally two ormore write operations ahead of the data on thecommunications line. If a communications linefails while you are sending data, your program isnotified by a return code on its current write oper-ation. Since the current operation is two or morewrite operations ahead of the failing operation,your program cannot determine if all data wassent before the line failed.

Subdevice Selection Function

Use the subdevice selection function to specify theremote system device (such as a printer, punch,or diskette) to which you are sending data. Thereceiving controller then directs output from yourprogram to the appropriate device. The subdeviceselection is designed primarily to support specifichardware devices, such as 3776, 3777, and 3780.You should only use the subdevice selection ifyour program communicates with one of thesedevices, and you specified RMTBSCEL(*NO) forthe communications session.

BSCEL processes the subdevice selection onlywhen the output operation is:

The first I/O operation in a session that wasstarted by a source program's acquire opera-

tion. (The source program receives an errormessage if the subdevice is specified with anevoke function.)

The first output operation used after an inputoperation, for which an end-of-transmissionindication was received.

The first output operation used after an outputoperation that specified either the allow-write,detach, or end-of-group function.

BSCEL ignores the subdevice selection if it hasbeen selected at any other time. BSCEL sends adevice selection character in a separate record asfollows:

Parameter CharacterValue Sent

*DC1 Hex 11

*DC2 Hex 12

*DC3 Hex 13

*DC4 Hex 5D

End-of-Group Function

When you use the end-of-group function, BSCELindicates to the remote system that this is the lastrecord of a user-defined group of records. Thisfunction also indicates to BSCEL that yourprogram is not requesting any input. BSCELreturns control to your program after the remotesystem acknowledges that it has received the lastdata record.

When you specify the end-of-group function, youmust also specify one of the following values forthe group separator (GRPSEP) parameter duringconfiguration or on the ADDICFDEVE,CHGICFDEVE, or OVRICFDEVE command:

*EOT. An end-of-transmission (EOT) controlcharacter follows the last data record.

*DEV3740. A null record (STXETX) followsthe last data record.

*OFCSYS. An end-of-text (ETX) control char-acter follows the last data record.

2 In data communications, a contention state is a type of half-duplex line or data link control in which either user may transmit anytime the line or link is available. If both users attempt to transmit at the same time, the protocols or the hardware determines whogoes first.


Variable-Length-Data Function

For information about determining the recordlength for an output operation, refer to “Deter-mining Record Lengths” on page 4-8.

Receiving Data

You can use two operations to receive data: readand read-from-invited-program-devices. Use theread operation to receive data from a specificprogram device. Use the read-from-invited-program-devices operation to receive data fromany previously invited program device. A recordlength is specified for each input operation. See“Determining Record Lengths” on page 4-8.

You can use several functions with these oper-ations, including invite, timer, and record identifica-tion.

Read Operation

Your program uses the read operation to obtain adata record from a specific program deviceacquired to the ICF file. The read operation alsocauses the program to wait for the data if it is notimmediately available. Your program receivescontrol when the data is available.

Whether or not a record format is specified on theread operation, the value for the FMTSLT param-eter on the program device entry command deter-mines which record format is used to process thereceived data. If a record format is not specifiedon the read operation, the system may use thedefault record format in the file. This defaultrecord format should be at least as large as themaximum user record length (RCDLEN) config-ured on the device description. See the ICF Pro-gramming for more information on what the defaultrecord formats are for each value of FMTSLT.

Invite Function

Your program uses the invite function to requestinput data from a specific program device. Yourprogram receives control after the invite requestwithout waiting for the input data. To get the data,your program must use either a read or read-from-

invited-program-devices operation later in thistransaction.

The invite function and read-from-invited-program-devices operations are used together. After usingan invite function, use the read-from-invited-program-devices operation to receive the datafrom the remote system.

When data is received from an invited programdevice, that device is no longer invited. You mustuse another invite function to make it eligible torespond to a read-from-invited-program-devicesoperation.

You do not need to use an invite function before aread operation to receive data. However, if youuse a read operation, and the program device hasan outstanding invite, the read completes theinvite and receives the data when it becomesavailable.

Read-from-Invited-Program-DevicesOperation

Your program uses the read-from-invited-program-devices operation to get data from any programdevice that has responded to an invite functionpreviously used by your program. If databecomes available to your program from morethan one program device before you use the read-from-invited-program-devices operation, yourprogram receives the data that was first madeavailable.

Record-Identification Function

The record-identification function identifies andselects the record format to use with a read oper-ation, depending on what data is received fromthe remote system.

This function is only applicable if you specifyFMTSLT(*RECID) on the ADDICFDEVE,CHGICFDEVE, or OVRICFDEVE command.

Variable-Length-Data Function

For information about determining the recordlength for an input operation, refer to “DeterminingRecord Lengths” on page 4-8.


Waiting for a Display File, an ICFFile, and a Data Queue

Use data queues when a program must wait for adisplay file, an ICF file, and a data queue, in anycombination, at the same time. The followingcommands are used with the specified DTAQparameter:

Create Display File (CRTDSPF) Change Display File (CHGDSPF) Override Display File (OVRDSPF) Create ICF File (CRTICFF) Change ICF File (CHGICFF) Override ICF File (OVRICFF)

Use these commands to indicate a data queue inwhich entries are placed when one of the followingoccurs:

An enabled command key or Enter key ispressed from an invited display device

Data becomes available when the session isinvited for an ICF device

A user-defined entry is made to a data queueby a job running on the system

For more information, see the CL Programmingand the ICF Programming books.

Notifying the Remote Program ofProblems

You can inform the other application program thatan error occurred in the data being sent orreceived using the fail function. Specify this func-tion on the write operation.

Fail Function

Use the fail function to indicate an error whensending or receiving data. The function indicatesthat the AS/400 system is ending the current com-munications session with the remote system.

When sending data, the fail function causesBSCEL to discard all records not sent in thecurrent transaction. If some records have beensent, BSCEL abnormally ends the session bysending the remote system a temporary text delay(TTD) followed by an EOT indicator.

When receiving data, the fail function causesBSCEL to discard all incoming records. BSCELabnormally ends the session by sending an EOTcontrol character to the remote system.

Your program should either end or use the end-of-session function after it uses the fail function.Either method will end the communicationssession. After the session has ended, you canattempt to start another communications session.

Using Additional Functions andOperations

You can use the following additional functions andoperation with BSCEL:

Request-to-write function (to request to senddata while your program is receiving data)

Allow-write function (to complete sending dataand to allow the remote system to send data)

Cancel-invite function (to cancel an invite thatyour program issued)

Get-attributes operation (to get the status ofthe current session)

Request-to-Write Function

Your program uses the request-to-write function toask the remote system to stop sending so yourprogram can send. Use the request-to-write func-tion while your program is receiving data to tell theremote system you want to change the direction ofdata transmission. After issuing the request-to-write, your program must continue to receive datauntil the remote system sends an end-of-transmission indication. If the remote systemallows the change, your program can send data, amessage, or both to the remote system.

When you use the request-to-write function,BSCEL sends a reverse-interrupt (RVI) indicator tothe remote system as the response to the nextdata record received. The reverse-interrupt(RVI) character is sent as a request from thereceiving station to the sending station to stoptransmitting and begin receiving a message.BSCEL sends only one RVI indicator to theremote system. If you issue additional request-to-write functions before the change of direction,BSCEL ignores them.


When your program uses the request-to-writefunction and the remote system is also usingBSCEL, the program on the remote systemreceives return code 0010 (operation completedsuccessfully–request to write) as the result of itsnext output operation, after remote BSCELreceives the RVI indication. For each output oper-ation issued before and after that output operation,the remote program receives return code 0000(operation completed successfully–continue) untilit stops sending.

If the remote system sends an RVI indicator, yourprogram receives return code 0010 at the end of awrite operation. Your program should stopsending data and use a r

bsc equivalence link programmingpublic.dhe.ibm.com/systems/power/docs/systemi/v5r4/en_us/...figures...

Documents