IBM Universal Remote Version 4 User Manual

AS/400 Advanced Series

IBM

System API Programming

Version 4

SC41-5800-00

Download from Www.Somanuals.com. All Manuals Search And Download.

AS/400 Advanced Series

IBM

System API Programming

Version 4

SC41-5800-00

Download from Www.Somanuals.com. All Manuals Search And Download.

Take Note!

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

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, Puerto

Rico, or Guam, you can order publications through the IBM Software Manufacturing Solutions at 800+879-2755. Publications are not

stocked 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 mail

your comments to the following address:

IBM Corporation

Attention Department 542

IDCLERK

3605 Highway 52 N

Rochester, MN 55901-7829 USA

or you can fax your comments to:

United States and Canada: 800+937-3430

Other countries: (+1)+507+253-5192

If you have access to Internet, you can send your comments electronically to [email protected]; IBMMAIL, to

IBMMAIL(USIB56RZ).

When you send information to IBM, you grant IBM a nonexclusive right to use or distribute the information in any way it believes

appropriate without incurring any obligation to you.

Note to U.S. Government Users — Documentation related to restricted rights — Use, duplication or disclosure is subject to

restrictions set forth in GSA ADP Schedule Contract with IBM Corp.

Download from Www.Somanuals.com. All Manuals Search And Download.

Contents

Notices

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi

. . . . . . . . . . . . . . . . . . . . . . . . . xii

Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii

Programming Interface Information

About System API Programming (SC41-5800)

. . . . . . . . . . . . . . . . . xiii

Who Should Use This Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii

. . . . . . . . . . . . . . . . . . . . . . . . xiii

Prerequisite and Related Information

Information Available on the World Wide Web . . . . . . . . . . . . . . . . . . . xiii

Chapter 1. Application Programming Interface—Overview

. . . . . . . . . 1-1

API Compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2

Using APIs—Benefits

System APIs or CL Commands—When to Use Each . . . . . . . . . . . . . . . 1-3

Actions and System Functions of APIs

Related Information

. . . . . . . . . . . . . . . . . . . . . . . 1-3

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4

Chapter 2. Getting Started with APIs . . . . . . . . . . . . . . . . . . . . . . . 2-1

Locating the API to Use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1

Selecting the High-Level Language To Use

. . . . . . . . . . . . . . . . . . . . 2-3

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4

API Environments

APIs for the Original Program Model Environment . . . . . . . . . . . . . . . 2-4

APIs for the Integrated Language Environment . . . . . . . . . . . . . . . . . 2-5

APIs for the ILE Common Execution Environment (CEE) . . . . . . . . . . . 2-5

APIs for the UNIX Environment . . . . . . . . . . . . . . . . . . . . . . . . . . 2-6

API Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-6

Parameter Passing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-7

Parameter Classification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-8

Error Code Parameter

Using the Job Log to Diagnose API Errors

Internal Identifiers

User Spaces

User Space Format—Example

Logic Flow of Processing a List of Entries . . . . . . . . . . . . . . . . . . . 2-15

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-8

. . . . . . . . . . . . . . . . . . 2-10

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-12

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-13

. . . . . . . . . . . . . . . . . . . . . . . . . 2-14

Manipulating a User Space with Pointers

Manipulating a User Space without Pointers

. . . . . . . . . . . . . . . . . . . 2-16

. . . . . . . . . . . . . . . . . 2-17

Additional Information about List APIs and a User Space . . . . . . . . . . 2-22

Listing Database File Members with a CL Program—Example . . . . . . . 2-22

Receiver Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-23

Bytes Available and Bytes Returned Fields . . . . . . . . . . . . . . . . . . 2-23

Keyed Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-24

User Space Alternative . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-25

Related Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-25

Continuation Handle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-25

Using a Continuation Handle

. . . . . . . . . . . . . . . . . . . . . . . . . . 2-25

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-26

Domain Concepts

Exit Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-27

Exit Points . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-27

APIs and the QSYSINC Library

. . . . . . . . . . . . . . . . . . . . . . . . . . 2-28

APIs and the QUSRTOOL Library . . . . . . . . . . . . . . . . . . . . . . . . . 2-30

User Index Considerations

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-30

 Copyright IBM Corp. 1997

iii

Download from Www.Somanuals.com. All Manuals Search And Download.

APIs and Internal System Objects . . . . . . . . . . . . . . . . . . . . . . . . . 2-31

Performance Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-31

Chapter 3. Common Information across APIs—Basic (OPM) Example . . 3-1

Original Program Model (OPM) API–Scenario . . . . . . . . . . . . . . . . . . . 3-1

Finding the API Name to Use . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1

Description of an API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2

Format

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-5

Field Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-5

Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-5

Extracting a Field from the Format . . . . . . . . . . . . . . . . . . . . . . . . 3-5

Retrieving the Hold Parameter (Exception Message)—OPM RPG Example

Retrieving the Hold Parameter (Error Code Structure)—OPM RPG

3-6

Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-11

Accessing the HOLD Attribute—OPM RPG Example . . . . . . . . . . . . . . 3-17

Accessing a Field Value (Initial Library List)—OPM RPG Example

Using Keys with List Spooled Files API—Example

Processing Lists That Contain Data Structures . . . . . . . . . . . . . . . . . . 3-29

Retrieve Job Description Information API—Example . . . . . . . . . . . . . . 3-29

Authorities and Locks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-30

. . . . . . . . . . . . . . . . . . . . . . . . . . . 3-30

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-30

. . . . 3-19

. . . . . . . . . . . . . . . 3-24

Required Parameter Group

JOBD0100 Format

Field Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-32

Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-36

Chapter 4. Common Information across APIs—Advanced (ILE) Example

4-1

Integrated Language Environment (ILE) APIs—Introduction . . . . . . . . . . . 4-1

Registration Facility Using ILE APIs—Concepts . . . . . . . . . . . . . . . . . . 4-2

Generic Header Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2

Keyed Interface—Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-3

Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-5

Receiver Variables—Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 4-7

Registration Facility Using ILE APIs—Examples . . . . . . . . . . . . . . . . . . 4-9

Retrieve Exit Point and Exit Program Information—ILE C Example

. . . . 4-13

Remove Exit Program and Deregister Exit Point—ILE C Example . . . . . 4-19

Chapter 5. List APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1

Characteristics of a List API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1

General Data Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1

Processing a List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-4

List Object API—OPM RPG Example . . . . . . . . . . . . . . . . . . . . . . . . 5-4

List Objects That Adopt Owner Authority API—Example . . . . . . . . . . . . 5-12

Authorities and Locks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-12

Required Parameter Group

. . . . . . . . . . . . . . . . . . . . . . . . . . . 5-12

User Space Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-14

Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-16

Chapter 6. Original Program Model (OPM) and Integrated Language

Environment (ILE) Differences . . . . . . . . . . . . . . . . . . . . . . . . . . 6-1

Contrasting OPM and ILE APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-1

API Name

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-1

Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-1

Error Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-1

iv System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Pointers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-2

. . . . . . . . . . . . . . . . . . 7-1

Chapter 7. Machine Interface Programming

Machine Interface Instructions—Introduction . . . . . . . . . . . . . . . . . . . . 7-1

Writing an MI Program—Example . . . . . . . . . . . . . . . . . . . . . . . . . . 7-2

Setting the Entry Point . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-2

Setting the Declare Statements . . . . . . . . . . . . . . . . . . . . . . . . . . 7-2

Starting the Instruction Stream

Compiling a Program

Using CLCRTPG to Create an MI Program . . . . . . . . . . . . . . . . . . . 7-5

Creating the MI Example Program

Debugging the MI Program

. . . . . . . . . . . . . . . . . . . . . . . . . . 7-3

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-4

. . . . . . . . . . . . . . . . . . . . . . . . 7-6

. . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-7

Setting Breakpoints in the MI Program . . . . . . . . . . . . . . . . . . . . . . 7-7

Handling Exceptions in the MI Program . . . . . . . . . . . . . . . . . . . . . 7-9

Creating an MI Version of CLCRTPG . . . . . . . . . . . . . . . . . . . . . . . 7-11

Source for the CL03 Program . . . . . . . . . . . . . . . . . . . . . . . . . . 7-13

Source for the CL04 Program . . . . . . . . . . . . . . . . . . . . . . . . . . 7-13

Source for the CL05 Program . . . . . . . . . . . . . . . . . . . . . . . . . . 7-14

Source for the MICRTPG Program . . . . . . . . . . . . . . . . . . . . . . . 7-15

Understanding the MICRTPG Program (by Sections of Code) . . . . . . . 7-16

Enhanced Version of the MICRTPG Program

. . . . . . . . . . . . . . . . . . 7-18

. . . . . . 7-18

Understanding the MICRTPG2 Program (by Sections of Code)

Beginning the Instruction Stream . . . . . . . . . . . . . . . . . . . . . . . . 7-22

MICRTPG2 Complete Program—MI Code Example . . . . . . . . . . . . . 7-23

Creating the MICRTPG2 Program . . . . . . . . . . . . . . . . . . . . . . . . . 7-27

Handling Exceptions in the MICRTPG2 Program . . . . . . . . . . . . . . . 7-27

MI Common Programming Techniques—Examples . . . . . . . . . . . . . . . 7-32

AS/400 Program Storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-36

Chapter 8. Use of OS/400 APIs

. . . . . . . . . . . . . . . . . . . . . . . . . . 8-1

Backup and Recovery APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-1

Client Support APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-1

Communications APIs

Configuration APIs

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-2

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-3

Debugger APIs

Dynamic Screen Manager APIs . . . . . . . . . . . . . . . . . . . . . . . . . . 8-4

Edit Function APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-5

File APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-5

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-6

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-3

Hardware Resource APIs

Hierarchical File System (HFS) APIs . . . . . . . . . . . . . . . . . . . . . . . 8-6

High-Level Language APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-6

Integrated Language Environment (ILE) CEE APIs . . . . . . . . . . . . . . . 8-7

Journal and Commit APIs

Message Handling APIs

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-8

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-8

National Language Support APIs . . . . . . . . . . . . . . . . . . . . . . . . . 8-9

Network Management APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-9

Object APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-11

Office APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-15

Operational Assistant APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-17

Performance Collector APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-17

Print APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-17

Problem Management APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-18

Program and CL Command APIs . . . . . . . . . . . . . . . . . . . . . . . . 8-19

Registration Facility APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-19

Contents

Download from Www.Somanuals.com. All Manuals Search And Download.

Security APIs

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-20

Software Product APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-20

UNIX-Type APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-21

User Interface APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-27

Virtual Terminal APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-28

Work Management APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-28

Work Station Support APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-28

Miscellaneous APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-29

Chapter 9. Common API Programming Errors . . . . . . . . . . . . . . . . . 9-1

Using the Error Code Parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-2

Using the Error Code Parameter—Example of Incorrect Coding . . . . . . . 9-2

Using the Error Code Parameter—Example of Correct Coding . . . . . . . . 9-3

Defining Data Structures

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-5

Defining a Data Structure—Example of Incorrect Coding . . . . . . . . . . . 9-5

Defining A Data Structure—Example of Correct Coding . . . . . . . . . . . . 9-7

Defining Receiver Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-10

Defining Receiver Variables—Example of Incorrect Coding . . . . . . . . . 9-10

Defining Receiver Variables—Example of Correct Coding . . . . . . . . . . 9-12

Defining List Entry Format Lengths

Defining List Entry Format Lengths—Example of Incorrect Coding . . . . . 9-14

Defining List Entry Format Lengths—Example of Correct Coding . . . . . 9-16

Using Null Pointers with OPM APIs . . . . . . . . . . . . . . . . . . . . . . . . 9-18

Using Null Pointers with OPM APIs—Example of Incorrect Coding . . . . 9-18

. . . . . . . . . . . . . . . . . . . . . . . . 9-14

Using Null Pointers with OPM APIs—Example of Correct Coding . . . . . 9-19

Defining Byte Alignment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-22

Defining Byte Alignment—Example of Incorrect Coding . . . . . . . . . . . 9-22

Defining Byte Alignment—Example of Correct Coding . . . . . . . . . . . . 9-25

Using Offsets in a User Space . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-27

Using Offsets in a User Space—Example of Incorrect Coding . . . . . . . 9-27

Using Offsets in a User Space—Example of Correct Coding . . . . . . . . 9-31

Coding for New Function

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-36

Coding for New Function—Example of Incorrect Coding

Coding for New Function—Example of Correct Coding

. . . . . . . . . . 9-36

. . . . . . . . . . . 9-43

Appendix A. Performing Tasks Using APIs—Examples . . . . . . . . . . A-1

Packaging Your Own Software Products A-1

. . . . . . . . . . . . . . . . . . . . .

Retrieving a File Description to a User Space—ILE C Example . . . . . . . . A-11

Using Data Queues versus User Queues . . . . . . . . . . . . . . . . . . . . . A-15

Data Queue—ILE C Example . . . . . . . . . . . . . . . . . . . . . . . . . . A-16

User Queue—ILE C Example . . . . . . . . . . . . . . . . . . . . . . . . . . A-17

Appendix B. Original Examples in Additional Languages . . . . . . . . . B-1

Original Program Model (OPM) APIs—Examples

. . . . . . . . . . . . . . . .

B-2

Retrieving the Hold Parameter (Exception Message)—ILE C Example

. .

Retrieving the Hold Parameter (Exception Message)—ILE COBOL Example B-4

Retrieving the Hold Parameter (Exception Message)—ILE RPG Example B-6

Handling Error Conditions—ILE RPG Example . . . . . . . . . . . . . . . . B-8

Retrieving the Hold Parameter (Error Code Structure)—ILE C Example

Retrieving the Hold Parameter (Error Code Structure)—ILE COBOL

. B-10

Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-12

Retrieving the Hold Parameter (Error Code Structure)—ILE RPG Example B-14

Accessing the HOLD Attribute—ILE C Example

. . . . . . . . . . . . . . . B-16

Accessing the HOLD Attribute—ILE COBOL Example . . . . . . . . . . . . B-18

vi System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Accessing the HOLD Attribute—ILE RPG Example

Accessing a Field Value (Initial Library List)—ILE C Example

. . . . . . . . . . . . . B-21

. . . . . . . B-22

Accessing a Field Value (Initial Library List)—ILE COBOL Example . . . . B-25

Accessing a Field Value (Initial Library List)—ILE RPG Example . . . . . . B-29

Using Keys with List Spooled Files API—ILE C Example . . . . . . . . . . B-33

Using Keys with List Spooled Files API—ILE COBOL Example

Using Keys with List Spooled Files API—ILE RPG Example . . . . . . . . B-42

Integrated Language Environment (ILE) APIs—Examples

. . . . . . B-38

. . . . . . . . . . . B-47

Retrieve Exit Point and Exit Program Information—OPM COBOL Example B-61

Retrieve Exit Point and Exit Program Information—ILE COBOL Example . B-66

Retrieve Exit Point and Exit Program Information—OPM RPG Example

Retrieve Exit Point and Exit Program Information—ILE RPG Example

. B-71

. . B-75

Remove Exit Program and Deregister Exit Point—OPM COBOL Example

B-85

Remove Exit Program and Deregister Exit Point—ILE COBOL Example . B-87

Remove Exit Program and Deregister Exit Point—OPM RPG Example . . B-90

Remove Exit Program and Deregister Exit Point—ILE RPG Example . . . B-92

List Object API—Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-94

List Object API—ILE C Example

. . . . . . . . . . . . . . . . . . . . . . . . B-94

List Object API—ILE COBOL Example . . . . . . . . . . . . . . . . . . . . B-101

List Object API—ILE RPG Example

OPM API without Pointers—Examples

. . . . . . . . . . . . . . . . . . . . . B-106

. . . . . . . . . . . . . . . . . . . . . B-112

Logging Software Error (OPM API without Pointers)—OPM COBOL

Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-112

Logging Software Error (OPM API without Pointers)—OPM RPG Example B-116

Logging Software Error (OPM API without Pointers)—ILE RPG Example B-119

ILE API with Pointers—Examples

. . . . . . . . . . . . . . . . . . . . . . . . B-122

Reporting Software Error (ILE API with Pointers)—ILE COBOL Example

B-122

Reporting Software Error (ILE API with Pointers)—ILE RPG Example . . B-126

Program for Packaging a Product—Examples . . . . . . . . . . . . . . . . . B-129

Program for Packaging a Product—ILE C Example

Program for Packaging a Product—ILE COBOL Example . . . . . . . . . B-136

Program for Packaging a Product—ILE RPG Example

. . . . . . . . . . . . B-129

. . . . . . . . . . B-144

Retrieving a File Description to a User Space—Examples . . . . . . . . . . B-152

Retrieving a File Description to a User Space—ILE COBOL Example . . B-152

Retrieving a File Description to a User Space—ILE RPG Example

. . . B-155

Data Queue—Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-165

. . . . . . . . . . . . . . . . . . . . . B-165

Data Queue—ILE COBOL Example

Data Queue—OPM RPG Example . . . . . . . . . . . . . . . . . . . . . . B-169

Data Queue—ILE RPG Example . . . . . . . . . . . . . . . . . . . . . . . B-172

UNIX-Type APIs—Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . B-175

Using the Integrated File System—ILE C Example . . . . . . . . . . . . . B-175

Using the Integrated File System—ILE COBOL Example . . . . . . . . . B-178

Using the Integrated File System—ILE RPG Example . . . . . . . . . . . B-183

Bibliography . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . H-1

General-Purpose Books . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . H-1

OS/400 API Books . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . H-1

Programming Language Books . . . . . . . . . . . . . . . . . . . . . . . . . . . H-2

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

X-1

Contents vii

Download from Www.Somanuals.com. All Manuals Search And Download.

viii System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Figures

1-1. How APIs Fit into the AS/400 Business Computing System Structure 1-2

2-1. OPM and ILE API Verbs and Abbreviations . . . . . . . . . . . . . . . 2-2

2-2. Language Selection Considerations — Data Types . . . . . . . . . . . 2-3

2-3. Language Selection Considerations — Call Conventions

. . . . . . . 2-4

. . . . . . . . . . . . . . . . . . . . . 2-7

2-4. Methods for Passing Parameters

2-5. Include Files Shipped with the QSYSINC Library . . . . . . . . . . . 2-28

5-1. General Data Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2

7-1. Program Flow for Creating the MICRTPG Program . . . . . . . . . . 7-12

8-1. Simplified Sequence of Events for a Sockets Program Example . . 8-26

9-1. Common Programming Errors . . . . . . . . . . . . . . . . . . . . . . . 9-1

A-1. ABC Software Packaging . . . . . . . . . . . . . . . . . . . . . . . . . A-1

A-2. Steps for Creating a Software Product . . . . . . . . . . . . . . . . . A-2

B-1. Original Program Model (OPM) API Examples from Chapter 3 . . . B-1

B-2. Integrated Language Environment (ILE) API Examples from Chapter

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

B-1

B-2

B-3. List API Examples from Chapter 5

B-4. Pointer API Examples from Chapter 6

B-5. Performing Tasks Using API Examples from Appendix A

B-6. UNIX-Type API Examples

. . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . .

. . . . . .

. . . . . . . . . . . . . . . . . . . . . . . .

 Copyright IBM Corp. 1997

Download from Www.Somanuals.com. All Manuals Search And Download.

System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Notices

References in this publication to IBM products, programs, or services do not imply that IBM intends to

make 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 equivalent

product, program, or service may be used instead of the IBM product, program, or service. The evaluation

and 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, NY

10594, U.S.A.

Licensees of this program who wish to have information about it for the purpose of enabling: (i) the

exchange 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 Corporation

Software Interoperability Coordinator

3605 Highway 52 N

Rochester, 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. This

publication may also refer to products that have not been announced in your country. IBM makes no

commitment to make available any unannounced products referred to herein. The final decision to

announce 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 illustrate

them as completely as possible, the examples include the names of individuals, companies, brands, and

products. All of these names are fictitious and any similarity to the names and addresses used by an

actual business enterprise is entirely coincidental.

This publication contains small programs that are furnished by IBM as simple examples to provide an

illustration. These examples have not been thoroughly tested under all conditions. IBM, therefore, cannot

guarantee or imply reliability, serviceability, or function of these programs. All programs contained herein

are provided to you "AS IS". THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR

A PARTICULAR PURPOSE ARE EXPRESSLY DISCLAIMED.

 Copyright IBM Corp. 1997

Download from Www.Somanuals.com. All Manuals Search And Download.

Programming Interface Information

This publication is intended to help experienced programmers create application programs. This publica-

tion documents General-Use Programming Interface and Associated Guidance Information provided by the

Operating System/400 (OS/400) licensed program.

General-Use programming interfaces allow the customer to write programs that obtain the services of the

OS/400 program. If you have a requirement for additional interfaces to the OS/400 program, contact IBM

at 1-507-253-1055 (FAX 507-253-1571).

Trademarks

The following terms are trademarks of the IBM Corporation in the United States or other countries or both:

Advanced Function Printing

Advanced Peer-to-Peer Networking

AFP

Operating System/2

Operating System/400

Operational Assistant

OS/400

Application System/400

APPN

AS/400

PrintManager

RPG IV

C/400

RPG/400

COBOL/400

SAA

DB2

SOM

FORTRAN/400

GDDM

SOMobjects

System/38

IBM

System/370

Systems Application Architecture

Ultimedia

Integrated Language Environment

NetView

OfficeVision

400

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 through

X/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 be

trademarks or service marks of others.

xii System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

About System API Programming (SC41-5800)

This book provides introductory, conceptual, and

Prerequisite and Related

Information

guidance information about how to use OS/400

application programming interfaces (APIs) with

your application programs. It includes examples

and discusses the following:

For information about other AS/400 publications

(except Advanced 36), see either of the following:

Ÿ Benefits of using APIs

Ÿ The Publications Reference book, SC41-5003,

in the AS/400 Softcopy Library.

Ÿ When to use APIs versus CL commands

Ÿ How to locate an API in the System API Ref-

erence book, SC41-5801

Ÿ Which high-level language (HLL) to use for

APIs

Ÿ The AS/400 Information Directory, a unique,

multimedia interface to a searchable database

that contains descriptions of titles available

from IBM or from selected other publishers.

The AS/400 Information Directory is shipped

with the OS/400 operating system at no

charge.

Ÿ Various API environments

Ÿ Common information across object program

model (OPM) APIs and Integrated Language

Environment (ILE) APIs

Ÿ Characteristics and use of list APIs

Ÿ Differences between OPM and ILE APIs

Ÿ Machine interface (MI) programming

Ÿ Why you might want to make use of various

OS/400 APIs

Information Available on the

World Wide Web

Ÿ Tips for common API programming errors

More AS/400 information is available on the World

Wide Web. You can access this information from

the AS/400 home page, which is at the following

uniform resource locator (URL) address:

This book provides introductory and guidance

information only; it does not contain API reference

information. For reference information, see the

System API Reference book.

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

Select the Information Desk, and you will be able

to access a variety of AS/400 information topics

from that page.

For a list of related publications, see the

“Bibliography” on page H-1.

Who Should Use This Book

This book is intended for experienced application

programmers who are developing system-level

and other OS/400 applications.

 Copyright IBM Corp. 1997

xiii

Download from Www.Somanuals.com. All Manuals Search And Download.

xiv System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

API Compatibility

Chapter 1. Application Programming Interface—Overview

Application programming interfaces (APIs) that are used on AS/400 business com-

puting systems provide paths into system functions. APIs are intended for experi-

enced application programmers who develop system-level applications and other

AS/400 applications.

In the broadest sense, AS/400 application programming interfaces (APIs) are

any formal interfaces that are intended to be used in the building of applications.

These interfaces can include such functions as:

Ÿ Control language (CL) commands

Ÿ High-level language (HLL) instructions

Ÿ Machine Interface (MI) instructions

Ÿ Exit programs

Ÿ Callable Operating System/400 (OS/400) APIs, such as those discussed in the

System API Reference, SC41-5801, and documentation for various licensed

programs.

The APIs discussed in this book are those callable and bindable OS/400 APIs and

OS/400 exit programs that are documented in the System API Reference.

Figure 1-1 on page 1-2 shows how APIs fit into the system structure.

API Compatibility

Original program model (OPM) APIs and Integrated Language Environment (ILE)

APIs must be compatible from one release to the next. To ensure this compat-

ibility, at least one of the following is true:

Ÿ Any additional parameters for existing OPM APIs are placed after the current

parameters and are optional parameters. For example, the Move Program

Message (QMHMOVPM) API has a group of required parameters and two

groups of optional parameters.

Note: ILE APIs cannot have additional parameters added to existing APIs.

Ÿ Any additional data structures are provided as a new format.

Ÿ Any new information for a data structure is added at the end of that format or

replaces a field currently defined as reserved.

It is IBM's intention that the APIs will continue to work as they originally worked and

any existing applications that use the APIs will continue to work without changes.

However, significant architectural changes may necessitate incompatible changes.

Some API definitions (for example, the UNIX** type of API definitions) are estab-

lished by industry standards organizations where the degree of compatibility is

determined by the organizations.

 Copyright IBM Corp. 1997

1-1

Download from Www.Somanuals.com. All Manuals Search And Download.

Program

Application

Licensed Programs

Commands

User

Exit

Application

High-Level

Languages

HLL

Program

Application

Calls

Exits

OS/400

ILE C for AS/400

MI Application

Machine

Interface

Licensed Internal Code

CL commands

Callable programs

Exit programs

Machine Interface Instructions

(accessible through ILE C for AS/400 or MI programming languages)

RV3W217-1

Figure 1-1. How APIs Fit into the AS/400 Business Computing System Structure

Using APIs—Benefits

Although some CL commands and some OS/400 APIs perform the same basic

functions, APIs often can provide additional performance improvements and access

to functions. Benefits for using APIs include the following:

Ÿ APIs are slightly faster than the following:

– Using the equivalent command or calling a CL program to call the

command.

– Coding a call to a command by using the Process Commands (QCAPCMD)

API because the API is saved the overhead of processing a command.

When you call an API, you do not have to go through the command ana-

lyzer.

– Using the system function in the ILE C language that processes com-

mands.

1-2 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Ÿ Your application is more straightforward if you are coding in a programming lan-

guage other than CL, which is not a fully defined language (it does not have

the full capabilities of a high-level language). For example, you may have to

code separate CL programs to perform specific functions.

Ÿ You can access system information and functions that are not available through

CL commands.

Ÿ Data is often easier to work with when returned to you by an API.

Ÿ At times, you may need access to system functions at a lower level than what

was initially provided on the AS/400 system. APIs and a set of documented

machine interface (MI) instructions are available to allow the experienced pro-

grammer access to these system functions.

System APIs or CL Commands—When to Use Each

Before system APIs were offered on the AS/400, you had to either code separate

CL programs to perform the needed functions using the appropriate CL commands

or code a call to the Execute Command (QCMDEXC) API in your program. Both

methods made coding an application on the AS/400 more cumbersome (less

straightforward and not as fast as possible).

CL commands will always be needed; they are ideal for the interactive user and for

CL applications that are performing basic tasks. They provide a complete set of

functions on the AS/400 system.

APIs are not provided as a replacement for CL commands, although in many cases

there may be both an API and a CL command that perform the same function. If a

CL command and an API provide the same function, at times the API provides

more flexibility and information. The CL command is intended to be entered either

interactively or in a CL program, and the API is designed as a programming inter-

face.

Some APIs have no equivalent CL command. These APIs have been provided in

areas where customers and business partners have indicated that they need high-

level language (HLL) access.

Actions and System Functions of APIs

An API can be categorized by the type of action it performs and by the system

function that it relates to.

Following are some of the types of APIs that perform actions; several examples of

these APIs are discussed in more detail in later chapters of this book.

Ÿ List APIs, which return lists of information about something on the system.

Refer to “List Object API—Examples” on page B-94 for an example of a list

API in both ILE COBOL and ILE RPG.

Ÿ Retrieve APIs, which return information to the application program.

Ÿ Create, change, and delete APIs, which work with objects of a specified type

on the system.

Ÿ Other APIs, which perform a variety of actions on the system.

While many APIs are used alone, some can be used together to perform a task or

function. The following is a list of a few functions:

Chapter 1. Application Programming Interface—Overview 1-3

Download from Www.Somanuals.com. All Manuals Search And Download.

Ÿ Defining, creating, distributing, and maintaining your own software products.

See “Packaging Your Own Software Products” on page A-1 for an example of

packaging a product similar to the way IBM packages products.

Ÿ Controlling systems and networks, which can include configuration, spooled

files, network management, problem management, and so forth.

Ÿ Handling objects, which includes creating, changing, copying, deleting, moving,

and renaming objects on the system.

APIs can also be categorized by the operating environment. For more information,

refer to “API Environments” on page 2-4.

Related Information

Besides the OS/400 APIs that are documented in the System API Reference, other

OS/400 APIs are documented in the following books:

Ÿ Common Programming APIs Toolkit/400 Reference, SC41-4802

Ÿ CPI Communications Reference, SC26-4399

Ÿ DB2 for AS/400 Query Management Programming, SC41-5703

Ÿ GDDM Programming Guide, SC41-0536

Ÿ Machine Interface Functional Reference, SC41-5810

Ÿ PrintManager API Reference, S544-3699

Ÿ REXX/400 Programmer’s Guide, SC41-5728, and REXX/400 Reference,

SC41-5729

Ÿ Ultimedia System Facilities Programming, SC41-4652

Many products on the AS/400 system also provide APIs. Refer to the product doc-

umentation for more information.

Ÿ Client Access

Ÿ OfficeVision for AS/400

Ÿ OSI File Services, OSI Message Services, and OSI Communications Sub-

system

Ÿ System Manager for AS/400 and Managed System Services for OS/400

Ÿ TCP/IP Connectivity Utilities for AS/400

1-4 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Chapter 2. Getting Started with APIs

You may find the information in this chapter helpful as you start to work with APIs;

for example, locating the API that you want to use. It also tells you about informa-

tion that you will need when using the APIs. Other topics covered are:

Ÿ Language selection considerations

Ÿ API environments

Ÿ API parameters

Ÿ Internal identifiers

Ÿ User spaces and receiver variables

Ÿ Continuation handles

Ÿ System and user domain concepts

Ÿ Exit programs

Ÿ QSYSINC library

Ÿ QUSRTOOL library

Ÿ User index considerations (recovering data)

Ÿ APIs and internal system objects

Ÿ Performance considerations

Locating the API to Use

If you are using the System API Reference, you can use the following methods to

find an API:

Ÿ You can use the table of contents where the APIs are grouped by function.

Within each chapter, the APIs are listed in alphabetical order.

Ÿ You can use the index where the APIs are listed in alphabetical order under the

application programming interface (API) topic.

Ÿ You can also use the index where the APIs are listed under terms such as the

following:

– Job API

– List API

– Spooled file API

– Socket network functions (in this case, the term functions means the same

as APIs)

Except for APIs that are defined by formal standards organizations (for example,

UNIX type or Systems Application Architecture (SAA)), OS/400 APIs start with the

letter Q and are followed by two to three letters that make up an internal compo-

nent identifier. The last part of the API name identifies the action or function of the

API. Generally, the information after the component ID is an abbreviation of the

verb that describes the function of the API. Figure 2-1 on page 2-2 contains all of

the verbs that are either part of an API name or are implied verbs associated with

an API name.

 Copyright IBM Corp. 1997

2-1

Download from Www.Somanuals.com. All Manuals Search And Download.

Figure 2-1. OPM and ILE API Verbs and Abbrevi-

ations

Figure 2-1. OPM and ILE API Verbs and Abbrevi-

ations

Verb

Abbreviation

access

Verb

Abbreviation

access

Add

Put

PUT, Put

ADD, Add

C, CHG, Chg, ch

C, CHK, CHECK

CLR, Clr

CLO, close

Cmp

PutGet

Query

PutGet

Change

Check

Clear

Q, QRY, Qry

Read

RD, Read, read

Receive

Release

Remove

Rename

Report

Resend

Reserve

Restore

reset

R, RCV, RECV

RG, REG, R, Register

Complete

Control

Convert

Copy

RLS

CTL

RMV, Rmv, Remove, rm

CVT, CVRT, Convert

CPY, Cpy

CRT, Crt, create

CST

RNM, rename

Report

Create

Customize

Delete

Deregister

Disable

Display

Dump

RSN

Reserve

DLT, Dlt

DRG, Deregister

Restore

rewind

Resize

Retrieve

Roll

Rsz

DSP, Dsp

DMP, Dump

dup

R, RTV, Rtv, Retrieve

Roll

duplicate

Edit

Save

SAV, Sav, Save

EDT

Scan for

Send

SCAN

Enable

End

S, SND, SEND, Send

END, End

EXC, EXEC

FTR

Set

SET, Set

Execute (run)

Filter

Shift

Shf

Start

Start, STR, Str

Force

FRC

Submit

Switch

Test

Submit

Generate

Get (fetch)

Initialize

Insert

GEN

Set

G, GET, Get, get

Inz

Toggle

Transform

Translate

truncate

Unregister

Update

Validate

Work with

Write

Tgl

Ins

link

TR, TRN, XLATE

List

L, LST, List

LUL

truncate

Lock/unlock

make

UPD

Map

Maximize

Move

Mxz

WK, WRK, Wrk

WRT, Wrt, write, W

MOV, Mov

OPN, open

Pad

Open

Note: Refer to “APIs for the ILE Common Exe-

cution Environment (CEE)” on page 2-5 for infor-

mation about ILE CEE API names.

Pad

PRT, Prt

2-2 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Selecting the High-Level Language To Use

You can use APIs with all the languages available on AS/400 business computing

systems, except for the ILE APIs. ILE APIs that are implemented as service pro-

grams (*SRVPGM) can be accessed only by ILE languages. In some cases, a

program (*PGM) interface is provided so that non-ILE languages can access the

function.

Some APIs also require that particular data types and particular parameter passing

conventions be used. Figure 2-2 shows the languages available on the AS/400

system and the data types that they provide.

Figure 2-2. Language Selection Considerations — Data Types

Excep-

tion

Han-

dling

Float-

ing

Point

Poin-

ters

Binary

Char-

acter

Zoned

Decimal

Packed

Decimal

Struc-

tures

Single

Array

Language

BASIC (PRPQ

5799-FPK)

ILE C

VisualAge C++ for

OS/400

ILE CL

COBOL

ILE COBOL

Pascal (PRPQ

5799-FRJ)

PL/I (PRPQ

5799-FPJ)

REXX

RPG

ILE RPG

Notes:

You cannot develop Cross System Product (CSP) programs on an AS/400 system. However, you can develop CSP pro-

grams on a System/370 system and run them on your AS/400 system.

Refer to the CNVRT$ intrinsic function.

There is no direct support, but the %BIN function exists on the Change Variable (CHGVAR) CL command to convert to and

from binary.

There is no direct support, but you can use the substring capability to simulate structures and arrays.

There is no direct support, but pointers passed to a CL program are preserved.

COBOL and ILE COBOL programs cannot monitor for specific messages, but these programs can define an error handler to

run when a program ends because of an error.

There is no direct support, but you can use extended program model (EPM) conversion routines to convert to and from

zoned and packed decimal.

RPG programs cannot monitor for specific messages, but these programs turn on an error indicator when a called program

ends with an error. These programs can define an error handler to run when a program ends because of an error.

Packed decimal is implemented in ILE C with the decimal() data type.

Packed decimal is implemented in VisualAge C++ for OS/400 with the Binary Coded Decimal (BCD) class. The BCD class is

the C++ implementation of the C-language's decimal(). The BCD object can be used in API calls because it is binary com-

patible with the decimal() data type.

Chapter 2. Getting Started with APIs 2-3

Download from Www.Somanuals.com. All Manuals Search And Download.

Figure 2-3 on page 2-4 shows the languages available on the AS/400 system and

the parameter support that they provide. For more information, see the reference

manual for the specific programming language that you plan to use.

Figure 2-3. Language Selection Considerations — Call Conventions

Function

Return

Values

Pass

Value

Pass by

Reference

Language

BASIC

ILE C

VisualAge C++ for OS/400

ILE CL

COBOL

ILE COBOL

Pascal

PL/I

REXX

RPG

ILE RPG

Notes:

You cannot develop Cross System Product (CSP) programs on an AS/400 system. However,

you can develop CSP programs on a System/370 and run them on your AS/400 system.

Return values are used by the UNIX-type APIs and the Dynamic Screen Manager (DSM) APIs.

COBOL provides a by-content phrase, but it does not have the same semantics as ILE C pass-

by-value.

API Environments

OS/400 APIs exist in several operating environments on an AS/400 system. These

environments are:

Ÿ Original program model (OPM)

Ÿ Integrated Language Environment (ILE)

Ÿ ILE Common Execution Environment (CEE)

Ÿ UNIX-type

APIs for the Original Program Model Environment

OPM APIs, the initial APIs on AS/400, use the following naming conventions:

Ÿ Start with the letter Q.

Ÿ Are followed by a 2- or 3-letter internal component identifier.

Ÿ Are limited to 8 characters.

Ÿ Must be uppercase.

2-4 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Related Information

Ÿ System API Reference, SC41-5801

Ÿ CL Reference, SC41-5722

Ÿ Chapter 3, “Common Information across APIs—Basic (OPM) Example” on

page 3-1

APIs for the Integrated Language Environment

The Integrated Language Environment (ILE) model is a set of tools and associated

system support designed to enhance program development on an AS/400 system.

Bindable ILE APIs are independent from the high-level languages. This can be

useful when mixed languages are involved.

The ILE APIs provide functions such as:

Ÿ Dynamic screen management (DSM)

Ÿ National language support

Ÿ Mail server framework

Ÿ Problem management

Ÿ Programming and control language (CL)

Ÿ Registration facility

Ÿ Source debugger

ILE APIs use the following naming conventions:

Ÿ Start with the letter Q.

Ÿ Are followed by a 2- or 3-character internal component identifier.

Ÿ Can be up to 30 characters.

Ÿ Are case sensitive.

ILE service programs (*SRVPGM) use the following naming conventions:

Ÿ Start with the letter Q.

Ÿ Are followed by a 2- or 3-character internal component identifier.

Ÿ Are limited to 8 characters.

Ÿ Are uppercase.

Related Information

Ÿ Chapter 4, “Common Information across APIs—Advanced (ILE) Example” on

page 4-1

Ÿ ILE Concepts, SC41-5606, for conceptual information about ILE

Ÿ Appropriate language guide or reference for information about the ILE lan-

guages

Ÿ System API Reference, SC41-5801

APIs for the ILE Common Execution Environment (CEE)

The ILE APIs with names beginning with CEE are based on the SAA language

environment specifications. These APIs are intended to be consistent across the

IBM SAA systems. CEE APIs with names beginning with CEE4 or CEES4 are spe-

cific to AS/400 business computing systems.

The ILE CEE APIs provide functions such as:

Ÿ Activation group and control flow management

Ÿ Condition management

Ÿ Date and time manipulation

Chapter 2. Getting Started with APIs 2-5

Download from Www.Somanuals.com. All Manuals Search And Download.

Ÿ Math functions

Ÿ Message services

Ÿ Program or procedure call management and operational descriptor access

Ÿ Storage management

Related Information

Ÿ “Integrated Language Environment (ILE) CEE APIs” on page 8-7

Ÿ ILE Concepts, SC41-5606, for conceptual information about ILE

Ÿ SAA CPI Language Environment Reference, for information about the SAA

Language Environment

Ÿ ILE CEE APIs in the System API Reference, SC41-5801

APIs for the UNIX Environment

The interfaces provided by sockets, the integrated file system, and the Common

Programming APIs (CPA) Toolkit/400 are part of a continuing emphasis on sup-

porting an open environment on the AS/400 system. The socket functions and inte-

grated file system should ease the amount of effort required to move UNIX**

applications to the AS/400 system.

The integrated file system is a function of OS/400 that supports stream input/output

and storage management similar to personal computer and UNIX operating

systems. It also provides an integrating structure over all information stored in

AS/400.

The naming conventions for the UNIX-type APIs are determined by industry stand-

ards organizations.

Related Information

Ÿ “UNIX-Type APIs” on page 8-21

Ÿ Common Programming APIs Toolkit/400 Reference, SC41-4802

Ÿ Integrated File System Introduction, SC41-5711

Ÿ Sockets Programming, SC41-5422

Ÿ UNIX-type APIs in the System API Reference, SC41-5801

API Parameters

After you have found the API that you want to use, you need to code a call to an

API and pass to the API the required set of parameters appropriate for that API.

Parameters can be:

Ÿ Required, which means that you must enter all of the parameters in the speci-

fied order.

Ÿ Optional, which means that you must enter all or none of the parameters within

the optional group. When you enter an optional group, you must also include

all preceding optional groups.

Ÿ Omissible, which means that the group of parameters may have parameters

that can be omitted. When these parameters are omitted, you must pass a null

pointer.

For OPM and ILE APIs, the values for all parameters that identify objects on the

system must be in *NAME (basic name) format, left-justified, uppercase, and with

valid special characters. (The *NAME format is a character string that must begin

with an alphabetic character (A through Z, $, #, or @) followed by up to 9 charac-

2-6 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

ters (A through Z, 0 through 9, $, #, @, ), or _). The system uses an object name

as is, and it does not change or check the object name before locating the object.

This improves the performance of the API. An incorrect name usually results in an

Object not found error.

Parameter Passing

With the exception of the UNIX-type APIs, the standard protocol is to pass a space

pointer that points to the information that is being passed. (This is also referred to

as pass-by-reference.) This is the convention automatically used by CL, RPG, and

COBOL compilers. If you are using a language that supports pointers, you must

ensure that these conventions are followed. Refer to the appropriate language doc-

umentation for instructions. Refer to “Selecting the High-Level Language To Use”

on page 2-3 for a table that discusses the high-level languages.

In an OPM or ILE call, a parameter is an expression that represents a value that

the calling application passes to the API specified in the call. HLL languages use

the following methods for passing parameters:

by value, directly

The value of the data object is placed directly into the

parameter list.

by value, indirectly

The value of the data object is copied to a temporary

location. The address of the copy (a pointer) is placed

into the parameter list. By value, indirectly is not done

explicitly by the application programmer. It is done by

the operating system at run time.

by reference

A pointer to the data object is placed into the parameter

list. Changes made by the called API to the parameter

are reflected in the calling application.

Figure 2-4 illustrates these parameter passing styles. Not all HLL languages

support all styles.

By value, directly

a copy of argument

By value, indirectly

pointer

a copy of argument

By reference

the actual argument

pointer

RV2W1027-1

Figure 2-4. Methods for Passing Parameters

HLL semantics usually determine when data is passed by value and when it is

passed by reference. For example, ILE C passes and accepts parameters by

value, directly, while for OPM and ILE COBOL and OPM and ILE RPG parameters

are usually passed by reference. You must ensure that the calling program or pro-

Chapter 2. Getting Started with APIs 2-7

Download from Www.Somanuals.com. All Manuals Search And Download.

cedure passes parameters in the manner expected by the called API. The OPM or

ILE HLL programmer's guides contain more information on passing parameters to

different languages.

The ILE languages support the following parameter-passing styles:

Ÿ ILE C passes and accepts parameters by value (directly and indirectly) and by

reference.

Ÿ ILE COBOL and COBOL support the passing of parameters by value (indi-

rectly) and by reference.

Ÿ ILE RPG and RPG support the passing of parameters by reference.

Ÿ ILE CL and CL support the passing of parameters by reference.

Parameter Classification

Parameters can be classified into the following general categories:

Ÿ Input parameters: These parameters must be set to a value before calling the

API because they pass needed information to the API to enable it to perform its

function. For example, if the API is to perform a function on an object, one of

the parameters would be the name and library of that object. Input parameters

are not changed by the API.

Ÿ Output parameters: These parameters do not need to be set before calling the

API because the API returns information to the application in these parameters.

When a return to the application is successful and no errors have occurred, the

application then accesses the information returned in output parameters.

Ÿ Input/Output parameters: These are parameters that are identified as struc-

tures that contain fields. The fields within the structure can be either input,

output, or both. For example, the bytes provided field in the error code param-

eter is an input field. The rest of the fields that make up this parameter are

output fields. The rules for input parameters and output parameters apply to

the individual fields in the structure.

Error Code Parameter

The error code parameter is a variable-length structure that is a parameter for most

APIs. (UNIX-type APIs and ILE CEE APIs do not use the error code structure.)

The error code parameter controls how errors are returned to the application. The

parameter must be initialized before the program calls the API. Depending on how

the error code structure is set, this parameter either returns information associated

with an error condition or causes errors to be returned as exception messages.

For some APIs, the error code parameter is optional. If you do not code the

optional error code parameter, the API returns diagnostic and escape messages. If

you code the optional error code parameter, the API can either signal exceptions or

return the exception information in the error code parameter.

The structure for the error code parameter is discussed in the topic “Format of an

Error Code Structure” on page 3-12. It contains information about the error code

fields. Although the information is about an RPG example, the information is true

for other APIs.

Note: The error code structure is provided in the QSYSINC library and is called

QUSEC. Refer to Figure 2-5 on page 2-28 for a list of include files that are

shipped in the QSYSINC library.

2-8 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Receiving Error Conditions as Exceptions—Example

This example shows an application that receives error conditions as exceptions. It

allocates an error code parameter that is a minimum of 4 bytes long to hold the

bytes provided field. The only field used is the bytes-provided INPUT field, which

the application sets to zero to request exceptions. The error code parameter con-

tains the following:

Field

INPUT

OUTPUT

Bytes provided

Receiving the Error Code without the Exception Data—Example

This application example attempts to create an alert for message ID USR1234 in

message file USRMSG in library QGPL. It receives the error condition in the error

code parameter but does not receive any exception data. To do this, it allocates an

error code parameter that is a minimum of 16 bytes long—for the bytes provided,

bytes available, exception ID, and reserved fields. It sets the bytes-provided field of

the error code parameter to 16.

When the application calls the Generate Alert (QALGENA) API, the alert table

USRMSG is not found, and QALGENA returns exception CPF7B03. The error

code parameter contains the data shown in the following table. In this example, 16

bytes are provided for data, but 36 are available. Twenty more bytes of data could

be returned if the bytes-provided field were set to reflect a larger error code param-

eter (see “Receiving the Error Code with the Exception Data—Example”).

Field

INPUT

OUTPUT

Bytes provided

Bytes available

Exception ID

Reserved

Ignored

CPF7B03

Receiving the Error Code with the Exception Data—Example

This application example attempts to create an alert for message ID USR1234 in

message file USRMSG in library QGPL. It receives the error condition in the error

code parameter and receives exception data as well. To do this, it allocates an

error code parameter that is 116 bytes long—16 bytes for the bytes provided, bytes

available, exception ID, and reserved fields, and 100 bytes for the exception data

for the exception. (In some cases, the exception data might be a variable-length

directory or file name, so this might not be large enough to hold all of the data;

whatever fits is returned in the error code parameter.) Finally, it sets the bytes-

provided field to 116.

When the application calls the Generate Alert (QALGENA) API, the alert table

USRMSG is not found, and QALGENA returns exception CPF7B03. The error

code parameter contains the following:

Field

INPUT

116

OUTPUT

116

Bytes provided

Bytes available

Ignored

Chapter 2. Getting Started with APIs 2-9

Download from Www.Somanuals.com. All Manuals Search And Download.

Field

INPUT

Ignored

OUTPUT

CPF7B03

Exception ID

Reserved

Exception data

USRMSG

QGPL

Using the Job Log to Diagnose API Errors

Sometimes an API may issue one or more messages that state that the API failed,

and the messages may direct you to see the previously listed messages in the job

log. If your application program needs to determine the cause of the error

message, you can use the Receive Message (RCVMSG) command or the Receive

Message APIs to receive the messages that explain the reason for the error. In

some cases, you can write an application program to use the diagnostic message

to identify and correct the parameter values that caused the error.

Receiving Error Messages from the Job Log—Example

To receive error messages from the job log using a CL program, specify the fol-

lowing:

/ᑍ

ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ

ᑍ/

PROGRAM: CLRCVMSG

LANGUAGE: CL

DESCRIPTION: THIS PROGRAM DEMONSTRATES HOW TO RECEIVE

DIAGNOSTIC MESSAGES FROM THE JOB LOG

APIs USED: QUSCRTUS

/ᑍ

ᑍ/

CLRCVMSG:

PGM

DCL

VAR(&MSGDATA) TYPE(ᑍCHAR) LEN(8ð)

VAR(&MSGID) TYPE(ᑍCHAR) LEN(7)

VAR(&MSGLEN) TYPE(ᑍDEC) LEN(5 ð)

MONMSG

CALL

MSGID(CPF3Cð1) EXEC(GOTO CMDLBL(GETDIAGS))

PGM(QUSCRTUS) PARM('!BADNAME !BADLIB

'!BADEXATTR' -1 '@' 'ᑍBADAUTH ' 'Text +

Description')

' +

/ᑍ IF WE MAKE IT HERE, THE SPACE WAS CREATED OK

GOTO CMDLBL(ALLDONE)

ᑍ/

/ᑍ IF THIS PART OF THE PROGRAM RECEIVES CONTROL, A CPF3Cð1

/ᑍ WAS RECEIVED INDICATING THAT THE SPACE WAS NOT CREATED.

ᑍ/

/ᑍ THERE WILL BE ONE OR MORE DIAGNOSTICS THAT WE WILL RECEIVE ᑍ/

/ᑍ TO DETERMINE WHAT WENT WRONG. FOR THIS EXAMPLE WE WILL

/ᑍ JUST USE SNDPGMMSG TO SEND THE ID'S OF THE MESSAGES

/ᑍ RECEIVED.

ᑍ/

GETDIAGS:

RCVMSG

PGMQ(ᑍSAME) MSGQ(ᑍPGMQ) MSGTYPE(ᑍDIAG) +

WAIT(3) RMV(ᑍNO) MSGDTA(&MSGDATA) +

MSGDTALEN(&MSGLEN) MSGID(&MSGID)

COND(&MSGID = '

CMDLBL(ALLDONE))

CMD(DO)

') THEN(GOTO +

ELSE

SNDPGMMSG MSG(&MSGID)

GOTO

ENDDO

CMDLBL(GETDIAGS)

2-10 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

ALLDONE:

ENDPGM

As an alternative to using the job log, the following RPG program uses the error

code structure to receive error messages:

Hᑍ ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Hᑍ

ᑍ

Hᑍ MODULE: ERRCODE

Hᑍ

Hᑍ LANGUAGE: RPG

Hᑍ

Hᑍ FUNCTION: THIS APPLICATION DEMONSTRATES THE USE OF THE

Hᑍ

ERROR CODE PARAMETER.

Hᑍ APIs USED: QHFRTVAT, QHFCRTDR

Hᑍ

Hᑍ ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Hᑍ

ᑍ

Hᑍ THIS PROGRAM DOES SOME SIMPLE VERIFICATION ON AN HFS

Hᑍ DIRECTORY. THE QHFRTVAT API IS USED TO VERIFY THE EXISTENCE ᑍ

Hᑍ OF THE SPECIFIED DIRECTORY. IF THE DIRECTORY DOES NOT EXIST, ᑍ

Hᑍ AN ATTEMPT IS MADE TO CREATE THE DIRECTORY.

ᑍ

Hᑍ

Hᑍ THERE ARE THREE PARAMETERS TO THIS PROGRAM

Hᑍ

INPUT

PATHNM - NAME OF DIRECTORY

PATHLN - LENGTH OF PATHNM PARAMETER

OUTPUT SUCCES - INDICATES SUCCESS OR FAILURE

'ð' SUCCESS

'1' FAILURE

Hᑍ ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

ISUCCES

4ðRETCOD

4ðPATHLN

IPLENG

IBINS

4ðRETDTA

8ðATTRLN

IERROR

Cᑍ

4ðBYTPRV

8ðBYTAVA

9 15 ERRID

16 16 ERR###

17 272 INSDTA

ᑍENTRY

PLIST

PARM

PATHNM 8ð

PLENG

SUCCES

Cᑍ INITIALIZE BYTES PROVIDED AND THE ATTRIBUTE LENGTH VARIABLE

Cᑍ

Z-ADD272

Z-ADDð

BYTPRV

ATTRLN

Cᑍ RETRIEVE DIRECTORY ENTRY ATTRIBUTES

Cᑍ

CALL 'QHFRTVAT'

PARM

PATHNM

PATHLN

ATTR

ATTRLN

ATTR

ATTRLN

RETDTA

ERROR

Cᑍ CHECK FOR DIRECTORY NOT FOUND OR FILE NOT FOUND ERRORS.

Cᑍ IF WE RECEIVE ONE OF THESE THIS IS THE INDICATION THAT

Cᑍ WE CAN TRY TO CREATE THE DIRECTORY.

Cᑍ

BYTAVA

IFEQ ᑍZERO

Chapter 2. Getting Started with APIs 2-11

Download from Www.Somanuals.com. All Manuals Search And Download.

Z-ADDð

ELSE

'CPF1Fð2' IFEQ ERRID

'CPF1F22' OREQ ERRID

RETCOD

Cᑍ ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Cᑍ THERE IS NO NEED TO REINITIALIZE THE ERROR CODE PARAMETER.

Cᑍ ONLY BYTES PROVIDED IS INPUT TO THE API; IT WILL RESET THE

Cᑍ ERROR CODE PARAMETER FOR US. AFTER THE CALL TO QHFCRTDR,

Cᑍ BYTES AVAILABLE WILL EITHER BE ð IF SUCCESSFUL OR NONZERO

Cᑍ IF THE CREATE FAILS. WE DO NOT HAVE TO WORRY ABOUT THE

Cᑍ PREVIOUS ERROR CODE BEING LEFT IN THE ERROR CODE PARAMETER.

Cᑍ ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

CALL 'QHFCRTDR'

PARM

PARM 2ð

PARM

PARM ð

PARM

IFEQ ᑍZERO

Z-ADDð

ELSE

PATHNM

PATHLN

ATTR

ATTRLN

ERROR

BYTAVA

RETCOD

Z-ADD1

END

Cᑍ

ELSE

Z-ADD1

END

RETCOD

Cᑍ

END

Cᑍ PROGRAM END

Cᑍ

SETON

Related Information

Ÿ “Retrieving the Hold Parameter (Exception Message)—OPM RPG Example” on

page 3-6

Ÿ “Error Handling” on page 4-5

Ÿ The “API Error Reporting” topic in Chapter 2 of the System API Reference,

SC41-5801

Internal Identifiers

You know of jobs, spooled files, and so forth, by their names. The system uses an

ID that is associated with the name. The ID is assigned based on usage. Several

of the APIs either require or allow you to use an internal ID. When you use an

internal ID, it is generally faster because the system does not have to convert the

external name to the internal ID.

A variety of terminology is used to identify internal IDs. For example:

Ÿ Work Management uses an internal job identifier.

Ÿ Spooling uses an internal spooled file identifier.

Ÿ Security uses the term handle to mean the user profile that is currently running

the job.

Ÿ Message handling uses the term message key (also appears on CL com-

mands) to identify a message in a message queue.

The internal values are often accessed in one API and then used in another. For

example, if you want a list of jobs, you would use the List Jobs (QUSLJOB) API,

which provides the internal job ID for each job in the list. You could then use the

2-12 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

User Spaces

internal job ID to access a spooled file for a job with the Retrieve Spooled File

Attributes (QUSRSPLA) API.

User Spaces

APIs that return information to a caller generally return the information in a user

space (used by list APIs) or a receiver variable (used by retrieve APIs).¹

The list APIs require a user space for returning information. A user space is an

object type that is created by the Create User Space (QUSCRTUS) API. Gener-

ally, a user space is used when information about more than one object is being

requested.

Following are some of the advantages of using user spaces:

Ÿ User spaces can be automatically extendable.

Ÿ User spaces can be shared across jobs.

Ÿ User spaces can exist across IPLs.

Most lists returned by APIs are made up of a series of entries where each entry is

a data structure. Special fields are placed in the user space at consistent locations

that describe:

Ÿ Where the list begins.

Ÿ The number of entries. The topic “Logic Flow of Processing a List of Entries”

on page 2-15 shows the logic for processing a list of entries.

Ÿ The length of each entry.

User spaces are used for such functions as returning either a list of members in a

file or objects in a library. When you use one of the list APIs, the parameter list

requires that you name the user space that will be used.

User spaces can be processed in two ways:

Ÿ If your language supports pointers, you can access or change the information

directly. Figure 2-2 on page 2-3 describes each supported language and

whether it supports pointers. Generally, pointer access is faster than API

access.

Ÿ For languages that do not support pointers, you can use APIs to access or

change the data in a user space. For example, the data in a user space can

be accessed by the Retrieve User Space (QUSRTVUS) API. The API identifies

a receiver variable that receives a number of bytes of information from the user

space.

You can pass the user space as a parameter to a program. You do need to use a

language that has pointer support to be able to pass the address of the first byte of

the user space as a parameter to the processing program. “Retrieving a File

Description to a User Space—Examples” on page B-152 shows an example of

pointer support.

A user space is an object consisting of a collection of bytes that can be used for storing any user-defined information. A receiver

variable is a program variable that is used as an output field to contain information that is returned from an API.

Chapter 2. Getting Started with APIs 2-13

Download from Www.Somanuals.com. All Manuals Search And Download.

User Spaces

User Space Format—Example

Following is an example of the format of a user space. This example does not

contain all of the fields in the fixed portion of a user space.

User Space

Fixed locations

┌────────────────────────┐

in the user space

──────────────────

│

XXXX ─────┼───5 Offset to data section

│

XXXX ─────┼───5 Number of list entries

│

XXXX ─────┼───5 Size of each entry

│

2nd entry ───│─────────────────┐

│

│ Variable locations in the

│ user space

│ ─────────────────────────

1st entry ───│──┐

│

│AAAAABBBBCCCDDDEEAAAABB │────5 List of entries

│BBBCCCDDDEEAAAABBBBBCCD │

│DDDEEAAAABBBBCCCDDDEE.. │

└────────────────────────┘

2-14 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

User Spaces

Logic Flow of Processing a List of Entries

When you process a list containing multiple entries, the logic flow looks as follows:

┌────────────────────────┐

│

Initialize the next │

entry with 'Where │

the list begins' │

└────────────┬───────────┘

│

┌────────────────────────┐

│

Have all of the

entries been

processed?

│ YES

├───────┐

┌───────5│

│

└────────────┬───────────┘

│

│NO

List is

complete

┌────────────────────────┐

│

│ Access the entry. Use │

│ the next entry value │

│ as an index.

└───────────┬────────────┘

│

┌────────────────────────┐

│

Process

the

entry

│

└────────────┬───────────┘

│

┌────────────────────────┐

│

Add the length of │

each entry

│

│ to the next entry

└────────────┬───────────┘

│

┌────────────────────────┐

│ Add 1 to a count of │

│

how many have

been processed

│

└────────────┬───────────┘

│

└─────────────────────┘

It is important from an upward compatibility viewpoint to use the offset, length of

each entry, and the number of entries rather than hard coding the values in your

program.

Related Information

Ÿ The User Space API chapter of the System API Reference, SC41-5801

Ÿ The “User Space Format for List APIs” topic in Chapter 2 of the System API

Reference, SC41-5801

Chapter 2. Getting Started with APIs 2-15

Download from Www.Somanuals.com. All Manuals Search And Download.

Manipulating a User Space with Pointers

Some languages, such as ILE C', VisualAge C++ for OS/400, ILE COBOL, ILE

RPG, COBOL, Pascal, and PL/I, support pointers. Pointers allow you to manipulate

information more rapidly from the user space. To use pointers with the OS/400

APIs, you should understand how to:

Ÿ Synchronize between two or more jobs

Ÿ Use offset values with pointers

Ÿ Update usage data

Synchronizing between Two or More Jobs

If you are using the Change User Space (QUSCHGUS) or Retrieve User Space

(QUSRTVUS) API to manipulate user spaces, you do not need to synchronize

update and retrieve operations when multiple jobs access the user space. The

APIs already do that for you. However, if you are using space pointers to retrieve

the information directly from the user space, you should synchronize your applica-

tion programs to avoid data errors. This ensures that no two users update the

space at the same time, which can cause unpredictable results.

Locks are typically used to synchronize two jobs on the system, and you can lock

user spaces. To synchronize multiple jobs, you can use one of the following:

Ÿ Compare and swap (CMPSWP MI instructions)

Ÿ Space location locks (LOCKSL and UNLOCKSL MI instructions)

Ÿ Object locks (LOCK and UNLOCK MI instructions)

Ÿ Allocate Object (ALCOBJ) and Deallocate Object (DLCOBJ) commands

The preceding list is ordered by relative performance where CMPSWP is the

fastest. If you do not synchronize two or more jobs, multiple concurrent updates to

the user space or read operations can occur while information is being updated.

As a result, the data may not be accurate.

Using Offset Values with Pointers

When using a pointer to manipulate the user space, you must:

1. Get a space pointer to the first byte (offset value of zero) of the user space.

2. Retrieve the offset value of the information you want to use from the user

space.

3. Add that offset value to the space pointer value.

4. Use the space pointer value to directly refer to the information in the user

space.

See “Changing a User Space with an ILE RPG Program—Example” on page 2-20

for an example of this procedure.

Updating Usage Data

If you are using the Change User Space (QUSCHGUS) or Retrieve User Space

(QUSRTVUS) API to manipulate user spaces, you do not need to update usage

data information. If you directly retrieve data using pointers, your application pro-

grams should update the usage data information. To do this, use the QUSCHGUS

API to update the date last changed and use the QUSRTVUS API to update the

date last retrieved. You do not need to do this for each retrieve or change opera-

tion to the user space, but you should do this once within each application program

to maintain accurate usage data information.

2-16 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Manipulating a User Space without Pointers

When programming in a language that does not support pointers, you can use the

Change User Space (QUSCHGUS) and Retrieve User Space (QUSRTVUS) APIs

to manipulate data. However, you must first understand how to use positions and

lengths with these APIs.

Position Values

Some APIs return offset values into a user space. To use other APIs, such as the

Retrieve User Space (QUSRTVUS) API, you must use position values to locate

bytes.

Position values and offset values are different ways to express the same thing. An

offset value is the relative distance of a byte from the first byte of the user space,

which has an offset value of 0. A position value is the offset value plus 1.

For examples of HLL programs that use positions, see “List Object API—OPM RPG

Example” on page 5-4.

Lengths

List APIs return the length of the information in the different sections of the user

space, as well as the length of the list entries in the user space. You should code

your application using the lengths returned instead of specifying the current length

returned by the API or the size of a data structure in the data structure files. The

amount of information returned for any format may increase in future releases, but

the information will be placed at the end of the existing information. In order for

your application to function properly, it should retrieve the length of the information

returned and add that length to a pointer or to a starting position.

Using Offset Values with the Change and Retrieve User Space

APIs

When you use the Change User Space (QUSCHGUS) or Retrieve User Space

(QUSRTVUS) API, your application program should first retrieve the offset value for

the information you want. You must then add one to the offset value to get the

starting position for the information.

Changing a User Space—Example

Before and after illustrations show how the QUSCHGUS API changes a user

space. The following is a user space before you change it with one of the change

examples.

Chapter 2. Getting Started with APIs 2-17

Download from Www.Somanuals.com. All Manuals Search And Download.

Manipulating a User Space without Pointers

Area that will change

after using the

Change User Space

(QUSCHGUS) API

RV3F089-0

2-18 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Manipulating a User Space without Pointers

The following is a user space after you change it with one of the change examples.

Area changed

after using the

Change User Space

(QUSCHGUS)

RV3F088-0

Chapter 2. Getting Started with APIs 2-19

Download from Www.Somanuals.com. All Manuals Search And Download.

Manipulating a User Space without Pointers

Changing a User Space with an ILE RPG Program—Example

To change the user area of a user space as shown in the previous example with a

call from an ILE RPG program, specify the following:

Hᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Hᑍ

Hᑍ PROGRAM: CHANGUSPTR

Hᑍ

Hᑍ LANGUAGE: ILE RPG for OS/4ðð

Hᑍ

Hᑍ DESCRIPTION: CHANGE THE CONTENTS OF INFORMATION IN THE USER

Hᑍ

AREA IN THE USER SPACE USING A POINTER

Hᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Dᑍ

DUSRSPCNAM

DNEWVALUE

DUSRSPCPTR

DUSERAREA

D CHARFIELD

Dᑍ

2ð

INZ('TEMPSPACE QTEMP

INZ('Big String padded with blanks')

ᑍ

BASED(USRSPCPTR)

Dᑍ Following QUSEC structure copied from QSYSINC library

Dᑍ

DQUSEC

Dᑍ

D QUSBPRV

Dᑍ

D QUSBAVL

Dᑍ

D QUSEI

Dᑍ

Qus EC

4B ð

8B ð

Bytes Provided

Bytes Available

Exception Id

Reserved

D QUSERVED

Dᑍ

Dᑍ End of QSYSINC copy

Dᑍ

Cᑍ

Cᑍ Initialize Error code structure to return error ids

Cᑍ

Z-ADD

QUSBPRV

Cᑍ Set USRSPCPTR to the address of the User Space

Cᑍ

CALL

PARM

'QUSPTRUS'

USRSPCNAM

USRSPCPTR

QUSEC

Cᑍ

Cᑍ Check for successful setting of pointer

Cᑍ

QUSBAVL

IFGT

Cᑍ If an error, then display the error message id

Cᑍ

DSPLY

ELSE

QUSEI

Cᑍ

Cᑍ Otherwise, update the User Space via the based structure

Cᑍ

MOVEL

END

NEWVALUE

USERAREA

Cᑍ

Cᑍ And return to our caller

Cᑍ

SETON

RETURN

2-20 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Manipulating a User Space without Pointers

Changing a User Space with an OPM RPG Program—Example

To change the user area of a user space with a call from an OPM RPG program,

specify the following:

Hᑍ ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Hᑍ

ᑍ

Hᑍ PROGRAM: CHANGUS

Hᑍ

Hᑍ LANGUAGE: RPG

Hᑍ

Hᑍ DESCRIPTION: THIS PROGRAM WILL CHANGE THE CONTENTS OF

Hᑍ

INFORMATION IN THE USER AREA IN THE USER SPACE ᑍ

(FIRST 64 BYTES).

ᑍ

Hᑍ APIs USED: QUSCHGUS

Hᑍ

Hᑍ ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

ARY

CHG

1 2ð

1 64

IUSRSPC

1 1ð USNAME

11 2ð USLIB

4ðLENDTA

8ðSTRPOS

Cᑍ

ᑍ

Cᑍ ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Cᑍ

ᑍ

OPERABLE CODE STARTS HERE

Cᑍ ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Cᑍ

ᑍ

Cᑍ MOVE THE USER SPACE AND LIBRARY NAME FROM ARY ARRAY INTO THE ᑍ

Cᑍ USRSPC DATA STRUCTURE. ALSO, MOVE THE NEW USER DATA FROM

ᑍ

Cᑍ CHG ARRAY INTO NEWVAL.

Cᑍ

MOVELARY,1

MOVELCHG,1

USRSPC

NEWVAL 64

Cᑍ

ᑍ

LEN OF USERAREA

STARTING POS

FORCE PARM

ᑍ

Z-ADD64

Z-ADD1

LENDTA

STRPOS

MOVE '1'

FORCE

Cᑍ

Cᑍ CALL THE QUSCHGUS API WHICH WILL CHANGE THE USER AREA IN THE ᑍ

Cᑍ USER SPACE.

ᑍ

Cᑍ

CALL 'QUSCHGUS'

PARM

USRSPC

STRPOS

LENDTA

NEWVAL

FORCE

Cᑍ

ᑍ

Cᑍ IF MORE OF THE USER SPACE NEEDS TO BE CHANGED, THIS PROGRAM

Cᑍ COULD BE UPDATED TO LOOP UNTIL THE END OF THE ARRAY WAS

Cᑍ REACHED.

Cᑍ

SETON

RETRN

ᑍᑍ ARY

TEMPSPACE QGPL

ᑍᑍ CHG

Big String padded with blanks

Chapter 2. Getting Started with APIs 2-21

Download from Www.Somanuals.com. All Manuals Search And Download.

Additional Information about List APIs and a User Space

Before you can use a list API to create a list, the *USRSPC object must exist.

If the user space is too small to contain the list and you have *CHANGE authority

to the user space, the list API extends the user space to the nearest page

boundary. If the user space is too small and you do not have *CHANGE authority,

an authority error results. An extended user space is not truncated when you run

the API again.

When you are creating a list into a user space and the user space cannot hold all

of the available information (the list is greater than 16MB in length), the API places

as much information as possible in the user space and sends a message (typically

CPF3CAA) to the user of the API. The returned list contains only the number of

entries that can fit inside the user space (not the total number of entries available).

Listing Database File Members with a CL Program—Example

To generate a list of members that start with M and are in file QCLSRC in library

QGPL, specify the following:

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ

ᑍ/

/ᑍ PROGRAM: LSTMBR2

/ᑍ

/ᑍ LANGUAGE: CL

/ᑍ

/ᑍ DESCRIPTION: THIS PROGRAM WILL GENERATE A LIST OF MEMBERS, ᑍ/

/ᑍ

THAT START WITH M, AND PLACE THE LIST INTO A

USER SPACE NAMED EXAMPLE IN LIBRARY QGPL.

ᑍ/

/ᑍ APIs USED: QUSCRTUS, QUSLMBR

/ᑍ

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

PGM

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ

CREATE A ᑍUSRSPC OBJECT TO PUT THE LIST INFORMATION INTO. ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

CALL QUSCRTUS

('EXAMPLE

'EXAMPLE

X'ððððð12C'

' '

QGPL

' /ᑍ USER SPACE NAME AND LIB

/ᑍ EXTENDED ATTRIBUTE

/ᑍ SIZE OF USER SPACE

/ᑍ INITIALIZATION VALUE

/ᑍ AUTHORITY

ᑍ/ +

'ᑍCHANGE

'USER SPACE FOR QUSLMBR EXAMPLE

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ

LIST THE MEMBERS BEGINNING WITH "M" OF A FILE CALLED

QCLSRC FROM LIBRARY QGPL USING THE OUTPUT FORMAT MBRLð2ðð. ᑍ/

OVERRIDE PROCESSING SHOULD OCCUR. ᑍ/

ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

CALL QUSLMBR

('EXAMPLE

'MBRLð2ðð'

'QCLSRC

'Mᑍ

QGPL

' /ᑍ USER SPACE NAME AND LIB

/ᑍ FORMAT NAME

ᑍ/ +

QGPL

' /ᑍ DATABASE FILE AND LIBRARY ᑍ/ +

/ᑍ MEMBER NAME

/ᑍ OVERRIDE PROCESSING

ᑍ/ +

ᑍ/

'1')

ENDPGM

2-22 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Receiver Variables

Some APIs use receiver variables to place returned information. For example,

instead of using a user space to return the information, the information is placed in

a receiver variable. A retrieve API requires only addressability to storage of fixed

size (typically a field or structure defined in your program), whereas a list API

requires a user space because the amount of information returned by a list API

may be large and not of a predictable size.

Retrieve APIs that return information to a receiver variable use the storage provided

for the receiver variable parameter. The returned information is in a specific format.

The format name is usually a parameter on the call to the API, and the format indi-

cates to the API the information that you want returned. On the return from the call

to the API, the caller parses through the receiver variable and extracts the informa-

tion that is needed. The caller knows how the information is returned by the docu-

mented format of the information. An API may have one or many formats that give

you the flexibility to choose the information that you need. Chapter 3, “Common

Information across APIs—Basic (OPM) Example” on page 3-1 contains several

examples of using receiver variables.

Some formats have variable-length fields, some only fixed-length fields, and yet

others have repeating entries. To move through the information, some formats use

offsets, some use lengths, and some use displacements. When the field is defined

as an offset, the offset is always the number of bytes from the beginning of the

receiver variable. When a length or displacement is used to move through the

receiver variable entries, the length is always added to the current position within

the receiver variable. For examples of repeating entry types and the various ways

to move through receiver variable entries, see “Receiver Variables—Examples” on

page 4-7.

Offsets and displacements are not the same. An offset is relative to the beginning

of a receiver variable or the beginning of a user space, whereas a displacement is

relative to the current position of the pointer plus the value within the displacement

field. If a format uses a displacement, you will see the word displacement in the

Field column of the API description.

Bytes Available and Bytes Returned Fields

Most formats used by retrieve APIs have a bytes available field and a bytes

returned field. The bytes available field contains the length in bytes of all the data

available to be returned to the user. The bytes returned field contains the length in

bytes of all the data that is actually returned to the user.

All available data is returned if enough space is provided in the receiver variable. If

the size of the receiver variable is at least large enough to contain all of the data,

the bytes returned field equals the bytes available field. If the receiver variable is

not large enough to contain all of the data, the bytes available field contains the

number of bytes that can be returned.

Your code could check the values for both the bytes available and bytes returned

fields. If the bytes available field is greater than the bytes returned field, the API

had more information to return than what would fit in the receiver variable. This

could occur, over time, because the APIs that you use may be enhanced with new

releases. The API may also have more information to return if the receiver variable

is being used to return a variable-length field (or array) and a very large value was

Chapter 2. Getting Started with APIs 2-23

Download from Www.Somanuals.com. All Manuals Search And Download.

returned on this API call. If both values are the same, the API returned all the

information.

Depending on the capabilities of your high-level language, some API users take

advantage of the following technique to avoid guessing the appropriate size for the

receiver variable:

1. Call the API with a receiver variable length of 8 bytes (that is, just enough for

the bytes available and the bytes returned fields).

2. Dynamically allocate an amount of storage equivalent to the bytes available.

3. Set the length of receiver variable parameter to the amount of storage allo-

cated.

4. Pass the address of the storage allocated in step 2 by using pass by value

(directly).

This technique provides for highly flexible use of APIs that can return variable

amounts of data.

Keyed Interface

Some APIs have a keyed interface for selecting what information you want

returned. A keyed interface allows the user of the API to provide information to

the API through the use of keys. Keys are API-specific values that inform the API

that a certain function should be performed. Keys also are used to pass informa-

tion to an API or to retrieve information from an API.

Through the use of keys, you can be more selective; you can choose one item or a

number of items rather than all of them. For example, using the List Job

(QUSLJOB) API, you can receive selected information about a job based on the

keys that you specify. If you want job information about the output queue priority,

you only need to specify the output queue priority key.

The keys are typically supplied to an API and are passed to the API using a

variable-length record (there are some exceptions). A variable-length record is a

collection of information that specifies the key being used and the data that is asso-

ciated with the key. If a given structure contains binary values, it must be 4-byte

aligned. “Defining Byte Alignment” on page 9-22 shows examples of correctly and

incorrectly defining byte alignment.

Some APIs that use variable-length records in addition to the List Job API are the

Change Object Description (QLICOBJD) API and the Register Exit Point

(QUSRGPT, QusRegisterExitPoint) API. You can use the appropriate include file in

member QUS in the system include (QSYSINC) library when you have variable-

length records as either input or output.

A keyed interface provides an easy-to-use means for later enhancing an API

without affecting the user who chooses not to use the enhancements. For exam-

ples that use a keyed interface, see “Using Keys with List Spooled Files

API—Example” on page 3-24 (OPM RPG) and “Keyed Interface—Example” on

page 4-3 (ILE C).

2-24 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

User Space Alternative

Although a receiver variable is usually used for returning information from a retrieve

API, sometimes a user space should be used instead. If the number of bytes of

information being returned is not known or is large, a user space is preferred. You

can create a user space so that it can automatically extend up to 16MB of storage

to accommodate the information being retrieved.

The disadvantage of using a receiver variable when it may be too small for the

amount of data being returned is that the API must be called again to receive the

remaining data.

For an example of using a user space to return information from a retrieve API, see

“Retrieving a File Description to a User Space—ILE C Example” on page A-11.

Related Information

Ÿ For a discussion of variable-length structures using ILE C, see “Variable-Length

Structure—Example” on page 4-3.

Ÿ For an example using the Register Exit Point (QusRegisterExitPoint) API, see

“Register Exit Point and Add Exit Program—ILE C Example” on page 4-9.

Ÿ For an example using the Change Object Description (QLICOBJD) API in RPG,

see “Program for Packaging a Product—OPM RPG Example” on page A-3.

The change object information parameter is defined as the COBJI field, and

this field is later used by the QLICOBJD API.

Ÿ For a discussion of include files, see “APIs and the QSYSINC Library” on

page 2-28.

Continuation Handle

Some APIs that return information offer a continuation handle. A continuation

handle is a value that is passed between a high-level language program and an

API. It is used to mark the last value put in either the receiver variable or the user

space. When a call to an API is made and the API has more information to return

than what could fit in the receiver variable or user space provided by the caller, the

API returns a continuation handle. If a continuation handle is returned to the caller

because there is more information to return, the caller can then call the API again

and pass the continuation handle that was returned. The API continues to return

information from the point that it left off on the call that generated the continuation

handle.

When you use the continuation handle parameter, that is the only parameter that

can change. All other parameters must appear as they did on the call to the API

that generated the continuation handle to obtain predictable results.

Using a Continuation Handle

To make use of a continuation handle, do the following:

1. Blank out the continuation handle to let the API know that this is a first attempt

at the retrieve operation.

2. Call the API to retrieve the information.

3. Make use of the information returned.

Chapter 2. Getting Started with APIs 2-25

Download from Www.Somanuals.com. All Manuals Search And Download.

4. If the continuation handle field in the receiver variable is not set to blanks, do

the following steps until the continuation handle equals blanks:

a. Copy the continuation handle from the receiver variable to the continuation

handle parameter.

b. Call the API again by using the continuation handle that is returned. Keep

all other parameters the same as the original API call.

For a program example that uses a continuation handle, see “Retrieve Exit Point

and Exit Program Information—ILE C Example” on page 4-13.

Domain Concepts

All objects are assigned a domain attribute when they are created. A domain is a

characteristic of an object that controls how programs can access the object. Once

set, the domain remains in effect for the life of the object. The two possible attri-

butes are system and user.

Most object types on the system are created in system domain. When you run

your system at security level 40 or 50, system domain objects can be accessed

only by using the commands and callable APIs provided.

These object types can be either system or user domain. The list includes the

symbolic object type.

Ÿ User space (*USRSPC)

Ÿ User index (*USRIDX)

Ÿ User queue (*USRQ)

Objects of the type *USRSPC, *USRIDX, and *USRQ in the user domain can be

manipulated directly by MI instructions without using the system-provided APIs and

commands.

Note: Objects of the type *PGM, *SRVPGM, and *SQLPKG also can be in the

user domain. Their contents cannot be manipulated directly by MI

instructions.

Prior to Version 2 Release 3 Modification 0, all user objects were created into the

user domain. Starting in Version 2 Release 3 Modification 0, user objects can exist

in either the user domain or the system domain. The allow user domain

(QALWUSRDMN) system value determines which libraries can contain user-domain

user objects. The default QALWUSRDMN system value is set to *ALL, but can be

changed by system administrators on individual machines to be one library or a list

of libraries. If your application requires direct pointer access to user-domain user

objects in a library that is not specified in the QALWUSRDMN value, your system

administrator can add the library to the system value.

The ability to create user domain objects on a system with a security level 40 or 50

is controlled by the allow user domain (QALWUSRDMN) system value. See the

table in the description of the Create User Queue (QUSCRTUQ) API in the System

API Reference for more information.

2-26 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Note: On a system configured for C2²system security, QALWUSRDMN is set to

QTEMP (only the QTEMP library can contain user-domain user objects).

For more information about C2 security, refer to the Guide to Enabling C2

Security book, SC41-0103.

Related Information

Ÿ “Using Data Queues versus User Queues” on page A-15

Ÿ Create User Index (QUSCRTUI), Create User Queue (QUSCRTUQ), and

Create User Space (QUSCRTUS) APIs in the Object part of the System API

Reference, SC41-5801

Ÿ Chapter 2 of the Security – Reference, SC41-5302

Exit Programs

Exit programs are called and given control by an application program or system

program. They can be used to customize particular functions to your needs. An

exit program is a program to which control is passed from a calling program.

Exit programs are usually user-written programs; however, a few are system-

supplied (such as a few of the Operational Assistant exit programs).

To transfer control to an exit program, you do an external call as you would to any

other program.

There are no general requirements for using exit programs. For any specific

requirements, see the documentation for the specific exit program.

Exit Points

An exit point signifies the point in a system function or program where control is

turned over to one or more exit programs to perform a function.

Prior to Version 3 Release 1, the exit program might have been represented as

network attributes, system values, CL command parameters, or attributes of system

objects. Also, in previous releases, all exit point providers had to supply their own

means of registering and deregistering exit programs.

The registration facility provides a central point to store and retrieve information

about OS/400 and non-OS/400 exit points and their associated exit programs. This

information is stored in the registration facility repository and can be retrieved to

determine which exit points and exit programs already exist.

You can use the registration facility APIs to register and deregister exit points, to

add and remove exit programs, and to retrieve information about exit points and

exit programs. You can also perform some of these functions by using the Work

with Registration Information (WRKREGINF) command.

C2 is a level of security defined in the Trusted Computer System Evaluation Criteria (TCSEC) published by the United States

Government.

Chapter 2. Getting Started with APIs 2-27

Download from Www.Somanuals.com. All Manuals Search And Download.

The exit point provider is responsible for defining the exit point information,

defining the format in which the exit program receives data, and calling the exit

program.

Related Information

Ÿ For more information about the registration facility, see the Registration Facility

part in the System API Reference, SC41-5801.

Ÿ For an example of adding an exit program to an exit point, see the topic “Reg-

ister Exit Point and Add Exit Program—ILE C Example” on page 4-9.

Ÿ For an example of calling an exit program to retrieve information in the registra-

tion facility repository, see the topic “Retrieve Exit Point and Exit Program

Information—ILE C Example” on page 4-13.

APIs and the QSYSINC Library

The QSYSINC (system include) library provides source include files shipped with

the AS/400 system for OS/400 APIs. This optionally installable library is fully sup-

ported, which means that you can write APARs if you find a problem.

You can install this library by using the GO LICPGM functions of OS/400. Select

the Install Licensed Programs option on the Work with Licensed Programs display

and the OS/400 - Openness Includes option on the Install Licensed Programs

display.

The terms include file and header file are interchangeable and pertain to the con-

tents of the QSYSINC library. These files are intended to be compatible with future

releases.

The naming conventions for the include files are the same as either the OPM API

name or the ILE service program name. If the API has a callable and a bindable

interface, an include file exists with both names.

The following table shows the API include files that are shipped with the QSYSINC

library:

Figure 2-5 (Page 1 of 2). Include Files Shipped with the QSYSINC Library

Operating

Language

File Name

Member Name (Header File)

Environment

OPM APIs

ILE C¹

RPG

OPM API program name

QRPGSRC

OPM API program name or OPM

API program name with the letter

E replacing the letter Q for

members containing array defi-

nitions

ILE RPG

COBOL

QRPGLESRC

QLBLSRC

OPM API program name

OPM API name

ILE COBOL

QCBLLESRC

OPM API program name

2-28 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Figure 2-5 (Page 2 of 2). Include Files Shipped with the QSYSINC Library

Operating

Language

File Name

Member Name (Header File)

Environment

ILE APIs

ILE C

Service program name or API

program name²

ILE RPG

ILE COBOL

QRPGLESRC

QCBLLESRC

Service program name or API

program name²

Service program name or API

program name²

UNIX type

ILE C

ARPA

Industry defined

NET

NETINET

SYS

Notes:

CEE ILE APIs are included in this part of the table.

The API can be either bindable when you use the service program name or callable

when you use the API program name.

For development of client-based applications, the integrated-file-system symbolic

links to QSYSINC openness includes are provided in the /QIBM/include path.

Include files for exit programs are shipped only if the exit program has a structure.

The member names for these exit programs start with the letter E. Except for RPG

array definitions for APIs that also start with E, any member names in the

QSYSINC library that start with the letter E are include files for exit programs.

Refer to the System API Reference for the actual member names for the exit pro-

grams.

All source physical files are shipped with read capabilities only; changes cannot be

made to the QSYSINC library. All are built with a CCSID of 00037. When you

compile a program in a specific CCSID, any QSYSINC include file is converted to

the program CCSID.

If you are coding in ILE C, the header files in the QSYSINC library are considered

system include files. You should use the < and > symbols on the #include state-

ment; this affects how the library list is used to search for header files.

If you are coding in RPG or COBOL and need to define storage for variable length

fields, you should copy the appropriate QSYSINC system include to a user source

library. You can then customize the include file to your specific needs and use the

customized member when you compile your application.

If you are developing applications on a release n system that will run on a

release n-1 system, you may want to copy each release's include files to user

source libraries. This will minimize the impact of include file changes as APIs are

enhanced over time with additional fields.

Chapter 2. Getting Started with APIs 2-29

Download from Www.Somanuals.com. All Manuals Search And Download.

User Index Considerations

Related Information

Ÿ Chapter 2 in the System API Reference, SC41-5801

APIs and the QUSRTOOL Library

QUSRTOOL, an optionally installable library, has several tools that use APIs and

include files (header files) for APIs. You can use the code as a model for your

programming. As of Version 3 Release 6, source include files will be removed from

this library. APARs against the offerings in QUSRTOOL are not allowed. There is

no support for enhancements or fixes to the contents of the library other than a

complete reshipment that occurs with each release. If you intend to use the tools,

you should copy the members that you plan to use to your own source libraries.

User Index Considerations

The performance of a user index is much better than that of a database file.

However, before using a user index, you must know the functional differences

between a user index and a database file.

The contents of a database file are not affected by an abnormal system end. On

the other hand, the contents of a user index may become totally unusable if the

system ends abnormally. Therefore, you should not use a user index if the infor-

mation you want to store needs to remain without errors after an abnormal system

end.

If your system abnormally ends when you are removing or inserting a user index

entry, unpredictable results may occur. If you are inserting or removing a user

index entry and you do not force the index entry to the disk unit using one of the

following:

Ÿ A user index created with the immediate update parameter set to 1 (affects

performance)

Ÿ A modify index (MODIDX) MI instruction with the immediate update bit set to 1

Ÿ The set access state (SETACST) MI instruction

and the system abnormally ends, your index is probably damaged.

To determine if your last system power down was normal or abnormal, you can

check the system value QABNORMSW.

You will not get an error message if your index is damaged. The definition of your

index is usable; it is probably the data in your index that is bad.

You can log changes to a database file in a journal, and you can use the journal to

apply or remove those changes later. You can also use the journal to audit who is

using the database file. However, the system does not support the journaling of

indexes. As a result, user applications should log entries in a journal to keep track

of changes to the index, but you cannot update the index using apply and remove

journal entry functions. For more information on journaling, see the Journal and

Commit APIs in the System API Reference book, SC41-5801.

Indexes support the storage of data that does not need to remain after an abnormal

system end. If an abnormal system end does occur, you must use a backup copy

of the index that was previously saved or create a new copy of the index.

2-30 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Performance Considerations

APIs and Internal System Objects

APIs retrieve information from internal system objects. Some of the information

contains special values. For example, the list object API returns the object type as

a special value (*PGM, *LIB, and so on). However, special values may be added

in future releases. Even numeric values may have new special values. When you

code to APIs, you should assume that the format of the information returned will not

change from release to release, but the content of the information might change.

Performance Considerations

The retrieve APIs allow you to control the performance cost for information you

retrieve. The format specified for any API influences the performance cost of the

API. In general, when more information is returned, the performance is slower.

Some list APIs, such as list jobs, list spooled files, and list objects, generate the list

with minimal cost. This is why these formats do not retrieve very much information.

Some of the APIs, such as list record formats and list fields, have only one format,

because there is no additional performance cost to supply the complete information.

The retrieve APIs, such as retrieve member description and retrieve spooled file

attributes, have formats that are generally ordered from fastest performance to

slowest performance. That is, the lower numbered formats run faster but retrieve

less information, and the higher numbered formats run slower but retrieve more

information. One exception is the Retrieve Job Information (QUSRJOBI) API where

the order of the formats does not have anything to do with performance character-

istics. For more information about the performance characteristics for the

QUSRJOBI API formats, see the Retrieve Job Information (QUSRJOBI) API in the

Work Management part of the System API Reference book.

Chapter 2. Getting Started with APIs 2-31

Download from Www.Somanuals.com. All Manuals Search And Download.

Performance Considerations

2-32 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Chapter 3. Common Information across APIs—Basic (OPM)

Example

Through the use of several examples, this chapter provides information about how

to use original program model (OPM) APIs in your programs. The primary example

programs in this chapter are also shown in additional languages in “Original

Program Model (OPM) APIs—Examples” on page B-2.

In the examples, the following are focus items:

Ÿ Description of an API by section

Ÿ Fixed-length formats

Ÿ Variable-length fields as output

Ÿ Optional parameters

The Retrieve Job Description Information (QWDRJOBD) API is used as the founda-

tion for the examples in this chapter. The QWDRJOBD API has been included in

“Retrieve Job Description Information API—Example” on page 3-29 for your use, if

you would like to refer to it as you read this chapter.

For details on the OS/400 APIs, refer to the System API Reference, SC41-5801.

Original Program Model (OPM) API–Scenario

In this chapter, accessing information from a job description is used to demonstrate

how to code APIs. While this may not be what your application requires, you can

use the same approach to access information when you use most of the APIs.

Assume that you are interested in accessing the value of the hold parameter on the

Retrieve Job Description (RTVJOBD) command. The hold parameter determines

whether the job is held on the job queue. Two values are supported:

*NO

The job is not held.

*YES

The job is held on the job queue.

Finding the API Name to Use

A first step in finding the correct API is to identify the part of the OS/400 program

that is most closely related to the function in which you are interested.

If you want to access information from a job description, for example, you have to

know that a job description object is considered part of the work management func-

tion. Next, you would turn to that chapter of the System API Reference.

Within each chapter of the System API Reference, the APIs are listed in alphabet-

ical order by the spelled-out form of the API name. The API names contain verbs

that are similar to the OS/400 licensed program: change, create, remove, and

retrieve. Other verbs, such as list and set, you may not be familiar with. For more

information on verbs, see Figure 2-1 on page 2-2. If you want to access informa-

tion from a job description, the verb retrieve is a good place to start.

Retrieve functions are available for several work management objects, such as data

areas, job descriptions, and job queues. Retrieve functions are also available for

 Copyright IBM Corp. 1997

3-1

Download from Www.Somanuals.com. All Manuals Search And Download.

nonobject information that represents data known to the system, such as job infor-

mation or system status.

Description of an API

Most APIs have similar topic headings. The following lists the API topic headings,

each with an overview and details on how to use the information.

Parameters

The Parameters box describes how to call the API. The first column in the Param-

eters box lists the required order of the parameters. The second column lists each

parameter used on the call.

The third column lists whether the parameter is defined for input, output, or input

and output. Input parameters and fields are not changed by the API. They have

the same value on the return from the API call as they do before the API call. In

contrast, output parameters are changed. Any information that an API caller places

in an output parameter or output field before the call to the API could be lost on the

return from the call to the API.

In the fourth column of the Parameters box is the type of data defined for the

parameter. CHAR(*) represents a data type that is not known, such as character,

binary, and so on, or a length that is not known. Binary(x) represents x bytes of a

binary value. CHAR(x) represents x bytes of character data. When calling the

QWDRJOBD API, for example, there is an 8-byte character format name, a 4-byte

binary value named length of receiver variable, and a variable-length receiver vari-

able. The receiver variable is a structure made up of several character and binary

fields. For more information on format names, see “Format Name” on page 3-4.

RPG Call Statement—Parameter Example: In this example program, you must

pass 5 parameters to use the API. For example, your RPG CALL statement might

look like the following:

CALL 'QWDRJOBD'

PARM

QWDBH

RCVLEN

FORMAT

LFNAM

QUSBN

Receiver Var.

Length QWDBH

Format Name

Qual. Job Desc

Error Code

Note: There is no parameter for the HOLD information. The first parameter,

receiver variable (QWDBH), is where the information is passed back from

the job description API. You will receive a data structure that contains infor-

mation, and you will need to find the specific location within the data struc-

ture for where the HOLD information is stored.

Authorities and Locks

The Authorities and Locks topic lists all the authorities that you need to use the

API. This topic also lists the locks that the API uses. To use an API, you must

have the correct authority to the following:

Ÿ The API itself

Ÿ All the objects that the API uses

Ÿ Any locks that the API places on any objects

3-2 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Locks are based on the objects that the API uses. The type of locking that occurs,

such as whether the object can be used by more than one user at the same time,

is based on what actions the API performs on the object.

For the QWDRJOBD API, you must have *USE authority to both the job description

object and the library to access the object. This is the same type of authority that

is required for most situations where you want to display or retrieve information in

an object. For example, it is the same authority that you would need to use the

Display Job Description (DSPJOBD) command. Because no specific information is

described for locks, you can assume that nothing unusual is required.

Required Parameter Group

The Required Parameter Group topic of an API lists all the parameters required for

that API. You must use all of the parameters in the order that they are listed.

None of the parameters may be left out.

The details of each parameter that must be used on the call to the QWDRJOBD

API are described in “Required Parameter Group” on page 3-30.

Receiver Variable: A receiver variable is the name of the variable (QWDBH in the

example RPG program in “Parameters” on page 3-2) where the information will be

placed. You need to declare the length of the receiver variable based on what you

want from the format. The include file QWDRJOBD contains the definition for the

receiver variable structure depending on the value used for the format name. For

more information on the format, see the table in “JOBD0100 Format” on page 3-30.

You can see from the Dec (decimal offset) column of the JOBD0100 format table

(.1/ on page 3-31) that at least 390 bytes plus additional bytes (of unknown length)

for the initial library list and the request data are returned. “Accessing a Field

Value (Initial Library List)—OPM RPG Example” on page 3-19 describes how to

determine the lengths of these fields. For now, you should focus on the fixed

portion (390 bytes) of the format.

You have a choice of receiving the maximum or enough bytes to contain the infor-

mation in which you are interested. Because the value of the hold on job queue

field starts at decimal 76, you could specify that the receiver variable is 100 bytes

(or any number greater than or equal to 86 bytes). It is not necessary to be precise

when you specify the length of the receiver variable. Whatever you specify is the

amount of data that is returned. You can truncate a value in the middle of a field in

the format, specify more length than the format has, and so on.

For example, assume that you decided to receive the fixed information, a length of

390 (.2/ on page 3-7). If you are going to call the API once, no measurable perfor-

mance gain occurs if you specify anything less than the maximum. When defining

the length of your receiver variable, you would usually use the length of the infor-

mation that you want to receive. The length of receiver variable parameter must be

set to a value equal to or less than the length that you defined the receiver variable

parameter to be.

Length of Receiver Variable: You normally enter the length that you have speci-

fied for the receiver variable. Remember that in this example, you decided to

declare the receiver variable to be 390 bytes in length. The length of receiver vari-

able parameter will have a value of 390 assigned to it (.3/ on page 3-7). You

could have specified a different value, but the value must be the same or less than

Chapter 3. Common Information across APIs—Basic (OPM) Example 3-3

Download from Www.Somanuals.com. All Manuals Search And Download.

the size of the variable in your program. In the example program in “RPG Call

Statement—Parameter Example” on page 3-2, RCVLEN is the length of receiver

variable parameter.

The length field, according to the required parameter group, must be described as

BINARY(4). This means that a field of 4 bytes is passed where the value is speci-

fied in binary. You need to know how your high-level language allows you to define

a 4-byte field and place a binary value in it. The API does not care if the field is

declared as a binary type. For example, some languages, like control language

(CL), do not have a binary type. What is important is that the field is 4 bytes in

length and that it contains the receiver length in binary.

If you write programs in CL, you need the %BIN function to convert a decimal value

or variable to a character field that is declared as 4 bytes. If you write programs in

RPG, you can declare a data structure that contains a 4-byte field of zero decimals

and is defined as B for binary (.4/ on page 3-7). Because the field is a binary

type, RPG would make a binary value.

Format Name: A format name is a name that identifies what type of information

you want returned in the receiver variable. Because this API has a single format

name, JOBD0100, you would use the format name given (.5/ on page 3-7) in the

Retrieve Job Description Information API. The format name variable in the

example program is called FORMAT. You can place the format name in a variable

or pass it as a literal.

Qualified Job Description Name: This name must be passed as a 20-character

name with the job description name in the first 10 characters and the library qual-

ifier beginning in the 11th character. If you want JOBD1 in LIBX, you would

specify:

2ð

JOBD1

LIBX

The special values of *CURLIB or *LIBL can be used as the library qualifier.

Note: APIs generally do not convert parameter values to uppercase. When using

object names (like job description and library), you must provide the name

in uppercase.

Error Code: This parameter allows you to select how errors are to be handled.

The include file QUSEC contains the definition for the error code structure that is

used for the error code parameter.

You can choose to receive exceptions (escape messages) or to receive an error-

code data structure that allows you to determine if an exception occurred.

Depending on your high-level language, you may not have a choice for which

method you use. You may have to use the error-code data structure because

some languages do not provide for escape messages.

In the example in “Retrieving the Hold Parameter (Exception Message)—OPM RPG

Example” on page 3-6, the RPG program requests that exceptions be sent if any

errors occur. To provide for this type of exception handling, a 4-byte binary field

3-4 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

with a value of zero (.6/ on page 3-7) must be passed. This indicates to the API

that you want exception messages sent.

Optional Parameter Group

Some of the APIs have optional parameters; the optional parameters form a group.

You must either include or exclude the entire group. You cannot use one of these

parameters by itself. You must include all preceding parameters.

The API can be called two ways: either with the optional parameters or without the

optional parameters.

The Retrieve Job Description Information API has no optional parameter groups.

The List Job (QUSLJOB) API is an example of an API with an optional parameter

group.

Format

The Format topic describes a format name, which for the Retrieve Job Description

(QWDRJOBD) API is JOBD0100. Listed within the format are the individual fields

that contain the attributes of the job description. The offset in the Dec (decimal

offset) column for the hold on job queue field (hold parameter on the Retrieve Job

Description command) begins at decimal offset 76. For more information on this

format, see “JOBD0100 Format” on page 3-30.

The fields in the format do not occur in any particular sequence. You have to scan

the format to determine what you want.

This API has only a single format; other APIs may have multiple formats where

each format has different levels of information. With multiple formats, a format

name parameter allows you to specify which format you want to retrieve.

Field Descriptions

The Field Descriptions topic describes the fields found in the format. The contents

of the format are presented in alphabetical sequence and not in the sequence of

the fields defined in the format. In the Retrieve Job Description Information API

example, you can find the description of the hold on job queue field. The field does

not use the parameter name found on the Create Job Description (CRTJOBD)

command.

Error Messages

The Error Messages topic lists error messages that can occur when you use the

API. These are message IDs that normally exist in the QCPFMSG file. You may

want to program for these messages regardless of the high-level language that you

are using. If you need more detail about the messages, use the Display Message

Description (DSPMSGD) command.

Extracting a Field from the Format

The format describes where the field that you want is located within the receiver

variable. An offset is shown in both decimal and hexadecimal. Depending on

which language you use, either offset may be helpful. For CL and RPG, you would

normally use the decimal offset. With any offset, it is important to remember

whether your language works with an offset from a base of 0 or a base of 1. The

format tables in the System API Reference are prepared for languages that work

Chapter 3. Common Information across APIs—Basic (OPM) Example 3-5

Download from Www.Somanuals.com. All Manuals Search And Download.

from a base of 0, but not all languages can use this base. CL and RPG, for

example, work from a base of 1, so you need to add 1 to the decimal value of each

offset. The hold on job queue field begins at decimal offset 76, for example. To

access the information in CL or RPG, you need to address byte 77 within the

receiver variable.

Using the format, you can tell that the field after the hold on job queue field, output

queue name, begins in offset 86. This means that the hold on job queue informa-

tion is in the following location from a CL or RPG perspective:

XXXXXXXXXX

The only possible values for the hold on job queue field are *YES and *NO. They

are left-justified in the field and the remaining positions are blank.

Most of the formats provide additional bytes for each field to allow for expansion,

such as a new value for the hold on job queue field that would be more than 4

bytes.

Many of the needed structures are provided by the system-include library,

QSYSINC. However, any fields of a structure that are variable in length are not

defined by QSYSINC. These variable-length fields must be defined by the user, as

shown by .7/ on page 3-20. For more information on the QSYSINC library, see

“APIs and the QSYSINC Library” on page 2-28.

Retrieving the Hold Parameter (Exception Message)—OPM RPG

Example

In the following program example, all the pieces have been put together with an

RPG program that accesses the hold on job queue information from a job

description. A message is sent for the value found. To make the RPG program

more general purpose, two parameters for the job description (JOBD) name and

library (JOBDL) name are passed to it .8/ (refer to page 3-7). The program

example, which is named JOBDAPI (this program name is also used in other exam-

ples in this chapter), does not handle errors. Any errors that are received are

returned as exception messages.

Iᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Iᑍ

IᑍProgram Name: JOBDAPI

Iᑍ

IᑍLanguage: OPM RPG

Iᑍ

IᑍDescriptive Name: Job Description

Iᑍ

IᑍDescription: This example expects errors to be sent as escape

Iᑍ

messages.

IᑍHeader Files Included: QUSEC - Error Code Parameter

Iᑍ

QWDRJOBD - Retrieve Job Description API

Iᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Iᑍ

Iᑍ Error Code Parameter Include for the APIs

Iᑍ

I/COPY QSYSINC/QRPGSRC,QUSEC

3-6 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Iᑍ

Iᑍ Retrieve Job Description API Include

Iᑍ

I/COPY QSYSINC/QRPGSRC,QWDRJOBD.2/

Iᑍ

Iᑍ Command String Data Structure

Iᑍ

ICMDSTR

I I

Iᑍ

'SNDMSG MSG(''HOLD -

'value is '

1 26 CMD1

27 36 HOLD

37 51 CMD2

''') TOUSR(QPGMR)'

Iᑍ Miscellaneous Data Structure

Iᑍ

I I

Iᑍ

Cᑍ

.3/

39ð

.4/

4ðRCVLEN

'JOBDð1ðð'

5 12 FORMAT

.5/

Cᑍ Beginning of Mainline

Cᑍ

Cᑍ Two parameters are being passed into this program.

Cᑍ

ᑍENTRY

PLIST .8/

PARM

JOBD

1ð

Cᑍ

JOBDL 1ð

Cᑍ Move the two parameters passed into LFNAM.

Cᑍ

JOBD

CAT JOBDL

LFNAM 2ð .9/

Cᑍ Error code bytes provided is set to ð

Cᑍ

Z-ADDð

QUSBNB .6/

Cᑍ

Cᑍ Instead of specifying 'QWCRJOBD', I could have used the

Cᑍ constant QWDBGB that was defined in the QWDRJOBD include.

Cᑍ

CALL 'QWDRJOBD'

PARM

QWDBH

RCVLEN

FORMAT

LFNAM

QUSBN

Receiver Var.

Length RCVVAR

Format Name

Qual. Job Desc

Error Code

Cᑍ

MOVELQWDBHN

HOLD

Cᑍ Let's tell everyone what the hold value was for this jobd.

Cᑍ

Z-ADD51

CALL 'QCMDEXC'

PARM

LENSTR 155

Cᑍ

CMDSTR

LENSTR

PARM

SETON

RETRN

Cᑍ End of MAINLINE

Cᑍ

The program declares the variables to be used. The QWDBH variable is length

390 as shown by .3/ on page 3-7.

In the example, the program places a value of JOBD0100 in the format variable. A

literal could have been used instead for those languages that support a literal on a

call .5/. (For program examples in other languages, see “Original Program Model

(OPM) APIs—Examples” on page B-2.) The program generates the qualified name

of the job description (JOBD) by concatenating the simple name and the library

Chapter 3. Common Information across APIs—Basic (OPM) Example 3-7

Download from Www.Somanuals.com. All Manuals Search And Download.

qualifier .9/. A 20-character variable must be used, and the simple name must

begin in byte 1 with the library qualifier in byte 11. Because CAT is used, a simple

concatenation of two 10-byte variables occurs so that the names are in the correct

place for the LFNAM parameter.

The QWDRJOBD API is called with the correct parameter list. The API uses the

parameter list and accesses the job description specified. The API extracts the

values from the internal object form and places them in a data structure that

matches the JOBD0100 format. The API then returns with the data structure

placed in variable QWDBH, which is located in member QWDRJOBD in the

QSYSINC library.

The output is similar to the following:

Display Messages

System:

GENSYS9ð

ᑍDSPMSG

Queue . . . . . :

Library . . . :

Severity . . . :

QPGMR

QUSRSYS

Program . . . . :

Library . . . :

Delivery . . . :

ðð

ᑍHOLD

Type reply (if required), press Enter.

From . . . :

HOLD value is ᑍNO

SMITH

ð7/23/94

1ð:25:14

The API does not need to be called each time that you want a separate field

because all fields are returned that would fit within the size indicated by the length

of receiver variable (RCVLEN) parameter. You can run the program against the

QBATCH job description in library QGPL by using the following call statement:

CALL JOBDAPI PARM(QBATCH QGPL)

If QGPL is on the library list, you can run the program against the QBATCH job

description by using the following call statement:

CALL JOBDAPI PARM(QBATCH ᑍLIBL)

You can run the program on one of your own job descriptions or on a test job

description where you have specified HOLD(*YES).

Handling Error Conditions—OPM RPG Example

For this example, assume that the XYZ job description does not exist:

CALL JOBDAPI PARM(XYZ ᑍLIBL)

You probably will receive the inquiry message CPA0701 that states an unmonitored

exception (CPF9801) has occurred and offers several possible replies. At this point,

you would enter C for Cancel and press the Enter key.

If you displayed the low-level messages, you would see the following: CPF9801

(Object not found), followed by the inquiry message (CPA0701), followed by your

reply.

When you specify the error code parameter as zero, you are specifying that

exceptions be sent as escape messages. You can code the RPG program so that

any errors on the call set the indicator 01 to on (.1ð/ on page 3-10). This causes a

different path to be taken in the code.

3-8 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

For RPG, the CALL operation specifies the error indicator. Based on whether the

error indicator is on or off, a set of instructions can be processed. The API must

receive an error code parameter that consists of a binary 4 field with a value of

binary zeros (.11/ on page 3-10). The message ID can be accessed from the

program-status data structure. You would define this as follows:

Iᑍ Program status DS (.12/ on page 3-9)

IPGMSTS

SDS

4ð 46 MSGIDD

If you are going to do something about an error condition, you must test for an

error condition in RPG:

Ÿ If you use the error-code data structure, test the bytes available field (.13/ on

page 3-14).

Ÿ If you let exceptions occur, test the error indicator on the CALL operation (.1ð/

on page 3-10).

Because you must test for some condition (one of the error messages in “Error

Messages” on page 3-36), no great difference exists in how you handle error con-

ditions in RPG. The error-code data structure is a little more straightforward (the

program-status data structure is not used). The only disadvantage of the error-

code data structure is that the escape message that occurred was removed from

the job log.

The following program shows how to code for an error condition, test for that condi-

tion, and send a message to the QPGMR message queue if the condition occurs:

Iᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Iᑍ

IᑍProgram Name: JOBDAPI

Iᑍ

IᑍLanguage: OPM RPG

Iᑍ

IᑍDescriptive Name: Get Job Description

Iᑍ

IᑍDescription: This program handles any errors that are

Iᑍ

returned

IᑍHeader Files Included: QUSEC - Error Code Parameter

Iᑍ

QWDRJOBD - Retrieve Job Description API

Iᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Iᑍ

Iᑍ Error Code Parameter Include for the APIs

Iᑍ

I/COPY QSYSINC/QRPGSRC,QUSEC

Iᑍ

Iᑍ Retrieve Job Description API Include

Iᑍ

I/COPY QSYSINC/QRPGSRC,QWDRJOBD

Iᑍ Program status DS

IPGMSTS

SDS .12/

4ð 46 MSGIDD

1 26 CMD1

Iᑍ

Iᑍ Command String Data Structure

Iᑍ

ICMDSTR

I I

'SNDMSG MSG(''HOLD -

'value is '

I I

Iᑍ

27 36 HOLD

37 51 CMD2

''') TOUSR(QPGMR)'

IMSG3

Chapter 3. Common Information across APIs—Basic (OPM) Example 3-9

Download from Www.Somanuals.com. All Manuals Search And Download.

I I

Iᑍ

'SNDMSG MSG(''No such-

' ᑍJOBD exists'') '

'TOUSR(QPGMR)'

1 35 MSG3A

36 47 MSG3B

Iᑍ Miscellaneous Data Structure

Iᑍ

I I

Cᑍ

39ð

'JOBDð1ðð'

4ðRCVLEN

5 12 FORMAT

Cᑍ Beginning of Mainline

Cᑍ

Cᑍ Two parameters are being passed into this program.

Cᑍ

ᑍENTRY

PLIST

PARM

JOBD

1ð

Cᑍ

JOBDL 1ð

Cᑍ Move the two parameters passed into LFNAM.

Cᑍ

JOBD

CAT JOBDL

LFNAM 2ð

Cᑍ Error code bytes provided is set to ð

Cᑍ

Z-ADDð

QUSBNB .11/

Cᑍ

Cᑍ Instead of specifying 'QWCRJOBD', I could have used the

Cᑍ constant QWDBGB that was defined in the QWDRJOBD include.

Cᑍ

CALL 'QWDRJOBD'

PARM

ð1 .1ð/

Receiver Var.

QWDBH

RCVLEN

FORMAT

LFNAM

QUSBN

PARM

Length RCVVAR

Format Name

Qual. Job Desc

Error Code

Error Subroutine

PARM

ð1

EXSR ERROR

Cᑍ

C Nð1

Cᑍ

MOVELQWDBHN

HOLD

Cᑍ Let's tell everyone what the hold value was for this job.

Cᑍ

C Nð1

Z-ADD51

CALL 'QCMDEXC'

PARM

LENSTR 155

C Nð1

Cᑍ

CMDSTR

LENSTR

PARM

SETON

RETRN

Cᑍ End of MAINLINE

Cᑍ

Cᑍ Subroutine to handle errors received on the CALL

Cᑍ

ERROR

MSGIDD

BEGSR

IFEQ 'CPF98ð1'

Cᑍ

Cᑍ Process errors returned from the API.

Cᑍ

Z-ADD47

CALL 'QCMDEXC'

PARM

LENSTR 155

MSG3

LENSTR

PARM

END

ENDSR

If the CPF9801 exception occurs, your program sends a message to the QPGMR

message queue as shown in the following display:

3-10 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Display Messages

System:

GENSYS9ð

ᑍDSPMSG

Queue . . . . . :

Library . . . :

Severity . . . :

QPGMR

QUSRSYS

Program . . . . :

Library . . . :

Delivery . . . :

ðð

ᑍHOLD

Type reply (if required), press Enter.

From . . . :

No such ᑍJOBD exists

SMITH

ð7/25/94

11:1ð:12

If another exception occurs (for example, a library name that is not valid), you do

not receive an indication that an error occurred because of the way the error sub-

routine is currently coded.

In addition, you can use the Message Handling APIs to receive the messages sent

to your program message queue.

The call to the API fails if you specify a valid job description but use a library qual-

ifier such as *ALLUSR. The value *ALLUSR is not supported by the description of

the required parameter group.

Retrieving the Hold Parameter (Error Code Structure)—OPM RPG

Example

In the program example in “Retrieving the Hold Parameter (Exception

Message)—OPM RPG Example,” QUSBNB (.6/ on page 3-7) was set to a value of

binary zero to tell the API to send exceptions (escape messages) for any error con-

ditions. The example in this topic uses an error-code data structure as an alterna-

tive to receiving exceptions.

Some languages do not support the use of exceptions, so you may prefer to code

for errors using error code structures.

In your programs, you can use error code structures in the following ways:

Ÿ Define an 8-byte error code structure that provides feedback on whether an

error occurred. If an error does occur, you are not able to determine the spe-

cifics of the problem.

Ÿ Define a 16-byte error code structure that allows you to determine if an error

exists and to access the exception message ID. The exception message IDs

are the same as shown in “Error Messages” on page 3-36.

Ÿ Define a larger than 16-byte error code structure that provides the same infor-

mation as described in the previous two error code structures as well as some

or all of the exception data. The exception data is the message data that is

sent with the exception message. Because the vast majority of exception mes-

sages do not have more than 512 bytes of message data, a 600-byte error

code structure would be adequate for almost all cases.

Note: Lengths of 1 through 7 bytes are not valid for the error code structure.

Chapter 3. Common Information across APIs—Basic (OPM) Example 3-11

Download from Www.Somanuals.com. All Manuals Search And Download.

Format of an Error Code Structure

The format of the error code structure (QUSBN) is:

Offset

Dec

Hex

Use

Type

Field

INPUT

BINARY(4) Bytes provided

OUTPUT BINARY(4) Bytes available

OUTPUT CHAR(7)

OUTPUT CHAR(1)

OUTPUT CHAR(*)

Exception ID

Reserved

Exception data

The error code structure can be found in the QSYSINC library in the member

QUSEC (see .14/ on page 3-12). Which of the files you use depends on the lan-

guage. For more information on the QSYSINC library, see “APIs and the

QSYSINC Library” on page 2-28.

The bytes provided field describes the size of the error code structure that you

declared in your program and how you want errors returned. (This was set to 0 as

shown by .6/ on page 3-7 in the JOBDAPI example on page 3-6.)

The bytes available field describes how many bytes the API could have passed

back. If this field is zero, no exception occurred. The correct method for testing if

an error occurred when using a nonzero-bytes-provided value is to check this field

for a value greater than zero (.13/ on page 3-14).

The exception ID is the normal 7-character message ID, such as CPF9801, that

occurs for an object-not-found condition. Do not test this field to determine if an

error exists. The field is properly set by the system only if the number of bytes

available is greater than 0. Similarly, the exception data (message data) informa-

tion is not set properly unless an error exists; for example, any information left from

a prior call is not changed.

The following program is the same as the previous program except that a 16-byte

error code structure is used:

Iᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Iᑍ

IᑍProgram Name: JOBDAPI

Iᑍ

IᑍLanguage: OPM RPG

Iᑍ

IᑍDescriptive Name: Get Job Description

Iᑍ

IᑍDescription: This sample program shows exceptions being

Iᑍ

returned in the error code parameter.

IᑍHeader Files Included: QUSEC - Error Code Parameter

Iᑍ

QWDRJOBD - Retrieve Job Description API

Iᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Iᑍ

Iᑍ Error Code Parameter Include for the APIs

Iᑍ

I/COPY QSYSINC/QRPGSRC,QUSEC .14/

Iᑍ

Iᑍ Retrieve Job Description API Include

3-12 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Iᑍ

I/COPY QSYSINC/QRPGSRC,QWDRJOBD

Iᑍ

Iᑍ Command String Data Structure

Iᑍ

ICMDSTR

I I

Iᑍ

IMSG2

I I

Iᑍ

'SNDMSG MSG(''HOLD -

'value is '

1 26 CMD1

27 36 HOLD

37 51 CMD2

''') TOUSR(QPGMR)'

'SNDMSG MSG(''Progr-

'am failed with mes-

'sage ID '

1 43 MSG2A

44 5ð MSGIDD

51 65 MSG2B

''') TOUSR(QPGMR)'

Iᑍ Miscellaneous Data Structure

Iᑍ

I I

Cᑍ

39ð

'JOBDð1ðð'

4ðRCVLEN

5 12 FORMAT

Cᑍ Beginning of Mainline

Cᑍ

Cᑍ Two parameters are being passed into this program.

Cᑍ

ᑍENTRY

PLIST

PARM

JOBD

1ð

Cᑍ

JOBDL 1ð

Cᑍ Move the two parameters passed into the LFNAM.

Cᑍ

JOBD

CAT JOBDL

LFNAM 2ð

Cᑍ Error code parameter is set to 16

Cᑍ

Z-ADD16

QUSBNB .15/

Cᑍ

Cᑍ Instead of specifying 'QWCRJOBD', I could have used the

Cᑍ constant QWDBGB that was defined in the QWDRJOBD include.

Cᑍ

CALL 'QWDRJOBD'

PARM

QWDBH

RCVLEN

FORMAT

LFNAM

QUSBN

Receiver Var.

Length RCVVAR

Format Name

Qual. Job Desc

Error Code

Cᑍ See if any errors were returned in the error code parameter.

EXSR ERRCOD

Cᑍ

C Nð1

Cᑍ

MOVELQWDBHN

HOLD

Cᑍ Let's tell everyone what the hold value was for this job.

Cᑍ

C Nð1

Z-ADD51

CALL 'QCMDEXC'

PARM

LENSTR 155

C Nð1

Cᑍ

CMDSTR

LENSTR

PARM

SETON

RETRN

Cᑍ End of MAINLINE

Cᑍ

Cᑍ Subroutine to handle errors returned in the error code

Cᑍ parameter.

Cᑍ

Chapter 3. Common Information across APIs—Basic (OPM) Example 3-13

Download from Www.Somanuals.com. All Manuals Search And Download.

ERRCOD

QUSBNC

BEGSR

IFGT ð .13/

Cᑍ

Cᑍ Process errors returned from the API.

Cᑍ

SETON

ð1

Z-ADD65

MOVELQUSBND

CALL 'QCMDEXC'

PARM

LENSTR 155

MSGIDD

MSG2

LENSTR

PARM

END

ENDSR

The QUSBN error-code data structure is defined in the include file QUSEC (.14/ on

page 3-12), and the program initializes the bytes provided field (QUSBNB) with a

value of 16 (.15/ on page 3-13). This sets the first field of the error code structure

to tell the API not to send an exception but to use the first 16 bytes of the QUSBN

parameter to return the error information. After the CALL to the API, the program

accesses the bytes available (QUSBNC) (.13/ on page 3-14). This contains the

number of bytes of information about the error condition. The program is coded so

that it tests if the number exceeds zero. This is the correct method of determining

whether an error has occurred.

If an error occurred, you may want to handle the error in many different methods.

The program shown extracts the specific error message ID that occurred and sends

the 7-character value as a message. The QUSBN parameter is used for both input

and output (see “Format of an Error Code Structure” on page 3-12). The first 4

bytes are input to the API to tell it how to handle exceptions. The remaining bytes

are output from the API about any exception conditions.

To see the value of the HOLD attribute, use the following call statement to run the

program against the QBATCH job description in library QGPL:

CALL JOBDAPI (QBATCH QGPL)

You should see that the value of the HOLD attribute is *NO:

Display Messages

System:

GENSYS9ð

ᑍDSPMSG

Queue . . . . . :

Library . . . :

Severity . . . :

QPGMR

QUSRSYS

Program . . . . :

Library . . . :

Delivery . . . :

ðð

ᑍHOLD

Type reply (if required), press Enter.

From . . . :

HOLD value is ᑍNO

SMITH

ð7/23/94

1ð:25:14

Handling Error Conditions—OPM RPG Example

For this error condition, you should assume that the XYZ job description does not

exist. Use the following call statement to run the error condition:

CALL JOBDAPI (XYZ ᑍLIBL)

You should see that the CPF9801 message (Object not found) was issued:

3-14 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Display Messages

System:

GENSYS9ð

ᑍDSPMSG

Queue . . . . . :

Library . . . :

Severity . . . :

QPGMR

QUSRSYS

Program . . . . :

Library . . . :

Delivery . . . :

ðð

ᑍHOLD

Type reply (if required), press Enter.

From . . . :

Program failed with message ID CPF98ð1

SMITH

ð7/23/94

1ð:56:13

Then run another error condition. For this error condition, you should assume that

the XYZ library does not exist. Use the following call statement:

CALL JOBDAPI (QPGMR XYZ)

The output is similar to the following:

Display Messages

System:

GENSYS9ð

ᑍDSPMSG

Queue . . . . . :

Library . . . :

Severity . . . :

QPGMR

QUSRSYS

Program . . . . :

Library . . . :

Delivery . . . :

ðð

ᑍHOLD

Type reply (if required), press Enter.

From . . . :

Program failed with message ID CPF981ð

SMITH

ð7/23/94

1ð:56:13

You should see that the CPF9810 message (Library not found) was issued. An

advantage of the error return variable is that it can contain other information such

as message data. The following are the changes needed to return a 200-byte error

code structure:

Iᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Iᑍ

IᑍProgram Name: JOBDAPI

Iᑍ

IᑍLanguage: OPM RPG

Iᑍ

IᑍDescriptive Name: Get Job Description

Iᑍ

IᑍDescription: This sample program shows the incorrect

Iᑍ

way of using the offset in a user space in RPG.

IᑍHeader Files Included: QUSEC - Error Code Parameter

Iᑍ

(Copied into Program)

QWDRJOBD - Retrieve Job Description API

Iᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Iᑍ Error Code Parameter Include for the APIs

Iᑍ

Iᑍ The following QUSEC include is copied into this program

Iᑍ so that the variable-length field can be defined as

Iᑍ fixed length.

Iᑍ

Iᑍᑍᑍ START HEADER FILE SPECIFICATIONS ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Iᑍ

IᑍHeader File Name: H/QUSEC

Iᑍ

IᑍDescriptive Name: Error Code Parameter.

Iᑍ

Iᑍ5763-SS1 (C) Copyright IBM Corp. 1994,1994

IᑍUS Government Users Restricted Rights -

IᑍUse, duplication or disclosure restricted

Iᑍby GSA ADP Schedule Contract with IBM Corp.

Chapter 3. Common Information across APIs—Basic (OPM) Example 3-15

Download from Www.Somanuals.com. All Manuals Search And Download.

Iᑍ

IᑍLicensed Materials-Property of IBM

Iᑍ

IᑍDescription: Include header file for the error code parameter.

Iᑍ

IᑍHeader Files Included: None.

Iᑍ

IᑍMacros List: None.

Iᑍ

IᑍStructure List: Qus_EC_t

Iᑍ

IᑍFunction Prototype List: None.

Iᑍ

IᑍChange Activity:

Iᑍ

IᑍCFD List:

Iᑍ

IᑍFLAG REASON

LEVEL DATE

PGMR

CHANGE DESCRIPTION

Iᑍ---- ------------ ----- ------ --------- ----------------------

Iᑍ$Að= D2862ððð

Iᑍ

3D1ð 9312ð1 DPOHLSON: New Include

IᑍEnd CFD List.

Iᑍ

IᑍAdditional notes about the Change Activity

IᑍEnd Change Activity.

Iᑍᑍᑍ END HEADER FILE SPECIFICATIONS ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Iᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

IᑍRecord structure for Error Code Parameter

Iᑍᑍᑍᑍ

ᑍᑍᑍ

IᑍNOTE: The following type definition defines only the fixed

Iᑍ

portion of the format. Varying-length field exception

data is not defined here.

Iᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

IQUSBN

Iᑍ

Qus EC

4ðQUSBNB

Bytes Provided

8ðQUSBNC

Bytes Available

9 15 QUSBND

Exception Id

16 16 QUSBNF

Reserved

17 17 QUSBNG

Varying length

17 2ðð QUSBNG .16/

Z-ADD2ðð

QUSBNB

Cᑍ

CALL 'QWDRJOBD'

PARM

QWDBH

RCVLEN

FORMAT

LFNAM

QUSBN

Receiver Var.

Length RCVVAR

Format Name

Qual. Job Desc

Error Code

The value placed in the QUSBNG variable .16/ is the message data associated

with the message ID that is identified as the exception. The message data follows

the same format as if you had entered a Receive Message (RCVMSG) command

and requested the message data (MSGDTA) parameter. You can use the Display

Message Description (DSPMSGD) command to determine the layout of the

message data for a particular message ID. When you handle exceptions, the only

information provided is the exception ID and the message data associated with the

3-16 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

exception. You cannot receive a diagnostic message (if one were sent in addition

to the escape message) in the error-code data structure. You can use the message

handling APIs to receive messages from your program message queue and to

access the other messages that may be issued from the API. Appendix A of the

System API Reference book contains an example of a diagnostic report program

that uses the message handling APIs.

When you instruct the API to return all errors in the error-code data structure, the

escape message does not appear in the job log. The escape message not

appearing in the job log is one of the major differences between letting the API

return errors in an error-code data structure and letting the API send escape mes-

sages. For the error-code data structure, the escape messages have been

removed from the job log by the API. If a diagnostic message is sent first, the

diagnostic message exists in the job log and can be received.

Accessing the HOLD Attribute—OPM RPG Example

The following is the RPG code used to access the HOLD attribute. This is the

same type of program as the RPG program examples in “Retrieving the Hold

Parameter (Exception Message)—OPM RPG Example” on page 3-6 and

“Retrieving the Hold Parameter (Error Code Structure)—OPM RPG Example” on

page 3-11. The program, named JOBDAPI, prints the value of HOLD if it is found

(.17/ on page 3-19). If an error occurs, the program prints a line that contains the

error message ID to a spooled file called QPRINT (.18/ on page 3-19).

Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Fᑍ

FᑍProgram Name: JOBDAPI

Fᑍ

FᑍLanguage: OPM RPG

Fᑍ

FᑍDescriptive Name: Get Job Description

Fᑍ

FᑍDescription: The following program prints out the name of

Fᑍ

the job description or prints an error if the

API could not find the job description name

specified.

FᑍHeader Files Included: QUSEC - Error Code Parameter

Fᑍ

QWDRJOBD - Retrieve Job Description API

Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Fᑍ JOBDAPIR - Print value of HOLD parameter using API

Fᑍ

Uses error-code data structure

FQPRINT O

Iᑍ

132

PRINTER

Iᑍ Error Code Parameter Include for the APIs

Iᑍ

I/COPY QSYSINC/QRPGSRC,QUSEC

Iᑍ

Iᑍ Retrieve Job Description API Include

Iᑍ

I/COPY QSYSINC/QRPGSRC,QWDRJOBD

Iᑍ

Iᑍ Dummy data structure used to declare binary field .19/

Iᑍ

I I

39ð

'JOBDð1ðð'

4ðRCVLEN

12FORMAT

Chapter 3. Common Information across APIs—Basic (OPM) Example 3-17

Download from Www.Somanuals.com. All Manuals Search And Download.

Cᑍ

Cᑍ Beginning of Mainline

Cᑍ

Cᑍ Two parameters are being passed into this program.

Cᑍ

ᑍENTRY

PLIST

PARM

Parm list

Job descrp

Jobd library

JOBD

1ð

JOBDL 1ð

Cᑍ

Cᑍ Move the two parameters passed into LFNAM.

Cᑍ

JOBD

CAT JOBDL

LFNAM 2ð

Qlfd name

Cᑍ

Cᑍ Error code parameter is set to 16.

Cᑍ

Z-ADD16

QUSBNB

Bytes provid

Cᑍ

Cᑍ Instead of specifying 'QWCRJOBD', I could have used the

Cᑍ constant QWDBGB that was defined in the QWDRJOBD include.

Cᑍ Call the API

Cᑍ

CALL 'QWDRJOBD'

Parm list

PARM

QWDBH

RCVLEN

FORMAT

LFNAM

QUSBN

Receiver Var.

Length RCVVAR

Format Name

Qual. Job Desc

Error Code

Cᑍ If no bytes available, API was successful; print HOLD value

QUSBNC

IFEQ ð

EXCPTGOOD

ENDIF

Cᑍ If some bytes available, API failed; print error message ID

QUSBNC

IFGT ð

EXCPTBAD

ENDIF

Cᑍ End of program

Cᑍ

SETON

RETRN

Cᑍ End of MAINLINE

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Oᑍ

OQPRINT E 1ð6

GOOD

'HOLD value - '

QWDBHN

BAD

OQPRINT E 1ð6

'Failed. Error ID - '

QUSBND

The following data structures are used:

Error-code data structure

This defines the two binary fields used and the message ID that is returned for

error conditions.

Retrieve job description data structure

This defines format JOBD0100, a 390-byte data structure with the hold field in

positions 77-86.

Dummy data structure

This contains a field used for the length of the receiver variable. The field is

defined as binary and is in the first 4 bytes. The dummy data structure (.19/

on page 3-17) also contains the format field.

This data structure is used because RPG only allows binary variables to be

defined in the context of a data structure.

The program retrieves the parameter list that is passed and initializes the fields to

be passed to the API. The API is called and places information into the receiver-

3-18 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

variable data structure if information is found. The API places the information in the

error-code data structure if an error occurred and if enough space was provided to

receive the information.

The program prints one of two different lines depending on whether any errors were

found:

HOLD value - ᑍNO .17/

Failed. Error ID - CPF98ð1 .18/

Accessing a Field Value (Initial Library List)—OPM RPG Example

In this topic, the JOBDAPI program accesses a variable-length array. The variable-

length array is the initial library list for the job description.

The discussion of the initial library list field in the job description format, “JOBD0100

Format” on page 3-30, indicates that the initial library list field is 11 bytes per entry,

where each entry is a library name followed by a blank. Because the maximum

number of libraries allowed on an initial library list is 25, this field is up to and

including 275 bytes in length. Depending on how many libraries are named for the

initial library list, the actual amount of space used varies (by multiples of 11).

The format does not have an entry in the Offset columns for initial library list. It may

begin in offset 390, but you should not rely on this. For example, if a new field is

added to the job description format, it will probably be placed at offset 390, and the

initial library list information will be shifted.

To access the initial library list field, use the following two fields found in the format:

Ÿ Offset to the initial library list field (.19/ on page 3-22 and on page 3-31).

Ÿ Number of libraries in the initial library list field (.2ð/ on page 3-22 and on page

3-31).

If you use these field values in the format instead of hard coding an offset and a

number of libraries, your program can work on any future release of an AS/400

business computing system, even if more job description attributes are defined in

the format. This is an important upward compatibility approach that you will want to

use whenever you code for a list of entries.

The following RPG code sends a message for each library found in the initial library

list field. Exceptions are handled by the RPG program. Although a library name

cannot exceed 10 bytes, each entry is 11 bytes long.

Iᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Iᑍ

IᑍProgram Name: JOBDAPI

Iᑍ

IᑍLanguage: OPM RPG

Iᑍ

IᑍDescriptive Name: Get Job Description

Iᑍ

IᑍDescription: This sample program shows the correct

Iᑍ

way of using the offset in a user space in RPG.

IᑍHeader Files Included: QUSEC - Error Code Parameter

Iᑍ

(Copied into Program)

QWDRJOBD - Retrieve Job Description API

(Copied into Program)

Iᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Chapter 3. Common Information across APIs—Basic (OPM) Example 3-19

Download from Www.Somanuals.com. All Manuals Search And Download.

Iᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Iᑍ

Iᑍ Error Code Parameter Include for the APIs

Iᑍ

Iᑍ The following QUSEC include is copied into this program

Iᑍ so that the variable-length field can be defined as

Iᑍ fixed length.

Iᑍ

Iᑍᑍᑍ START HEADER FILE SPECIFICATIONS ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Iᑍ

IᑍHeader File Name: H/QUSEC

Iᑍ

IᑍDescriptive Name: Error Code Parameter.

Iᑍ

Iᑍ5763-SS1 (C) Copyright IBM Corp. 1994,1994

IᑍUS Government Users Restricted Rights -

IᑍUse, duplication or disclosure restricted

Iᑍby GSA ADP Schedule Contract with IBM Corp.

Iᑍ

IᑍLicensed Materials-Property of IBM

Iᑍ

IᑍDescription: Include header file for the error code parameter.

Iᑍ

IᑍHeader Files Included: None.

Iᑍ

IᑍMacros List: None.

Iᑍ

IᑍStructure List: Qus_EC_t

Iᑍ

IᑍFunction Prototype List: None.

Iᑍ

IᑍChange Activity:

Iᑍ

IᑍCFD List:

Iᑍ

IᑍFLAG REASON

LEVEL DATE

PGMR

CHANGE DESCRIPTION

Iᑍ---- ------------ ----- ------ --------- ----------------------

Iᑍ$Að= D2862ððð

Iᑍ

3D1ð 9312ð1 DPOHLSON: New Include

IᑍEnd CFD List.

Iᑍ

IᑍAdditional notes about the Change Activity

IᑍEnd Change Activity.

Iᑍᑍᑍ END HEADER FILE SPECIFICATIONS ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Iᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

IᑍRecord structure for Error Code Parameter

Iᑍᑍᑍᑍ

ᑍᑍᑍ

IᑍNOTE: The following type definition defines only the fixed

Iᑍ

portion of the format. Varying-length field exception

data is not defined here.

Iᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

IQUSBN

Iᑍ

Qus EC

4ðQUSBNB

Bytes Provided

8ðQUSBNC

Bytes Available

9 15 QUSBND

Exception Id

16 16 QUSBNF

Reserved

Iᑍ

Varying length, had to define len

17 1ðð QUSBNG .7/

Iᑍ

Iᑍ Retrieve Job Description API Include

Iᑍ

Iᑍ The following QWDRJOBD include is copied into this program

Iᑍ so that the variable-length field can be defined as fixed

Iᑍ length.

3-20 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Iᑍ

Iᑍᑍᑍ START HEADER FILE SPECIFICATIONS ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Iᑍ

IᑍHeader File Name: H/QWDRJOBD

Iᑍ

IᑍDescriptive Name: Retrieve Job Description Information API

Iᑍ

Iᑍ5763-SS1 (C) Copyright IBM Corp. 1994,1994

IᑍUS Government Users Restricted Rights -

IᑍUse, duplication or disclosure restricted

Iᑍby GSA ADP Schedule Contract with IBM Corp.

Iᑍ

IᑍLicensed Materials-Property of IBM

Iᑍ

IᑍDescription: The Retrieve Job Description Information API

Iᑍ

retrieves information from a job description

object and places it into a single variable in the

calling program.

IᑍHeader Files Included: None.

Iᑍ

IᑍMacros List: None.

Iᑍ

IᑍStructure List: Qwd_JOBDð1ðð_t

Iᑍ

IᑍFunction Prototype List: QWDRJOBD

Iᑍ

IᑍChange Activity:

Iᑍ

IᑍCFD List:

Iᑍ

IᑍFLAG REASON

LEVEL DATE

PGMR

CHANGE DESCRIPTION

Iᑍ---- ------------ ----- ------ --------- ----------------------

Iᑍ$Að= D2862ððð

Iᑍ

3D1ð 94ð424 ROCH:

New Include

IᑍEnd CFD List.

Iᑍ

IᑍAdditional notes about the Change Activity

IᑍEnd Change Activity.

Iᑍᑍᑍ END HEADER FILE SPECIFICATIONS ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Iᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

IᑍPrototype for QWDRJOBD API

Iᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

'QWDRJOBD'

QWDBGB

Iᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

IᑍType Definition for the JOBDð1ðð format.

Iᑍᑍᑍᑍ

ᑍᑍᑍ

IᑍNOTE: The following type definition defines only the fixed

Iᑍ

portion of the format. Any varying-length fields have

to be defined by the user.

Iᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

IQWDBH

Iᑍ

1ððð

Qwd JOBDð1ðð

4ðQWDBHB

Bytes Returned

8ðQWDBHC

Bytes Available

9 18 QWDBHD

Job Description Name

19 28 QWDBHF

Job Description Lib Name

29 38 QWDBHG

User Name

39 46 QWDBHH

Job Date

47 54 QWDBHJ

Job Switches

55 64 QWDBHK

Job Queue Name

Iᑍ

Chapter 3. Common Information across APIs—Basic (OPM) Example 3-21

Download from Www.Somanuals.com. All Manuals Search And Download.

65 74 QWDBHL

Job Queue Lib Name

75 76 QWDBHM

Job Queue Priority

77 86 QWDBHN

Hold Job Queue

87 96 QWDBHP

Output Queue Name

97 1ð6 QWDBHQ

Output Queue Lib Name

1ð7 1ð8 QWDBHR

Output Queue Priority

1ð9 118 QWDBHS

Printer Device Name

119 148 QWDBHT

Print Text

B 149 152ðQWDBHV

Syntax Check Severity

B 153 156ðQWDBHW

End Severity

B 157 16ððQWDBHX

Message Log Severity

161 161 QWDBHY

Message Log Level

162 171 QWDBHZ

Message Log Text

172 181 QWDBHð

Log CL Programs

182 191 QWDBH1

Inquiry Message Reply

192 2ð4 QWDBH2

Device Recovery Action

2ð5 214 QWDBH3

Time Slice End Pool

215 229 QWDBH4

Accounting Code

23ð 3ð9 QWDBH5

Routing Data

31ð 359 QWDBH6

Text Description

36ð 36ð QWDBH7

Reserved

B 361 364ðQWDBH8 .19/

Offset Initial Lib List

B 365 368ðQWDBH9 .2ð/

Number Libs In Lib list

B 369 372ðQWDBJB

Offset Request Data

B 373 376ðQWDBJC

Length Request Data

B 377 38ððQWDBJH

Job Message Queue Max Size

381 39ð QWDBJJ

Job Message Queue Full Actio

391 391 QWDBJD

Iᑍ

Varying length

392 4ð2 QWDBJF

Iᑍ

Varying length

Iᑍ

4ð3 4ð3 QWDBJG

Iᑍ

Iᑍ Command String Data Structure

Iᑍ

ICMDSTR

I I

Iᑍ

'SNDMSG MSG(''LIBRARY-

' - '

1 22 CMD1

23 32 LIB

33 47 CMD2

''') TOUSR(QPGMR)'

Iᑍ Miscellaneous Data Structure

3-22 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Iᑍ

I I

Cᑍ

1ððð

4ðRCVLEN

8ðX

'JOBDð1ðð'

9 16 FORMAT

Cᑍ Beginning of Mainline

Cᑍ

Cᑍ Two parameters are being passed into this program.

Cᑍ

ᑍENTRY

PLIST

PARM

JOBD

1ð

Cᑍ

JOBDL 1ð

Cᑍ Move the two parameters passed into LFNAM.

Cᑍ

JOBD

CAT JOBDL

LFNAM 2ð

Cᑍ Error code Parameter is set to 1ðð

Cᑍ

Z-ADD1ðð

QUSBNB

Cᑍ

Cᑍ Instead of specifying 'QWCRJOBD', I could have used the

Cᑍ constant QWDBGB that was defined in the QWDRJOBD include.

Cᑍ

CALL 'QWDRJOBD'

PARM

QWDBH

RCVLEN

FORMAT

LFNAM

QUSBN

Receiver Var.

Length RCVVAR

Format Name

Qual. Job Desc

Error Code

Cᑍ See if any errors were returned in the error code parameter.

Cᑍ

C Nð1

Cᑍ

EXSR ERRCOD

Z-ADD47

LENSTR 155

C Nð1

QWDBH8

ADD 1

QWDBH9

1ð

SUBSTQWDBH:X

LIB

Cᑍ

Cᑍ Let's tell everyone what the library value is.

Cᑍ

CALL 'QCMDEXC'

PARM

CMDSTR

LENSTR

PARM

ADD 11

IFGE RCVLEN

LEAVE

ENDIF

ENDDO

Cᑍ

SETON

RETRN

Cᑍ

Cᑍ End of MAINLINE

Cᑍ

Cᑍ Subroutine to handle errors returned in the error code

Cᑍ parameter.

Cᑍ

ERRCOD

QUSBNC

BEGSR

IFGT ð

SETON

ð1

Error on API Call

Cᑍ

Cᑍ Process errors returned from the API.

Cᑍ

END

ENDSR

Note: It is important to access the count and to compare for the exact number of

libraries to be processed. If you do not check for the exact number of

Chapter 3. Common Information across APIs—Basic (OPM) Example 3-23

Download from Www.Somanuals.com. All Manuals Search And Download.

libraries, you may begin to access information in the format for the next set

of information (in this example, it may be the request data value).

The output for this program example is as follows:

Display Messages

System: GENSYS9ð

Queue . . . . . : QPGMR

Program . . . . : ᑍDSPMSG

Library . . . :

QUSRSYS

Severity . . . : ðð

Type reply (if required), press Enter.

LIBRARY - SMITH

From . . . : SMITH

LIBRARY - QTEMP

From . . . : SMITH

LIBRARY - QGPL

Delivery . . . : ᑍHOLD

ð7/23/94 12:29:38

From . . . : SMITH

LIBRARY - QBLDCPF

From . . . : SMITH

LIBRARY - UTIL

From . . . : SMITH

LIBRARY - OPENTEST

ð7/23/94 12:29:38

The handling of the initial library list field is typical of what you will find in many

APIs.

Using Keys with List Spooled Files API—Example

This topic introduces a new program named LSTSPL. Program LSTSPL uses the

List Spooled Files (QUSLSPL) API to determine the spooled file name, date

created, and number of pages for all spooled files created by the current user of

the LSTSPL program. Unlike the earlier JOBDAPI program examples, where

format JOBD0100 of the Retrieve Job Description (QWDRJOBD) API returned

dozens of fields while we were only interested in the HOLD field, the QUSLSPL API

provides a keyed interface that allows LSTSPL to request that only the relevant

fields (spooled file name, date created, and number of pages) be returned. In addi-

tion to providing a keyed interface, QUSLSPL also differs from QWDRJOBD in that

the QUSLSPL API retrieves a list of all spooled files into a User Space (*USRSPC)

while QWDRJOBD retrieves information about one specific job description into a

program variable.

In the following program example, all the pieces have been put together with an

OPM RPG program that accesses specific information related to spooled files. A

report listing this information is created. The program example does not handle

API-related errors. Any errors that are received are returned as exception mes-

sages.1/.

Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Fᑍ

Fᑍ Program Name:

LSTSPL

Fᑍ

Fᑍ Program Language:

OPM RPG

Fᑍ

Fᑍ Descriptive Name:

List Spooled Files for Current User

Fᑍ

Fᑍ Description:

Fᑍ

This example shows the steps necessary

to process keyed output from an API.

3-24 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Fᑍ

Fᑍ Header Files Included: QUSEC

- Error Code Parameter

Fᑍ

QUSGEN

- User Space Generic Header

Fᑍ

QUSLSPL - List Spooled Files

Fᑍ

Fᑍ APIs Used:

QUSLSPL - List Spooled Files

QUSCRTUS - Create User Space

QUSRTVUS - Retrieve User Space

Fᑍ

Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

FQSYSPRT O

Iᑍ

132

PRINTER

Iᑍ Copy User Space Generic Header

Iᑍ

I/COPY QSYSINC/QRPGSRC,QUSGEN

.11/

Iᑍ

Iᑍ Copy API Error Code parameter

Iᑍ

I/COPY QSYSINC/QRPGSRC,QUSEC

Iᑍ

Iᑍ Copy List Spooled Files API include

Iᑍ

I/COPY QSYSINC/QRPGSRC,QUSLSPL

Iᑍ

Iᑍ Data structure to hold space name

Iᑍ

ISPCNAM

I I

'SPCNAME

'QTEMP

1 1ð SPC

11 2ð LIB

I I

Iᑍ

Iᑍ Data structure to hold requested key values

Iᑍ

IKEYARA

I I

.5/ .7/

2ð1

216

211

4ðKEY1

8ðKEY2

I I

Iᑍ

9 12ðKEY3

.8/

Iᑍ Receiver variable for QUSRTVUS

Iᑍ

IRECVR

Iᑍ

1ððð

Iᑍ Other assorted variables

Iᑍ

4ðSIZ

8ðSTART

9 12ðLENDTA

B 13 16ðKEY#

B 17 2ððPAGES#

17 2ð PAGESA

21 21 INTVAL

I I

Cᑍ

X'ðð'

Cᑍ Initialize Error Code structure to accept exceptions

Cᑍ

Z-ADDð

QUSBNB .1/

Cᑍ Create the User Space to hold the QUSLSPL API results

Cᑍ

CALL 'QUSCRTUS'

PARM

.2/

SPCNAM

PARM 'quslspl' EXTATR 1ð

PARM 2ððð

PARM

PARM 'ᑍALL'

PARM

PARM 'ᑍYES'

PARM

SIZ

INTVAL

PUBAUT 1ð

TXTDSC 5ð

REPLAC 1ð

QUSBN

Cᑍ Call QUSLSPL to get all spooled files for ᑍCURRENT user

Cᑍ

CALL 'QUSLSPL'

PARM

.3/

SPCNAM

Chapter 3. Common Information across APIs—Basic (OPM) Example 3-25

Download from Www.Somanuals.com. All Manuals Search And Download.

Cᑍ

PARM 'SPLFð2ðð'FORMAT 8 .4/

PARM 'ᑍCURRENT'USRNAM 1ð

PARM 'ᑍALL'

PARM

OUTQ

2ð

FRMTYP 1ð

USRDTA 1ð

QUSBN

PARM

JOBNAM 26

KEYARA

KEY#

PARM

PARM 3

.5/

.6/

Cᑍ Retrieve information concerning the User Space and its contents

Cᑍ

CALL 'QUSRTVUS'

PARM

.9/

SPCNAM

START

LENDTA

QUSBP

QUSBN

PARM 1

Start Rtv at 1

for length =192

PARM 192

PARM

.1ð/

Cᑍ

Cᑍ Check User Space status for good information

Cᑍ

QUSBPD

QUSBPJ

IFEQ 'ð1ðð'

IFEQ 'C'

OREQ 'P'

.12/

.14/

Header Fmt

Complete

or Partial

Cᑍ

Cᑍ Check to see if any entries were put into User Space

Cᑍ

QUSBPS

IFGT ð

.16/

Cᑍ Keep count of how many list entries we have processed

Cᑍ

Z-ADDð

COUNT

9ð .17/

Cᑍ Adjust Offset value to Position value

Cᑍ

QUSBPQ

ADD 1

START

.18/

Cᑍ

Cᑍ Retrieve the lesser of allocated storage or available data

Cᑍ

QUSBPT

IFLT 1ððð

Z-ADDQUSBPT

ELSE

Z-ADD1ððð

ENDIF

.19/

LENDTA

Cᑍ

Cᑍ Process all entries returned

Cᑍ

COUNT

DOWLTQUSBPS

.2ð/

Cᑍ

Cᑍ Retrieve spooled file information

Cᑍ

CALL 'QUSRTVUS'

.21/

SPCNAM

START

LENDTA

RECVR

QUSBN

PARM

Cᑍ

Cᑍ Loop through returned fields

Cᑍ

SUBSTRECVR

Z-ADD5

QUSFV

.22/

.24/

4ð

QUSFVB

.23/

Cᑍ

Cᑍ Get header information

Cᑍ

SUBSTRECVR:X

QUSKR

Cᑍ Set Y to location of actual data associated with key

Cᑍ

ADD 16

4ð

3-26 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Cᑍ Process the data based on key type

Cᑍ

QUSKRC

CASEQ2ð1

CASEQ211

CASEQ216

CAS

FILNAM

PAGES

AGE

.25/

ERROR

END

Cᑍ

Cᑍ Adjust X to address next keyed record returned

Cᑍ

ADD QUSKRB

ENDDO

Cᑍ

Cᑍ Output information on spooled file

Cᑍ

EXCPTPRTLIN

.26/

.27/

Cᑍ

Cᑍ Adjust START to address next entry

Cᑍ

ADD 1

ADD QUSBPT

ENDDO

ENDIF

ELSE

EXCPTLSTERR

ENDIF

ELSE

EXCPTHDRERR

ENDIF

MOVE '1'

RETRN

COUNT

START

.15/

.13/

ᑍINLR

.28/

Cᑍ

Cᑍ Various subroutines

Cᑍ

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Cᑍ

FILNAM

BEGSR

Cᑍ Extract spooled file name for report

Cᑍ

MOVE ᑍBLANKS

SUBSTRECVR:Y

ENDSR

PRTFIL 1ð

PRTFIL

QUSKRG

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Cᑍ

PAGES

BEGSR

Cᑍ Extract number of pages for report

Cᑍ

QUSKRG

SUBSTRECVR:Y

ENDSR

PAGESA

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Cᑍ

AGE

BEGSR

Cᑍ Extract age of spooled file for report

Cᑍ

MOVE ᑍBLANKS

SUBSTRECVR:Y

ENDSR

OPNDAT 7

OPNDAT

QUSKRG

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Cᑍ

ERROR

BEGSR

Cᑍ If unknown key value, then display the value and end

Cᑍ

DSPLY

QUSKRC

ᑍINLR

MOVE '1'

RETRN

Oᑍ

ENDSR

OQSYSPRT E

PRTLIN

PRTFIL

PAGES#

OPNDAT

LSTERR

1ð

4ð

OQSYSPRT E

Chapter 3. Common Information across APIs—Basic (OPM) Example 3-27

Download from Www.Somanuals.com. All Manuals Search And Download.

22 'List data not valid

OQSYSPRT E

HDRERR

22 'Unknown Generic Header'

List APIs do not automatically create the user space (*USRSPC) to receive the list.

You must first create one using the Create User Space (QUSCRTUS) API.2/.

Similar to CL create commands, the QUSCRTUS API has several parameters that

identify the name of the object, the public authority, the object description text, and

so forth.

After creating the user space, you can call the QUSLSPL API to return spooled file

information into the user space.3/. The QUSLSPL API supports two formats:

SPLF0100, which returns a fixed set of information about each selected spooled

file, and SPLF0200, which returns only user-selected fields. LSTSPL uses

SPLF0200.4/ and passes to the QUSLSPL API a list of keys to identify the

selected fields.5/ and the number of keys.6/. Because OPM RPG does not

support an array (list) of binary values, LSTSPL defines the key array (KEYARA) as

a data structure comprised of contiguous binary(4) fields.7/. The fields are initial-

ized to 201, 216, and 211, which correspond to the keys named spooled file name,

date file was opened, and total pages, respectively.8/. Note that while the user

space was created with an initial size of 2000 bytes.2/, most List APIs implicitly

extend the user space (up to a maximum of 16MB) in order to return all available

list entries. The reverse, truncation when the user space is too large, is not per-

formed by list APIs.

Having generated the list, you can now process the user space data.

List APIs (like QUSLSPL) generally provide a generic list header at the beginning of

the user space, which provides information such as the API that created the list, the

number of entries (spooled files for this example) in the list, the size of each entry,

and so on. See the “User Space Format for List APIs” topic in the book System

API Reference for further information. To access the generic list header, use the

Retrieve User Space (QUSRTVUS) API.9/. Program LSTSPL retrieves the generic

list header into the data structure QUSBP.1ð/, which is defined in the QUSGEN

QSYSINC /COPY (include) file.11/. Note that languages, such as ILE RPG,

COBOL, and C, which support pointers, can avoid this call to QUSRTVUS (and the

resulting movement of data) by using the Retrieve Pointer to User Space

(QUSPTRUS) API. See “List Object API—Examples” on page B-94 for examples.

Program LSTSPL now checks that the format of the generic list header is the one

expected.12/, and if not, prints an error line.13/. Having verified the header

format, LSTSPL now checks the information status of the list.14/ (and if it is not

accurate, prints an error line.15/) and that at least one list entry is available.16/.

Having determined that accurate list entries are available, LSTSPL does the fol-

lowing:

Ÿ Initializes the COUNT variable to keep track of how many entries have been

processed.17/

Ÿ Adds one to the base 0 offset (to the first entry in the list) as the QUSRTVUS

API assumes base 1 positional values.18/

Ÿ Determines how much data is associated with each entry.19/ (which is the

lesser of either the amount of storage you allocated to receive a list entry, or

the size of a list entry)

3-28 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Ÿ Falls into a DO loop to process all of the available list entries.2ð/

Within this loop, LSTSPL retrieves each list entry.21/, extracts the number of fields

returned.22/, and enters an inner DO loop to process all of the available list entry

fields.23/.

Within this inner loop, the program extracts the field information.24/ and processes

the field data based on the key field.25/.

When all fields for a given list entry have been processed, LSTSPL generates a

print line.26/ and proceeds to the next list entry.27/.

When all the list entries have been processed, LSTSPL ends.28/.

Processing Lists That Contain Data Structures

Some APIs support a list where each entry in the list is itself a data structure. A

good example is the Retrieve System Status (QWCRSSTS) API. It supports mul-

tiple formats for different types of information. The SSTS0300 format contains a list

where each entry in the list has the information about a particular storage pool. In

addition to the two critical fields (the offset to where the list begins field and the

number of entries in the list field), the format also supports a field that describes the

length of each entry. In the initial library list, each entry was 11-bytes long. But in

a storage pool, a field (length of pool information entry) describes the length and

should be used instead of a fixed-length increment. This allows for growth, such as

more information being available in another release for each list entry.

For example, if another field is added to describe some additional information about

a storage pool, it is probably added after the paging option field. The length of pool

information entry allows your code to be upwardly compatible while it retains the

locations (relative to the start of a list entry) of the current fields.

Retrieve Job Description Information API—Example

The following API has been included as reference information. This API is used in

many examples throughout this chapter and should not be used to code your pro-

grams. Refer to the System API Reference, SC41-5801, for the most recent

version of this API.

Parameters

Required Parameter Group:

Receiver variable

Length of receiver variable

Format name

Qualified job description name

Error code

Output

Input

I/O

Char(*)

Binary(4)

Char(8)

Char(20)

Char(*)

The Retrieve Job Description Information (QWDRJOBD) API retrieves information

from a job description object and places it into a single variable in the calling

program. The amount of information returned depends on the size of the variable.

Chapter 3. Common Information across APIs—Basic (OPM) Example 3-29

Download from Www.Somanuals.com. All Manuals Search And Download.

The information returned is the same information returned by the Display Job

Description (DSPJOBD) command.

Authorities and Locks

Job Description Object Authority *USE

Library Authority

*USE

Required Parameter Group

Receiver variable

OUTPUT; CHAR(*)

The variable that is to receive the information requested. You can specify the

size of this area to be smaller than the format requested if you specify the

length of receiver variable parameter correctly. As a result, the API returns

only the data that the area can hold.

Length of receiver variable

INPUT; BINARY(4)

The length of the receiver variable. If this value is larger than the actual size of

the receiver variable, the result may not be predictable. The minimum length is

8 bytes.

Format name

INPUT; CHAR(8)

The format of the job description information to be returned. You can use this

format:

JOBD0100

Basic job description information. For details, see “JOBD0100

Format.”

Qualified job description name

INPUT; CHAR(20)

The name of the job description whose contents are to be retrieved. The first

10 characters contain the name of the job description, and the second 10 char-

acters contain the name of the library where the job description is located. You

can use these special values for the library name:

*CURLIB

*LIBL

The job's current library

The library list

Error code

I/O; CHAR(*)

The structure in which to return error information. For the format of the struc-

ture, see "Error Code Parameter" in Chapter 2 of the System API Reference.

JOBD0100 Format

The following table describes the information that is returned in the receiver vari-

able for the JOBD0100 format. For detailed descriptions of the fields, see “Field

Descriptions” on page 3-32.

Offset

Dec

Hex

Type

Field

BINARY(4)

Bytes returned

Bytes available

3-30 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Offset

Dec

Hex

Type

Field

CHAR(10)

CHAR(8)

Job description name

Job description library name

User name

Job date

CHAR(8)

Job switches

CHAR(10)

CHAR(2)

Job queue name

Job queue library name

Job queue priority

CHAR(10)

CHAR(2)

Hold on job queue

Output queue name

Output queue library name

Output queue priority

Printer device name

Print text

106

108

118

148

152

156

160

161

171

181

191

204

214

229

309

359

360

364

368

372

376

380

CHAR(10)

CHAR(30)

BINARY(4)

CHAR(1)

Syntax check severity

End severity

135

167

168

16C

170

174

178

17C

186

Message logging severity

Message logging level

Message logging text

Logging of CL programs

Inquiry message reply

Device recovery action

Time-slice end pool

Accounting code

CHAR(10)

CHAR(13)

CHAR(10)

CHAR(15)

CHAR(80)

CHAR(50)

CHAR(1)

Routing data

Text description

Reserved

BINARY(4)

CHAR(10)

CHAR(*)

Offset to initial library list .19/

Number of libraries in initial library list .2ð/

Offset to request data

Length of request data

Job message queue maximum size

Job message queue full action

Reserved

390

.1/

ARRAY (*) of

CHAR(11)

Initial library list

Request data

CHAR(*)

Chapter 3. Common Information across APIs—Basic (OPM) Example 3-31

Download from Www.Somanuals.com. All Manuals Search And Download.

Field Descriptions

Accounting code. An identifier assigned to jobs that use this job description.

This code is used to collect system resource use information. If the special value

*USRPRF is specified, the accounting code used for jobs using this job description

is obtained from the job's user profile.

Bytes available. The length of all data available to return. All available data is

returned if enough space is provided.

Bytes returned. The length of all data actually returned. If the data is truncated

because the receiver variable was not sufficiently large to hold all of the data avail-

able, this value will be less than the bytes available.

Device recovery action. The action to take when an I/O error occurs for the inter-

active job's requesting program device. The possible values are:

*SYSVAL

The value in the system value QDEVRCYACN at the time the job is started is

used as the device recovery action for this job description.

*MSG

Signals the I/O error message to the application and lets the application

program perform error recovery.

*DSCMSG

Disconnects the job when an I/O error occurs. When the job reconnects, the

system sends a message to the application program, indicating the job has

reconnected and that the workstation device has recovered.

*DSCENDRQS

Disconnects the job when an I/O error occurs. When the job reconnects, the

system sends the End Request (ENDRQS) command to return control to the

previous request level.

*ENDJOB

Ends the job when an I/O error occurs. A message is sent to the job's log

and to the history log (QHST). This message indicates that the job ended

because of a device error.

*ENDJOBNOLIST

Ends the job when an I/O error occurs. There is no job log produced for the

job. The system sends a message to the history log (QHST). This message

indicates that the job ended because of a device error.

End severity. The message severity level of escape messages that can cause a

batch job to end. The batch job ends when a request in the batch input stream

sends an escape message, whose severity is equal to or greater than this value, to

the request processing program. The possible values are from 0 through 99.

Hold on job queue. Whether jobs using this job description are put on the job

queue in the hold condition. The possible values are *YES and *NO.

Initial library list. The initial library list that is used for jobs that use this job

description. Only the libraries in the user portion of the library list are included.

Note: The data is an array of 11-byte entries, each entry consisting of a 10-byte

library name left-justified with a blank pad at the end. The 11-byte entries

can be easily used in CL commands. The number of libraries in the initial

library list tells how many entries are contained in the array.

3-32 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Inquiry message reply. How inquiry messages are answered for jobs that use

this job description.

*RQD

*DFT

The job requires an answer for any inquiry messages that occur while

the job is running.

The system uses the default message reply to answer any inquiry mes-

sages issued while the job is running. The default reply is either

defined in the message description or is the default system reply.

*SYSRPYL The system reply list is checked to see if there is an entry for an

inquiry message issued while the job is running. If a match occurs, the

system uses the reply value for that entry. If no entry exists for that

message, the system uses an inquiry message.

Job date. The date that will be assigned to jobs using this job description when

they are started. The possible values are:

*SYSVAL

The value in the QDATE system value is used at the time the job is started.

job-date

The date to be used at the time the job is started. This date is in the format

specified for the DATFMT job attribute.

Job description library name. The name of the library in which the job

description resides.

Job description name. The name of the job description about which information

is being returned.

Job message queue maximum size. The maximum size (in megabytes) of the

job message queue. The possible values are:

The maximum size set by system value QJOBMSGMX at the time the

job is started.

2–64

The maximum size of the job message queue in megabytes.

Job message queue full action. The action taken when the job message queue

becomes full. The possible values are:

*SYSVAL The value is specified by the system value QJOBMSGQFL.

*NOWRAP

When the message queue becomes full, do not wrap. This action will

cause the job to end.

*WRAP

When the message queue becomes full, wrap to the beginning and start

filling again.

*PRTWRAP

When the message queue becomes full, wrap the job queue and print

the messages that are being overlaid.

Job queue library name. The library of the job queue into which batch jobs using

this job description are placed.

Job queue name. The name of the job queue into which batch jobs using this job

description are placed.

Job queue priority. The scheduling priority of each job that uses this job

description. The highest priority is 1 and the lowest priority is 9.

Chapter 3. Common Information across APIs—Basic (OPM) Example 3-33

Download from Www.Somanuals.com. All Manuals Search And Download.

Job switches. The initial settings for a group of eight job switches used by jobs

that use this job description. These switches can be set or tested in a program and

used to control a program's flow. The possible values are '0' (off) and '1' (on).

Length of request data. The length of all available request data, in bytes. If the

receiver variable was not sufficiently large to hold all of the request data available,

the amount of request data actually returned may be less than this value.

Logging of CL programs. Whether or not messages are logged for CL programs

that are run. The possible values are *YES and *NO.

Message logging level. The type of information logged. Possible types are:

No messages are logged.

All messages sent to the job's external message queue with a severity greater

than or equal to the message logging severity are logged.

The following information is logged:

Ÿ Level 1 information.

Ÿ Requests or commands from CL programs for which the system issues

messages with a severity code greater than or equal to the logging

severity.

Ÿ All messages associated with those requests or commands that have a

severity code greater than or equal to the logging severity.

The following information is logged:

Ÿ Level 1 information.

Ÿ All requests or commands from CL programs.

Ÿ All messages associated with those requests or commands that have a

severity greater than or equal to the logging severity.

The following information is logged:

Ÿ All requests or commands from CL programs.

Ÿ All messages with a severity code greater than or equal to the logging

severity.

Message logging severity. The minimum severity level that causes error mes-

sages to be logged in the job log. The possible values are from 0 through 99.

Message logging text. The level of message text that is written in the job log or

displayed to the user when an error message is created according to the logging

level and logging severity. The possible values are:

*MSG

Only the message is written to the job log.

*SECLVL

Both the message and the message help for the error message are written to

the job log.

*NOLIST

If the job ends normally, there is no job log. If the job ends abnormally (the

job end code is 20 or higher), there is a job log. The messages appearing in

the job's log contain both the message and the message help.

Number of libraries in initial library list. The number of libraries in the user

portion of the initial library list. Up to 25 libraries can be specified.

Offset to initial library list. The offset from the beginning of the structure to the

start of the initial library list.

3-34 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Offset to request data. The offset from the beginning of the structure to the start

of the request data.

Output queue library name. The name of the library in which the output queue

resides.

Output queue name. The name of the default output queue that is used for

spooled output produced by jobs that use this job description.

*USRPRF The output queue name for jobs using this job description is obtained

from the user profile of the job at the time the job is started.

*DEV

The output queue with the same name as the printer device for this job

description is used.

*WRKSTN The output queue name is obtained from the device description from

which this job is started.

output-queue-name

The name of the output queue for this job description.

Output queue priority. The output priority for spooled files that are produced by

jobs using this job description. The highest priority is 1, and the lowest priority is 9.

Print text. The line of text (if any) that is printed at the bottom of each page of

printed output for jobs using this job description. If the special value *SYSVAL is

specified, the value in the system value QPRTTXT is used for jobs using this job

description.

Printer device name. The name of the printer device or the source for the name

of the printer device that is used for all spooled files created by jobs that use this

job description.

*USRPRF

The printer device name is obtained from the user profile of the job at the

time the job is started.

*SYSVAL

The value in the system value QPRTDEV at the time the job is started is used

as the printer device name.

*WRKSTN

The printer device name is obtained from the work station where the job was

started.

printer-device-name

The name of the printer device that is used with this job description.

Request data. The request data that is placed as the last entry in the job's

message queue for jobs that use this job description. The possible values are:

*NONE

No request data is placed in the job's message queue.

*RTGDTA

The data specified in the routing data parameter is placed as the last entry in

the job's message queue.

request-data

The request data to use for jobs that use this job description.

Reserved. An ignored field.

Chapter 3. Common Information across APIs—Basic (OPM) Example 3-35

Download from Www.Somanuals.com. All Manuals Search And Download.

Routing data. The routing data that is used with this job description to start jobs.

The possible values are:

QCMDI

The default routing data QCMDI is used by the IBM-supplied interactive sub-

system to route the job to the IBM-supplied control language processor

QCMD in the QSYS library.

*RQSDTA

Up to the first 80 characters of the request data specified in the request data

field are used as the routing data for the job.

routing-data

The routing data to use for jobs that use this job description.

Syntax check severity. Whether requests placed on the job's message queue

are checked for syntax as CL commands, and the message severity that causes a

syntax error to end processing of a job. The possible values are:

-1

The request data is not checked for syntax as CL commands. This is

equivalent to *NOCHK.

0–99

Specifies the lowest message severity that causes a running job to end.

The request data is checked for syntax as CL commands, and, if a syntax

error occurs that is greater than or equal to the error message severity

specified here, the running of the job that contains the erroneous

command is suppressed.

Text description. The user text, if any, used to briefly describe the job

description.

Time-slice end pool. Whether interactive jobs using this job description should be

moved to another main storage pool when they reach time-slice end. The possible

values are:

*SYSVAL The system value is used.

*NONE

*BASE

The job is not moved when it reaches time-slice end.

The job is moved to the base pool when it reaches time-slice end.

User name. The name of the user profile associated with this job description. If

*RQD is specified, a user name is required to use the job description.

Error Messages

CPF1618 E Job description &1 in library &2 damaged.

CPF24B4 E Severe error while addressing parameter list.

CPF3CF1 E Error code parameter not valid.

CPF3CF2 E Error(s) occurred during running of &1 API.

CPF3C21 E Format name &1 is not valid.

CPF3C24 E Length of the receiver variable is not valid.

CPF9801 E Object &2 in library &3 not found.

CPF9802 E Not authorized to object &2 in &3.

CPF9803 E Cannot allocate object &2 in library &3.

CPF9804 E Object &2 in library &3 damaged.

CPF9807 E One or more libraries in library list deleted.

CPF9808 E Cannot allocate one or more libraries on library list.

CPF9810 E Library &1 not found.

CPF9820 E Not authorized to use library &1.

CPF9830 E Cannot assign library &1.

3-36 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

CPF9872 E Program or service program &1 in library &2 ended. Reason code &3.

Chapter 3. Common Information across APIs—Basic (OPM) Example 3-37

Download from Www.Somanuals.com. All Manuals Search And Download.

3-38 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Chapter 4. Common Information across APIs—Advanced

(ILE) Example

Through the use of several examples, this chapter provides information about how

to use more advanced or more complex API concepts in your programs. The

example programs in this chapter use ILE APIs. These examples are also shown

in additional languages in “Integrated Language Environment (ILE)

APIs—Examples” on page B-47.

In the examples, the following are focus items:

Ÿ Header files

Ÿ Keyed interfaces

Ÿ Error handling

Ÿ Receiver variables

For more information about the APIs used in this chapter, refer to the System API

Reference, SC41-5801.

Integrated Language Environment (ILE) APIs—Introduction

OS/400 Integrated Language Environment (ILE) APIs are contained within service

programs that the calling program binds to. In addition, some OS/400 ILE APIs

provide a program interface for the original program model (OPM) languages. You

can usually distinguish between the *SRVPGM interface and the *PGM interface by

the name of the API. For example, the registration facility APIs provide both a

program and a service program entry point (procedure) interface. For the Register

Exit Point API, the service program entry point interface is named

QusRegisterExitPoint and the program interface is named QUSRGPT. A bindable

procedure name can be up to 30 characters and mixed uppercase and lowercase.

A program interface name can be up to 8 characters and is all uppercase.

A binding directory is used for OS/400 ILE APIs that are contained in service pro-

grams. A binding directory is a list of names of modules and service programs

that provides a reference by name and type. Service programs that contain

OS/400 ILE APIs are in the QUSAPIBD binding directory. This binding directory is

implicitly used by ILE compilers to resolve the OS/400 ILE API references; there-

fore, it is not necessary to explicitly name the service program or the API binding

directory when creating programs that use OS/400 ILE APIs. If you provide your

own APIs with the same name, make sure that you also provide your own binding

directory or service program.

All OS/400 APIs (ILE and non-ILE) have a header file supplied by OS/400. These

header files reside in the optionally installable library QSYSINC. The header files

provide the prototypes for the API as well as define any structures that are used by

the API. The QSYSINC library is used by the ILE C compiler to search for header

files; therefore, it is not necessary to specify a library qualifier for any header files

that reside in the QSYSINC library. When coding in ILE C, remember to enclose

the header file name in less-than (<) and greater-than (>) symbols because this

affects how the library list is processed in locating the header file.

 Copyright IBM Corp. 1997

4-1

Download from Www.Somanuals.com. All Manuals Search And Download.

The example APIs in this chapter represent two general functions of APIs—change

and retrieve. It is typical for an API that is not retrieving information not to return

any output to the caller other than the error code parameter. If an error did not

occur when using APIs, the requested function completed successfully.

The presentation of the ILE APIs in the System API Reference is similar to the

OPM APIs. For a general discussion of the API topics, see “Description of an API”

on page 3-2.

Registration Facility Using ILE APIs—Concepts

The following examples illustrate the use of OS/400 ILE APIs. The examples use

the registration facility APIs. The registration facility APIs provide a means for

storing and retrieving information about exit points and exit programs. An exit

point is a specific point in a system function or program where control may be

passed to one or more exit programs. An exit program is a program to which

control is passed from an exit point. The examples show how to manipulate exit

points and exit programs, how to retrieve information about exit points and exit pro-

grams that are stored with the registration facility, and how to call an exit program.

Several of the registration facility APIs manipulate the information that the registra-

tion facility repository contains. One API is provided for retrieving information from

the repository.

The example programs are provided at the end of this chapter in their entirety (see

“Registration Facility Using ILE APIs—Examples” on page 4-9). The example

makes use of a continuation handle. Following are portions of the code to help

illustrate concepts pertaining to the use of OS/400 ILE APIs. The following con-

cepts include:

Ÿ Various types of header files

Ÿ The use of keyed interfaces

Ÿ Error handling and the error code parameter

Ÿ The use of receiver variables for returned information

Generic Header Files

This topic shows how to use a generic header file from the QSYSINC (system

include) library in a program. For information about the QSYSINC header files, see

“APIs and the QSYSINC Library” on page 2-28.

In addition to the traditional C-library header files (such as stdio and string), the API

header file qusrgfa1.h is included in the following example. The qusrgfa1.h header

file defines the functions exported from service program QUSRGFA1. This service

program contains the APIs provided for manipulating the information in the reposi-

tory. A second service program named QUSRGFA2 contains the ILE API for

retrieving information from the registration facility repository. The header file

qusec.h contains the definition for the error code structure that is used for the error

code parameter. The following list shows the standard C header files (the first four

includes) and a few AS/400-defined header files for APIs. This list does not show

all the header files used in the example programs starting on page 4-9.

4-2 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

#include <stdio.h>

#include <signal.h>

#include <string.h>

#include <stdlib.h>

#include <qusrgfa1.h>

#include <qusec.h>

Variable-Length Structure—Example

Many of the structures needed are provided by the QSYSINC (system include)

library. However, any fields of a structure that are variable in length are not defined

by QSYSINC and must be defined by the user. For example, in the qusec.h

header file, the structure Qus_EC_t is defined as:

typedef struct Qus_EC {

int Bytes_Provided;

int Bytes_Available;

char Exception_Id[7];

char Reserved;

/ᑍchar Exception_Data[]; .1/ᑍ/ /ᑍ Varying length field ᑍ/

} Qus_EC_t;

Because the Exception_Data field .1/ is a varying-length field, it is shown as a

comment. The following is a new error code structure, which defines the

exception_data field .2/. It was created by using the structure that was defined in

the qusec.h header file.

typedef struct {

Qus_EC_t ec_fields;

char

exception_data[1ðð].2/;

} error_code_struct;

Within QSYSINC include files, all varying-length fields and arrays are in the form of

comments so that you can control how much storage to allocate based on your

specific requirements.

Keyed Interface—Example

This example shows how to set key values for a keyed interface.

Exit Program Attributes Parameter

The interface for the Add Exit Program API is a keyed interface. One of the param-

eters for the Add Exit Program API is the exit program attributes parameter. The

exit program attributes are provided to the API by means of a variable-length

record. Typically, APIs that use a variable-length record interface use either a 3- or

4-field record. The Add Exit Program API makes use of a 4-field variable-length

record .4/. The exit program attributes parameter for the API is defined as follows:

.3/

Type

Field

BINARY(4)

Number of variable-length records

.4/

Chapter 4. Common Information across APIs—Advanced (ILE) Example 4-3

Download from Www.Somanuals.com. All Manuals Search And Download.

Type

Field

BINARY(4)

CHAR(*)

Length of variable-length record

Exit program attribute key

Length of data

Data

The number of variable-length records field .3/ is the first 4 bytes, and this field

tells the API how many variable-length records have been specified. The fields

defined in .4/ are repeated (contiguously) immediately following the number of

variable-length records for each record that is sent to the API. The API gets to

each variable-length record by using the length of variable-length record field to get

to the next record, up to and including the number of records specified.

The variable-length record structures are defined in the qus.h header file (this

C-language header file is included by the qusrgfa1.h header file). The 4-field

variable-length record is defined as:

typedef _Packed struct Qus_Vlen_Rec_4 {

int Length_Vlen_Record;

int Control_Key;

int Length_Data;

/ᑍchar Data[];ᑍ/

/ᑍ Varying length field ᑍ/

} Qus_Vlen_Rec_4_t;

Because the data field is a varying-length field, it needs to be defined in a new

structure.

Exit Program Attribute Keys

The Add Exit Program API has several exit program attributes that can be set. The

following table shows the valid exit program attribute keys for the key field area of

the variable-length record.

Key

Type

Field

CHAR(27)

Qualified message file name and message identifier for exit

program description

CHAR(50)

BINARY(4)

CHAR(1)

Exit program text description

Exit program data CCSID

Replace

This example specifies only two attribute keys (replace_rec and CCSID_rec fields)

and lets the remaining attribute keys be set by the API to the default value. When

working with variable-length structures, each variable-length record must start on a

4-byte boundary alignment. (The 4-byte boundary alignment requirement is only

true for the registration facility APIs, not all keyed APIs.) The following new struc-

ture becomes the exit program attributes parameter on the call to the Add Exit

Program API:

typedef struct {

int

num_rec;

Qus_Vlen_Rec_4_t replace_rec;

char

replace;

Reserved[3];

4-4 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Qus_Vlen_Rec_4_t CCSID_rec;

int

CCSID;

} addep_attributes;

The num_rec field is set to the value of 2 because the example specifies two

variable-length records. The replace_rec field contains the length of the variable-

length record (value of 16), the key (value of 4), and the length of the data (value of

1). The replace field contains the data for the replace key. The Reserved field

reserves 3 bytes to force the next record to start on a 4-byte boundary alignment.

The 3 bytes that are reserved are counted as part of the length for the replace

variable-length record. The next record then follows the first record.

Error Handling

Error handling with ILE APIs can be accomplished in two ways: use the error code

parameter or have exceptions signaled by the API to your application program.

Error Handling through the Error Code Parameter

The error code parameter enables a user to have exceptions returned to the

program through the use of the parameter instead of having the exceptions sig-

naled. Some exceptions may be signaled to the caller regardless of the size of the

error code parameter. These exceptions are usually from errors that occur with the

error code parameter itself (that is, message CPF3CF1) or with one of the other

parameters (that is, message CPF9872). In the latter case, message CPF9872 is

always signaled and never returned through the error code parameter because the

API is unable to verify the error code parameter before the exception occurs.

The caller of the API must initialize the error code parameter so that the bytes pro-

vided field is set to the size, in bytes, of the error code parameter. For example,

the error_code_struct structure on page 4-3 sets the size at 116 bytes. To initialize

the error code parameter, do the following:

1. Allocate storage for the error code parameter:

error_code_struct error_code;

2. Initialize the bytes provided field to the number of bytes that were allocated for

the parameter:

error_code.ec_fields.Bytes_Provided=sizeof(error_code_struct);

If the bytes provided field is set to a value equal to or greater than 8, the caller

wants all exceptions returned through the error code parameter. The API fills in all

of the message information up to the size of the error code parameter.

Error Determination—Example: On the return from the call to the API, verify

whether or not an error occurred. If an error occurred, the bytes available field is

set to something other than zero. If the bytes available field is not zero, you can

use the message ID and the message data to determine what the program should

do next. To receive the message ID and data, you must provide enough storage

on the error code parameter for the information.

In the following example, the bytes available field is checked to determine if an

error occurred. In this case, if an error occurred, a message is printed, which

states the message ID and that the call to the API failed.

Chapter 4. Common Information across APIs—Advanced (ILE) Example 4-5

Download from Www.Somanuals.com. All Manuals Search And Download.

if (error_code.ec_fields.Bytes_Available != ð)

{

printf("ATTEMPT TO REGISTER EXIT POINT FAILED WITH EXCEPTION: %.7s",

error_code.ec_fields.Exception_Id);

exit(1);

}

Message Data—Example: If your program needs to handle different exceptions in

different ways, you may need to make use of both the message data and the

message ID. The message data is returned in the same format as when you

display the message description on an AS/400. For example, if message

CPF3C1E is received, some of the message data is printed. You can see

message data that is associated with the message by using the Display Message

Description (DSPMSGD) command. The message data for message CPF3C1E is

defined as:

BIN(4)

Parameter number

CHAR(256)

ILE entry point name

To receive all of the message data for this exception, the exception data field of the

error code structure would need to be at least 260 bytes in size. The following

example uses only the number of bytes shown for the parameter number of the

exception in the message data; therefore, the exception data field only needs to be

4 bytes.

int parm_number;

char ᑍtemp_ptr;

if (error_code.ec_fields.Bytes_Available != ð)

{

if (memcmp(error_code.ec_fields.Exception_Id,"CPF3C1E",7)==ð)

{

printf("\nFAILED WITH CPF3C1E:");

temp_ptr=&(error_code.exception_data);

parm_number=ᑍ((int ᑍ)temp_ptr);

printf("\n Parameter number omitted: %d",parm_number);

}

else

{

printf("ATTEMPT TO REGISTER EXIT POINT FAILED WITH EXCEPTION: %.7s",

error_code.ec_fields.Exception_Id);

exit(1);

}

Error Handling Signaled by API

The second means of exception handling is by having all exceptions signaled by

the API to the calling program. To have all exceptions signaled by the API, set the

bytes provided field of the error code structure to zero. Refer to the documentation

of your specific programming language for information on exception handling.

4-6 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Receiver Variables—Examples

As discussed in “Receiver Variables” on page 2-23, receiver variables are generally

used by retrieve APIs to return information to a caller. This topic provides coding

examples of repeating entry types and of the use of offsets to go from one entry to

the next in the receiver variable.

Repeating Entry Type with Fixed-Length Fields—Example

In the following example, the EXTI0100 format is defined in the qusreg.h header

file, which is included by the qusrgfa2.h header file in the QSYSINC library.

This format is of the repeating entry type with all fixed-length fields. The repeating

portion of the format (Qus_EXTI0100_Entry_t) is repeated after the fixed portion.

The fixed portion of the format (Qus_EXTI0100_t) is returned only once. To go

from one entry to the next, you add the offset exit point entry field to the starting

position of the receiver variable to get to the first entry. Add the length exit point

entry field to the current position in the receiver variable to move to the subsequent

entries.

typedef _Packed struct Qus_EXTIð1ðð_Entry {

char Exit_Point_Name[2ð];

char Format_Name[8];

int Max_Exit_Programs;

int Number_Exit_Programs;

char Allow_Deregistration;

char Allow_Change_Control;

char Registered_Exit_Point;

char Prep_Name_Add_Pgm[1ð];

char Prep_Lib_Add_Pgm[1ð];

char Prep_Format_Add[8];

char Prep_Name_Rmv_Pgm[1ð];

char Prep_Lib_Rmv_Pgm[1ð];

char Prep_Format_Rmv[8];

char Prep_Name_Rtv_Info[1ð];

char Prep_Lib_Rtv_Info[1ð];

char Prep_Format_Rtv[8];

char Desc_Indicator;

char Desc_Msg_File[1ð];

char Desc_Msg_Library[1ð];

char Desc_Msg_Id[7];

char Text_Description[5ð];

/ᑍchar Reserved[];ᑍ/

} Qus_EXTIð1ðð_Entry_t;

typedef _Packed struct Qus_EXTIð1ðð {

int Bytes_Returned;

int Bytes_Available;

char Continue_Handle[16];

int Offset_Exit_Point_Entry;

int Number_Points_Returned;

int Length_Exit_Point_Entry;

/ᑍchar Reserved[];ᑍ/

/ᑍQus_EXTIð1ðð_Entry_t Array[];ᑍ/

} Qus_EXTIð1ðð_t;

Chapter 4. Common Information across APIs—Advanced (ILE) Example 4-7

Download from Www.Somanuals.com. All Manuals Search And Download.

Repeating Entry Type with Variable-Length Fields—Example

In this example, the EXTI0200 format is defined in the qusreg.h header file, which

is included by the qusrgfa2.h header file in the QSYSINC library.

This format is of the repeating entry type with some variable-length fields. The

repeating portion of the format (Qus_EXTI0200_Entry_t) is repeated for each entry

returned, and the fixed portion of the format (Qus_EXTI0200_t) is returned only

once. To go from one entry to the next, you add the offset program entry field to

the starting position of the receiver variable to get to the first entry. Then add the

offset next entry field to the starting position of the receiver variable to get to each

subsequent entry. To get to the Prog_Data field, add the offset exit data field to

the starting position of the receiver variable and use the length exit data field to

determine the number of bytes of information in the Prog_Data field.

typedef _Packed struct Qus_EXTIð2ðð_Entry {

int Offset_Next_Entry;

char Exit_Point_Name[2ð];

char Format_Name[8];

char Registered_Exit_Pt;

char Complete_Entry;

char Reserved[2];

int Program_Number;

char Program_Name[1ð];

char Program_Library[1ð];

int Data_Ccsid;

int Offset_Exit_Data;

int Length_Exit_Data;

/ᑍchar Reserved[];ᑍ/

/ᑍQus_Program_Data_t Prog_Data;ᑍ/

} Qus_EXTIð2ðð_Entry_t;

typedef _Packed struct Qus_EXTIð2ðð {

int Bytes_Returned;

int Bytes_Available;

char Continue_Handle[16];

int Offset_Program_Entry;

int Number_Programs_Returned;

int Length_Program_Entry;

/ᑍchar Reserved[];ᑍ/

/ᑍQus_EXTIð2ðð_Entry_t Array[];ᑍ/

} Qus_EXTIð2ðð_t;

Offsets Type—Example: The following portion of code illustrates the use of the

offsets to go from one entry to the next in the receiver variable:

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ Save the number of exit programs returned, and set the pointer ᑍ/

/ᑍ to point to the first exit program entry.

ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

rcv_ptr=rcv_var;

num_exit_pgms=((Qus_EXTIð2ðð_t ᑍ)rcv_ptr)→Number_Programs_Returned;

rcv_ptr += ((Qus_EXTIð2ðð_t ᑍ)rcv_ptr)→Offset_Program_Entry;

rsl_ok=1;

for (i=ð; i<num_exit_pgms; i++)

{

memcpy(exit_pgm_name,

((Qus_EXTIð2ðð_Entry_t ᑍ)rcv_ptr)→Program_Name,1ð);

4-8 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

memcpy(exit_pgm_lib,

((Qus_EXTIð2ðð_Entry_t ᑍ)rcv_ptr)→Program_Library,1ð);

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ Resolve to the exit program. If an error occurs on the

/ᑍ resolve operation to the library, the rsl_ok indicator is

/ᑍ set to failed in the RSL_PGM_HDLR exception handler.

/ᑍ The RSLVSP MI instruction signals all errors to this

/ᑍ program; therefore, enable the exception handler to

/ᑍ capture any errors that may occur.

ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

#pragma exception_handler (RSLVSP_PGM_HDLR,rsl_ok,ð,_C2_MH_ESCAPE)

exit_pgm_ptr=((Pgm_OS ᑍ)rslvsp(_Program,

exit_pgm_name,

exit_pgm_lib,

_AUTH_POINTER));

#pragma disable_handler

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ If the resolve is successful, call the exit program.

/ᑍ If not, move on to the next exit program.

ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

if (rsl_ok)

{

exit_pgm_ptr(info_for_exit_pgm);

}

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ Set the receiver variable to point to the next exit program ᑍ/

/ᑍ that is returned.

ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

rsl_ok=1;

rcv_ptr=rcv_var +

((Qus_EXTIð2ðð_Entry_t ᑍ)rcv_ptr)→Offset_Next_Entry;

}

Registration Facility Using ILE APIs—Examples

Following are the entire program listings for the ILE C programs discussed in the

preceding topics. The programs perform the following tasks:

Ÿ Register an exit point and add an exit program

Ÿ Retrieve exit point and exit program information

Ÿ Remove an exit program and deregister an exit point

These example programs are also shown in additional languages in “Integrated

Language Environment (ILE) APIs—Examples” on page B-47.

The following program registers an exit point with the registration facility and adds

an exit program to the exit point.

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ PROGRAM:

Add an Exit Program

ᑍ/

/ᑍ

/ᑍ LANGUAGE:

ILE C

Chapter 4. Common Information across APIs—Advanced (ILE) Example 4-9

Download from Www.Somanuals.com. All Manuals Search And Download.

/ᑍ

ᑍ/

/ᑍ DESCRIPTION: This program registers an exit point with the

/ᑍ

registration facility. After the successful

/ᑍ

completion of the registration of the exit point, ᑍ/

an exit program is added to the exit point.

/ᑍ

ᑍ/

/ᑍ

/ᑍ APIs USED:

QusRegisterExitPoint - Register Exit Point

/ᑍ

QusAddExitProgram

- Add Exit Program

/ᑍ NOTE: This example uses APIs that are shipped with ᑍEXCLUDE ᑍ/

authority. The user needs ᑍUSE authority to the service ᑍ/

program QUSRGFA1 to use these APIs. ᑍ/

/ᑍ

Includes

ᑍ/

#include <stdio.h>

#include <signal.h>

#include <string.h>

#include <stdlib.h>

#include <qusrgfa1.h>

#include <qusec.h>

#include <qliept.h>

/ᑍ

Structures

ᑍ/

typedef struct {

/ᑍ Error code

ᑍ/

Qus_EC_t ec_fields;

char

exception_data[1ðð];

} error_code_struct;

typedef struct {

/ᑍ Exit point control keys

ᑍ/

int

num_rec;

Qus_Vlen_Rec_4_t max_pgms_rec;

int

max_pgms;

Qus_Vlen_Rec_4_t descrip_rec;

char

} rgpt_controls;

text_desc[5ð];

typedef struct {

int

/ᑍ Exit program attribute keysᑍ/

num_rec;

Qus_Vlen_Rec_4_t replace_rec;

char

replace;

Reserved[3];

Qus_Vlen_Rec_4_t CCSID_rec;

int

CCSID;

} addep_attributes;

/ᑍ

ᑍ/

main

4-10 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

int main()

{

int ccsid,

pgm_num,

num_of_attrs,

epgm_num,

len_epgm_data,

add_epgm_num,

ᑍccsid_ptr,

ᑍpgm_num_ptr;

error_code_struct error_code;

rgpt_controls control_keys;

addep_attributes attrib_keys;

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ Register the exit point with the registration facility. If the ᑍ/

/ᑍ registration of the exit point is successful, add an exit

/ᑍ program to the exit point.

ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ Initialize the error code parameter. To signal exceptions to ᑍ/

/ᑍ this program by the API, you need to set the bytes provided

/ᑍ field of the error code to zero. Because this program has

ᑍ/

/ᑍ exceptions sent back through the error code parameter, it sets ᑍ/

/ᑍ the bytes provided field to the number of bytes that it gives ᑍ/

/ᑍ the API for the parameter.

ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

error_code.ec_fields.Bytes_Provided=sizeof(error_code_struct);

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ Set the exit point controls. Each control field is passed to ᑍ/

/ᑍ the API using a variable length record. Each record must

/ᑍ start on a 4-byte boundary.

ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ Set the total number of controls that are being specified on ᑍ/

/ᑍ the call. This program lets the API take the default for the ᑍ/

/ᑍ controls that are not specified.

ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

control_keys.num_rec=2;

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ Set the values for the two controls that are specified:

/ᑍ Maximum number of exit programs = 1ð

ᑍ/

/ᑍ Exit point text description

= "EXIT POINT EXAMPLE"

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

control_keys.max_pgms_rec.Length_Vlen_Record=16;

control_keys.max_pgms_rec.Control_Key=3;

control_keys.max_pgms_rec.Length_Data=4;

control_keys.max_pgms=1ð;

control_keys.descrip_rec.Length_Vlen_Record=62;

control_keys.descrip_rec.Control_Key=8;

control_keys.descrip_rec.Length_Data=5ð;

memcpy(control_keys.text_desc,

"EXIT POINT EXAMPLE

",5ð);

Chapter 4. Common Information across APIs—Advanced (ILE) Example 4-11

Download from Www.Somanuals.com. All Manuals Search And Download.

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ Call the API to register the exit point.

ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

QusRegisterExitPoint("EXAMPLE_EXIT_POINT ",

"EXMPð1ðð",

&control_keys,

&error_code);

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ If an exception occurs, the API returns the exception in the ᑍ/

/ᑍ error code parameter. The bytes available field is set to

ᑍ/

/ᑍ zero if no exception occurs and nonzero if an exception does ᑍ/

/ᑍ occur.

ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

if (error_code.ec_fields.Bytes_Available != ð)

{

printf("ATTEMPT TO REGISTER EXIT POINT FAILED WITH EXCEPTION: %.7s",

error_code.ec_fields.Exception_Id);

exit(1);

}

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ If the call to register an exit point is successful, add

/ᑍ an exit program to the exit point.

ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ Set the total number of exit program attributes that are being ᑍ/

/ᑍ specified on the call. This program lets the API take the

/ᑍ default for the attributes that are not specified. Each

/ᑍ attribute record must be 4-byte aligned.

ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

attrib_keys.num_rec=2;

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ Set the values for the two attributes that are being

/ᑍ specified:

ᑍ/

/ᑍ

Replace exit program

= 1

Exit program data CCSID = 37

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

attrib_keys.replace_rec.Length_Vlen_Record=16;

attrib_keys.replace_rec.Control_Key=4;

attrib_keys.replace_rec.Length_Data=1;

attrib_keys.replace='1';

attrib_keys.CCSID_rec.Length_Vlen_Record=16;

attrib_keys.CCSID_rec.Control_Key=3;

attrib_keys.CCSID_rec.Length_Data=4;

attrib_keys.CCSID=37;

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ Call the API to add the exit program.

ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

QusAddExitProgram("EXAMPLE_EXIT_POINT ",

"EXMPð1ðð",

4-12 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

"EXAMPLEPGMEXAMPLELIB",

"EXAMPLE EXIT PROGRAM DATA",

25,

&attrib_keys,

&error_code);

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ If an exception occurs, the API returns the exception in the ᑍ/

/ᑍ error code parameter. The bytes available field is set to

ᑍ/

/ᑍ zero if no exception occurs and nonzero if an exception does ᑍ/

/ᑍ occur.

ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

if (error_code.ec_fields.Bytes_Available != ð)

{

printf("ATTEMPT TO ADD AN EXIT PROGRAM FAILED WITH EXCEPTION: %.7s",

error_code.ec_fields.Exception_Id);

exit(1);

}

} /ᑍ End program ᑍ/

Retrieve Exit Point and Exit Program Information—ILE C Example

The following program retrieves information about exit points and exit programs. It

then resolves to each exit program and calls the exit program.

The Retrieve Exit Information API returns a continuation handle when it has more

information to return than what fits in the receiver variable. For more information

about continuation handles, see “Continuation Handle” on page 2-25.

/ᑍ PROGRAM:

Retrieve Exit Point and Exit Program Information ᑍ/

ᑍ/

/ᑍ

/ᑍ LANGUAGE:

/ᑍ

ILE C

ᑍ/

/ᑍ DESCRIPTION: This program retrieves exit point and exit

/ᑍ

program information. After retrieving the

exit point information, the program resolves to ᑍ/

each associated exit program and calls each exit ᑍ/

program.

ᑍ/

/ᑍ APIs USED: QusRetrieveExitInformation - Retrieve Exit

/ᑍ

Information

/ᑍ

Includes

ᑍ/

#include <stdio.h>

#include <signal.h>

#include <string.h>

#include <stdlib.h>

#include <except.h>

#include <qusrgfa2.h>

#include <qusec.h>

#include <qmhchgem.h>

Chapter 4. Common Information across APIs—Advanced (ILE) Example 4-13

Download from Www.Somanuals.com. All Manuals Search And Download.

#include <miptrnam.h>

#include <qliept.h>

/ᑍ

Prototypes

ᑍ/

typedef void Pgm_OS(void ᑍarg,...);

#pragma linkage(Pgm_OS,OS)

/ᑍ

Structures

ᑍ/

typedef struct {

/ᑍ Error code

ᑍ/

Qus_EC_t ec_fields;

char

exception_data[1ðð];

} error_code_struct;

/ᑍ FUNCTION NAME: RSLVSP_PGM_HDLR

/ᑍ

ᑍ/

/ᑍ FUNCTION :

This function handles all exceptions that

/ᑍ

may occur while resolving to the exit

program.

/ᑍ

/ᑍ INPUT:

Interrupt handler information

NONE

/ᑍ

/ᑍ OUTPUT:

/ᑍ

void RSLVSP_PGM_HDLR(_INTRPT_Hndlr_Parms_T ᑍerrmsg)

{

error_code_struct Error_Code;

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ Set the rsl_ok indicator to not valid.

ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

int ᑍrsl_ok = (int ᑍ)(errmsg→Com_Area);

ᑍrsl_ok = ð;

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ Let message handler know that the program handled the message ᑍ/

/ᑍ and to remove it from the job log.

ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

Error_Code.ec_fields.Bytes_Provided=ð;

QMHCHGEM(&(errmsg→Target),

ð,

(char ᑍ)&errmsg→Msg_Ref_Key,

"ᑍREMOVE ",

"",

ð,

&Error_Code);

}

/ᑍ FUNCTION NAME: Call_Exit_Program

/ᑍ

ᑍ/

4-14 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

/ᑍ FUNCTION :

This function calls the exit programs that

ᑍ/

/ᑍ

were retrieved from the registration facility ᑍ/

/ᑍ

repository.

Information retrieved

NONE

ᑍ/

/ᑍ INPUT:

/ᑍ

/ᑍ OUTPUT:

/ᑍ

void Call_Exit_Program(char ᑍrcv_var)

{

int num_exit_pgms,

char exit_pgm_name[1ð],

exit_pgm_lib[1ð],

info_for_exit_pgm[1ð],

ᑍrcv_ptr;

volatile int rsl_ok;

Pgm_OS ᑍexit_pgm_ptr;

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ Save the number of exit programs returned and set the pointer ᑍ/

/ᑍ to point to the first exit program entry.

ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

rcv_ptr=rcv_var;

num_exit_pgms=((Qus_EXTIð2ðð_t ᑍ)rcv_ptr)→Number_Programs_Returned;

rcv_ptr += ((Qus_EXTIð2ðð_t ᑍ)rcv_ptr)→Offset_Program_Entry;

rsl_ok=1;

for (i=ð; i<num_exit_pgms; i++)

{

memcpy(exit_pgm_name,

((Qus_EXTIð2ðð_Entry_t ᑍ)rcv_ptr)→Program_Name,1ð);

memcpy(exit_pgm_lib,

((Qus_EXTIð2ðð_Entry_t ᑍ)rcv_ptr)→Program_Library,1ð);

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ Resolve to the exit program. If an error occurs on the

/ᑍ resolve operation to the library, the rsl_ok indicator is

/ᑍ set to failed in the RSL_PGM_HDLR exception handler.

/ᑍ The rslvsp MI instruction signals all errors to this

ᑍ/

/ᑍ program; therefore, enable the exception handler to capture ᑍ/

/ᑍ any errors that may occur. ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

#pragma exception_handler (RSLVSP_PGM_HDLR,rsl_ok,ð,_C2_MH_ESCAPE)

exit_pgm_ptr=((Pgm_OS ᑍ)rslvsp(_Program,

exit_pgm_name,

exit_pgm_lib,

_AUTH_POINTER));

#pragma disable_handler

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ If the resolve operation is successful, call the exit

/ᑍ program. If not, move on to the next exit program.

ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

if (rsl_ok)

{

Chapter 4. Common Information across APIs—Advanced (ILE) Example 4-15

Download from Www.Somanuals.com. All Manuals Search And Download.

exit_pgm_ptr(info_for_exit_pgm);

}

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ Set the receiver variable to point to the next exit program ᑍ/

/ᑍ that is returned.

ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

rsl_ok=1;

rcv_ptr=rcv_var +

((Qus_EXTIð2ðð_Entry_t ᑍ)rcv_ptr)→Offset_Next_Entry;

}

/ᑍ

ᑍ/

main

void main()

{

int sel_criteria=ð,

len_rcv_variable=35ðð,

exit_pgm_num=-1;

char continuation_hdl[16],

rcv_variable[35ðð],

ᑍrcv_ptr;

error_code_struct error_code;

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ Retrieve the exit point information first. If the current

/ᑍ number of exit programs is not zero, retrieve the exit

/ᑍ programs. It is not necessary to call for the exit point

/ᑍ information to determine if the exit point has any exit

/ᑍ programs. It is done here for illustration purposes only.

/ᑍ You can make one call to the API for the exit program

/ᑍ information and check the number of exit program entries

ᑍ/

/ᑍ returned field to see if there are any exit programs to call. ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ Initialize the error code to inform the API that all

ᑍ/

/ᑍ exceptions should be returned through the error code parameter.ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

error_code.ec_fields.Bytes_Provided=sizeof(error_code_struct);

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ Blank out the continuation handle to let the API know that thisᑍ/

/ᑍ is a first attempt at the retrieve operation.

ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

memset(continuation_hdl,' ',16);

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ Call the API to retrieve the exit point information.

ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

QusRetrieveExitInformation(continuation_hdl,

&rcv_variable,

len_rcv_variable,

"EXTIð1ðð",

4-16 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

"EXAMPLE_EXIT_POINT ",

"EXMPð1ðð",

exit_pgm_num,

&sel_criteria,

&error_code);

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ If an exception occurs, the API returns the exception in the ᑍ/

/ᑍ error code parameter. The bytes available field is set to

ᑍ/

/ᑍ zero if no exception occurs and nonzero if an exception does ᑍ/

/ᑍ occur.

ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

if (error_code.ec_fields.Bytes_Available != ð)

{

printf("ATTEMPT TO RETRIEVE INFORMATION FAILED WITH EXCEPTION: %.7s",

error_code.ec_fields.Exception_Id);

exit(1);

}

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ If the call to retrieve exit point information is successful, ᑍ/

/ᑍ check to see if there are any exit programs to call.

ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

rcv_ptr=rcv_variable;

rcv_ptr += ((Qus_EXTIð1ðð_t ᑍ)rcv_ptr)->Offset_Exit_Point_Entry;

if (((Qus_EXTIð1ðð_Entry_t ᑍ)rcv_ptr)->Number_Exit_Programs != ð)

{

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ Blank out the continuation handle to let the API know that

/ᑍ this is a first attempt at the retrieve operation.

ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

memset(continuation_hdl,' ',16);

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ Call the API to retrieve the exit program information.

ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

QusRetrieveExitInformation(continuation_hdl,

&rcv_variable,

len_rcv_variable,

"EXTIð2ðð",

"EXAMPLE_EXIT_POINT ",

"EXMPð1ðð",

exit_pgm_num,

&sel_criteria,

&error_code);

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ Verify that the call to the API is successful.

ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

if (error_code.ec_fields.Bytes_Available != ð)

{

printf("ATTEMPT TO RETRIEVE EXIT PROGRAMS FAILED WITH EXCEPTION:\

%.7s", error_code.ec_fields.Exception_Id);

exit(1);

}

Chapter 4. Common Information across APIs—Advanced (ILE) Example 4-17

Download from Www.Somanuals.com. All Manuals Search And Download.

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ If the call is successful, call the exit programs. ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

Call_Exit_Program(rcv_variable);

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ If the continuation handle field in the receiver variable is ᑍ/

/ᑍ not set to blanks, the API has more information to return

/ᑍ than what could fit in the receiver variable.

ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

rcv_ptr=rcv_variable;

while (memcmp(((Qus_EXTIð2ðð_t ᑍ)rcv_ptr)->Continue_Handle,

",16)!=ð)

{

memcpy(continuation_hdl,

((Qus_EXTIð2ðð_t ᑍ)rcv_ptr)→Continue_Handle,16);

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ Call the API to retrieve the exit program information.

ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

QusRetrieveExitInformation(continuation_hdl,

&rcv_variable,

len_rcv_variable,

"EXTIð2ðð",

"EXAMPLE_EXIT_POINT ",

"EXMPð1ðð",

exit_pgm_num,

&sel_criteria,

&error_code);

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ Verify that the call to the API is successful.

ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

if (error_code.ec_fields.Bytes_Available != ð)

{

printf("RETRIEVE EXIT PROGRAMS FAILED WITH EXCEPTION: %.7s",

error_code.ec_fields.Exception_Id);

exit(1);

}

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ If the call is successful, call the exit programs.

ᑍ/

/ᑍ The receiver variable offers enough room for a minimum of ᑍ/

/ᑍ one exit program entry because the receiver variable was

/ᑍ declared as 35ðð bytes. Therefore, this example only

ᑍ/

/ᑍ checks the number of exit programs returned field. If the ᑍ/

/ᑍ receiver variable were not large enough to hold at least

/ᑍ one entry, the bytes available field would need to be

/ᑍ checked as well as the number of exit programs returned

/ᑍ field. If the number of exit programs returned field is

ᑍ/

/ᑍ set to zero and the bytes available field is greater than ᑍ/

/ᑍ the bytes returned field, the API had at least one exit

/ᑍ program entry to return but was unable to because the

/ᑍ receiver variable was too small.

ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

Call_Exit_Program(rcv_variable);

} /ᑍ While continuation handle not set to blanks ᑍ/

} /ᑍ Number of exit programs not equal to zero ᑍ/

4-18 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

} /ᑍ End program ᑍ/

Remove Exit Program and Deregister Exit Point—ILE C Example

The following program removes an exit program from an exit point and deregisters

the exit point from the registration facility.

/ᑍ PROGRAM:

Remove an Exit Program

Deregister an Exit Point

ᑍ/

/ᑍ

/ᑍ LANGUAGE:

/ᑍ

ILE C

/ᑍ DESCRIPTION: This program removes an exit program and

/ᑍ

deregisters an exit point from the registration ᑍ/

facility.

/ᑍ

ᑍ/

/ᑍ

/ᑍ APIs USED:

QusRemoveExitProgram - Remove Exit Program

QusDeregisterExitPoint - Deregister Exit Point

/ᑍ

/ᑍ NOTE: This example uses APIs that are shipped with ᑍEXCLUDE ᑍ/

authority. The user needs ᑍUSE authority to the service ᑍ/

program QUSRGFA1 to use these APIs. ᑍ/

/ᑍ

Includes

ᑍ/

#include <stdio.h>

#include <signal.h>

#include <string.h>

#include <stdlib.h>

#include <qusrgfa1.h>

#include <qusec.h>

#include <qliept.h>

/ᑍ

Structures

ᑍ/

typedef struct {

/ᑍ Error code

ᑍ/

Qus_EC_t ec_fields;

char

exception_data[1ðð];

} error_code_struct;

/ᑍ

ᑍ/

main

int main()

{

int pgm_num=1;

error_code_struct error_code;

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

Chapter 4. Common Information across APIs—Advanced (ILE) Example 4-19

Download from Www.Somanuals.com. All Manuals Search And Download.

/ᑍ Remove an exit program from the exit point and then deregister ᑍ/

/ᑍ the exit point. It is not necessary to remove exit programs ᑍ/

/ᑍ from an exit point before deregistering the exit point. It is ᑍ/

/ᑍ done here only for illustration purposes.

ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ Initialize the error code parameter. To have exceptions

/ᑍ signaled to this program by the API, set the bytes provided

ᑍ/

/ᑍ field of the code to zero. This program has exceptions sent ᑍ/

/ᑍ through the error code parameter; therefore, the bytes ᑍ/

/ᑍ provided field is set to the number of bytes that this program ᑍ/

/ᑍ gives the API for the parameter. ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

error_code.ec_fields.Bytes_Provided=sizeof(error_code_struct);

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ Call the API to remove the exit program.

ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

QusRemoveExitProgram("EXAMPLE_EXIT_POINT ",

"EXMPð1ðð",

pgm_num,

&error_code);

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ If an exception occurs, the API returns the exception in the ᑍ/

/ᑍ error code parameter. The bytes available field is set to

ᑍ/

/ᑍ zero if no exception occurs and nonzero if an exception does ᑍ/

/ᑍ occur.

ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

if (error_code.ec_fields.Bytes_Available != ð)

{

printf("ATTEMPT TO REMOVE EXIT PROGRAM FAILED WITH EXCEPTION: %.7s",

error_code.ec_fields.Exception_Id);

exit(1);

}

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ If the call to remove the exit program is successful,

/ᑍ deregister the exit point.

ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ Call the API to add the exit program.

ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

QusDeregisterExitPoint("EXAMPLE_EXIT_POINT ",

"EXMPð1ðð",

&error_code);

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ If an exception occurs, the API returns the exception in the ᑍ/

/ᑍ error code parameter. The bytes available field is set to

/ᑍ zero if no exception occurs and nonzero if an exception does ᑍ/

/ᑍ occur. ᑍ/

ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

if (error_code.ec_fields.Bytes_Available != ð)

{

printf("ATTEMPT TO DEREGISTER EXIT POINT FAILED WITH EXCEPTION: %.7s",

4-20 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

error_code.ec_fields.Exception_Id);

exit(1);

}

} /ᑍ End program ᑍ/

Chapter 4. Common Information across APIs—Advanced (ILE) Example 4-21

Download from Www.Somanuals.com. All Manuals Search And Download.

4-22 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Chapter 5. List APIs

This chapter contains an overview of list APIs, which are those APIs that return a

list unique to a given API. The chapter discusses the characteristics of a list API

and provides information that you should be aware of when you use list APIs.

The List Objects That Adopt Owner Authority (QSYLOBJP) API is referred to

throughout this chapter. The QSYLOBJP API is included in “List Objects That

Adopt Owner Authority API—Example” on page 5-12 if you need to refer to it as

you read this chapter.

Characteristics of a List API

As discussed in “User Spaces” on page 2-13, list APIs return information to a user

space. List APIs generally have a user space parameter that uses a general (or

common) data structure. You must use the general data structure to get at the

information placed in the user space by the list API.

General Data Structure

This topic describes some of the more important fields that comprise the general

data structure. Figure 5-1 on page 5-2 shows the common fields that list APIs

use. All list APIs have an input parameter section, a header section, and a list data

section.

User Area

The first field in the general data structure is called the user area. This is a 64-byte

field that is not used or changed by the system. Whatever information you place in

this field remains there. For example, you may specify the date last used, include

comments about the list, and so forth.

Size of Generic Header

The size of the generic header does not include the size of the user area. All

sections have a size, which may differ for each API.

Some fields may be added to the generic header from release to release. Because

fields may be added, you may want to check the size of this field. If your applica-

tion works across multiple releases, it is recommended that you check the size of

this field to determine which fields are applicable.

Offset to Input Parameter Section

The offset to input parameter section is an offset to the start of the input parameter

section. The input parameter section may contain a copy of the input parameters

that you pass to the list API. The QSYLOBJP API's input parameter section is

shown on page 5-14.

The input parameter section contains a copy of the continuation handle value that

you passed as the continuation handle parameter to the API. “Other Fields of

Generic Header” on page 5-3 discusses continuation handles further.

 Copyright IBM Corp. 1997

5-1

Download from Www.Somanuals.com. All Manuals Search And Download.

Header

┌────────────────────────────────────┐

┌─────────────────────────┐

+ðð│

│

│ 64─Byte User Area

│

├────────────────────────────────────┤

┌───5│ Input Parameter Section │

+4ð│ Size of Generic Header

│

├────────────────────────────────────┤

│

│ Generic Header

├─────────────────────────┤

│

+6C│ Offset to Input Parameter Section ─┼────┘

│

+7ð│ Input Parameter Section Size

│

+74│ Offset to Header Section───────────┼────────5│

├─────────────────────────┤

│

Header Section

│

+78│ Header Section Size

│

+7C│ Offset to List Data Section────────┼────┐

│

+8ð│ List Data Section Size

│

+84│ Number of List Entries

│

+88│ Size of Each Entry

├─────────────────────────┤

│

+8C│ CCSID of data in the user space

│

+9ð│ Country ID

│

List Data Section

+93│ Language ID

│─────────────────────────┤

│

└───5│ Entry 1

│─────────────────────────┤

│ Entry 2

│

+95│ Subsetted list indicator

│

+Cð│ API entry point name

│─────────────────────────┤

│ Entry 3

│

└────────────────────────────────────┘

│─────────────────────────┤

│ Last Entry

│─────────────────────────┤

│

Figure 5-1. General Data Structure

Offset to Header Section

The header section includes an offset to where the header section starts and the

size of the header section. This section is needed in the event any input parame-

ters have a special value. The fields in the header section tell what the special

value resolved to. For example, the special value *CURRENT for the user name

parameter would resolve to the user profile name for the job that called the API.

This section is also sometimes used for API-specific control information that is not

related to a particular list entry.

The QSYLOBJP API's header section is shown on page 5-14.

Offset to List Data Section

The offset to the list data section is the offset to the start of the format. The spe-

cific format that the API uses is determined by the name you specify for the format

name parameter. The specific format that you use determines what information is

returned in the user space.

The number of list entries field tells how many entries have been returned to you.

The size of each entry field within the list data section tells how large each entry is.

In the list data section, each entry is of the same length for a given list. If the size

5-2 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

of each entry field is ð, the entries have different lengths and the format tells the

length of each entry.

The list data sections for the QSYLOBJP API are shown in the “OBJP0100 Format”

on page 5-14 and the “OBJP0200 Format” on page 5-14. This API has two pos-

sible formats.

For more information about formats and how to extract a field from a format, see

“Format” on page 3-5 and “Extracting a Field from the Format” on page 3-5.

Other Fields of Generic Header

The field called structure’s release and level is part of the generic header. This

field tells the layout of the generic header. For an original program model (OPM)

layout, this value should be 0100. For an Integrated Language Environment (ILE)

model layout, the value should be 0300.

The information status field tells you whether the information in the user space is

complete and accurate, or partial. You need to check the value of this field before

you do anything with the information in the user space (see .1/ on page 5-9). Pos-

sible values for this field follow:

Complete and accurate.

Incomplete. The information you received is not accurate or complete.

Partial but accurate. The information you received is accurate, but the API

had more information to return than the user space could hold.

If the value is P, the API has more information to return than what could fit in the

user space. If you received the value P, you need to process the current informa-

tion in the user space before you get the remaining information. The API returns a

continuation handle usually in the form of a parameter. You can use this continua-

tion handle value to have the remaining information placed in the user space. You

specify the continuation handle value that the API returned as the value of the con-

tinuation handle input parameter on your next call to the API.

The QSYLOBJP API provides a continuation handle in the header section (see .2/

on page 5-14) to return the remaining information to the user space. The user then

passes this value back to the API as an input parameter (see .3/ on page 5-14) so

that the API can locate the remaining information and place it in the user space.

If the API does not have a continuation handle and the information status field

value is P, you must further qualify what you want in the list. In other words, you

must be more specific on the parameter values that you pass to the API. For

example, the QUSLOBJ API asked to get a list of objects; however, all of the

objects on the system would not fit in the user space. To further qualify or limit the

number of objects returned, the user might specify all libraries that start with a spe-

cific letter.

For more information about continuation handles and how to use them, see “Con-

tinuation Handle” on page 2-25.

Chapter 5. List APIs 5-3

Download from Www.Somanuals.com. All Manuals Search And Download.

Processing a List

This is the preferred method for processing lists. To correctly process through a

list, do the following:

1. Use the offset to list data section field (see .5/ on page 5-9)

2. Look at the number of list entries field in the list (see .6/ on page 5-10)

3. Add the size of each entry field to get to the start of the next entry (see .7/ on

page 5-9)

IBM may add fields to the bottom of formats in future releases. If this occurs and

your code uses the size of each entry for a previous release, your list would not

process at the start of each entry.

The example program defines the size of each entry at .4/ on page 5-9. For

another example that shows the correct and incorrect way, see “Defining List Entry

Format Lengths” on page 9-14.

List Object API—OPM RPG Example

The example program prints a report that shows all objects that adopt owner

authority.

Fᑍ

Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Fᑍ

FᑍProgram Name: List objects which adopt owner authority

Fᑍ

FᑍLanguage:

Fᑍ

OPM RPG

FᑍDescription: This program prints a report showing all objects

Fᑍ

that adopt owner authority. The two parameters

passed to the program are the profile to be

checked and the type of objects to be listed.

The parameter values are the same as those

accepted by the QSYLOBJP API.

Fᑍ

FᑍAPIs Used:

QSYLOBJP - List Objects that Adopt Owner Authority

QUSCRTUS - Create User Space

QUSROBJD - Retrieve Object Description

QUSRTVUS - Retrieve From User Space

Fᑍ

Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Fᑍ

FQSYSPRT O F

132

PRINTER

Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

I/COPY QSYSINC/QRPGSRC,QSYLOBJP

I/COPY QSYSINC/QRPGSRC,QUSROBJD

I/COPY QSYSINC/QRPGSRC,QUSGEN

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Iᑍ Error Code Structure

Iᑍ

Iᑍ This shows how the user can define the variable length portion

5-4 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Iᑍ of error code for the exception data.

Iᑍ

Iᑍ/COPY QSYSINC/QRPGSRC,QUSEC

Iᑍᑍᑍ START HEADER FILE SPECIFICATIONS ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Iᑍ

IᑍHeader File Name: QRPGSRC/QUSEC

Iᑍ

IᑍDescriptive Name: Error Code Parameter.

Iᑍ

Iᑍ5763-SS1 (C) Copyright IBM Corp. 1994,1994

IᑍUS Government Users Restricted Rights -

IᑍUse, duplication or disclosure restricted

Iᑍby GSA ADP Schedule Contract with IBM Corp.

Iᑍ

IᑍLicensed Materials-Property of IBM

Iᑍ

IᑍDescription: Include header file for the error code parameter.

Iᑍ

IᑍHeader Files Included: None.

Iᑍ

IᑍMacros List: None.

Iᑍ

IᑍStructure List: Qus_EC_t

Iᑍ

Qus_ERRCð2ðð_t

IᑍFunction Prototype List: None.

Iᑍ

IᑍChange Activity:

Iᑍ

IᑍCFD List:

Iᑍ

IᑍFLAG REASON

LEVEL DATE PGMR

CHANGE DESCRIPTION

Iᑍ---- ------------ ----- ------ --------- ----------------------

Iᑍ$Að= D2862ððð

Iᑍ$B1= D91794ðð

Iᑍ

3D1ð 9312ð1 DPOHLSON: New Include

3D6ð 94ð9ð4 GEORGE : Add Qus_ERRCð2ðð_t

structure.

IᑍEnd CFD List.

Iᑍ

IᑍAdditional notes about the Change Activity

IᑍEnd Change Activity.

Iᑍᑍᑍ END HEADER FILE SPECIFICATIONS ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Iᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

IᑍRecord structure for Error Code Parameter

Iᑍᑍᑍᑍ

ᑍᑍᑍ

IᑍNOTE: The following type definition only defines the fixed

Iᑍ portion of the format. Varying length field Exception

Iᑍ Data will not be defined here.

Iᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

IQUSBN

Iᑍ

Qus EC

B 1 4ðQUSBNB

Iᑍ

Bytes Provided

B 5 8ðQUSBNC

Bytes Available

9 15 QUSBND

Chapter 5. List APIs 5-5

Download from Www.Somanuals.com. All Manuals Search And Download.

Iᑍ

Exception Id

16 16 QUSBNF

Reserved

Iᑍ

Iᑍ Following statement was uncommented and 17 was changed to 1ðð

17 1ðð QUSBNG

Iᑍ

IQUSKY

Iᑍ

Varying length

Qus ERRCð2ðð

B 1 4ðQUSKYB

Key

B 5 8ðQUSKYC

Bytes Provided

B 9 12ðQUSKYD

Bytes Available

13 19 QUSKYF

Exception Id

2ð 2ð QUSKYG

Reserved

B 21 24ðQUSKYH

CCSID

B 25 28ðQUSKYJ

Offset Exc Data

B 29 32ðQUSKYK

Length Exc Data

33 33 QUSKYL

Reserved2

Iᑍ

34 34 QUSKYM

Iᑍ Global Variables

Iᑍ

1 1ð APINAM

11 3ð CONHDL

31 4ð EXTATR

41 41 LSTSTS

42 49 MBRLST

68 75 RJOBDF

76 85 SPCAUT

86 95 SPCDMN

96 96 SPCINT

' 97 116 SPCNAM

117 126 SPCREP

127 176 SPCTXT

177 186 SPCTYP

B 197 2ðððRCVLEN

B 2ð1 2ð4ðSIZENT

B 2ð5 2ð8ðSPCSIZ

B 2ð9 212ðI

I I

'QSYSLOBJP '

I I

'OBJPð2ðð'

'OBJDð1ðð'

'ᑍALL

'ᑍUSER

X'ðð'

'ADOPTS

'ᑍYES

QTEMP

I I

'ᑍUSRSPC '

I I

B 213 216ðNUMENT

B 217 22ððOFFSET

B 221 224ðSTRPOS

2ððð

IRCVVAR

Cᑍ

Cᑍ Beginning of Mainline

Cᑍ

5-6 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Cᑍ Two parameters are being passed into this program.

Cᑍ

ᑍENTRY

PLIST

PARM

USRPRF 1ð

OBJTYP 1ð

Cᑍ

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

EXSR INIT

EXSR PROCES

EXSR DONE

Cᑍ

Cᑍ End of MAINLINE

Cᑍ

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Cᑍ Function:

Cᑍ

getlst

Cᑍ Description: This function calls QSYLOBJP to build a list.

Cᑍ

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Cᑍ

GETLST

BEGSR

MOVEL'OBJPð2ðð'MBRLST

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Cᑍ Call QSYLOBJP API to generate a list. The continuation handle

Cᑍ is set by the caller of this function.

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

CALL 'QSYLOBJP'

PARM

SPCNAM

MBRLST

USRPRF

OBJTYP

CONHDL

QUSBN

User space/lib

Member list

User profile

Object type sc

Continuation ha (.3/

Error Code

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Cᑍ Check for errors on QSYLOBJP.

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

QUSBNC

IFGT ð

MOVEL'QSYLOBJP'APINAM

EXSR APIERR

ENDIF

ENDSR

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Cᑍ Function:

Cᑍ

INIT

Cᑍ Description: This function does all the necessary

Cᑍ

initialization for this program and the

rest is done in the I specs.

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

INIT BEGSR

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Z-ADD1ðð QUSBNB

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Cᑍ Call QUSROBJD to see if the user space was previously created

Cᑍ in QTEMP. If it was, simply reuse it.

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

CALL 'QUSROBJD'

PARM

RCVVAR

Receiver Var

Chapter 5. List APIs 5-7

Download from Www.Somanuals.com. All Manuals Search And Download.

PARM

RCVLEN

RJOBDF

SPCNAM

SPCTYP

QUSBN

Rec Var Length

Format

Qual User Space

User object typ

Error Code

Cᑍ

QUSBNC

IFGT ð

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Cᑍ If a CPF98ð1 error was received, then the user space was not

Cᑍ found.

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

QUSBND

IFEQ 'CPF98ð1'

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Cᑍ Create a user space for the list generated by QSYLOBJP.

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

CALL 'QUSCRTUS'

PARM

SPCNAM

EXTATR

SPCSIZ

SPCINT

SPCAUT

SPCTXT

SPCREP

QUSBN

Qual User Space

Extended Attrib

Size user space

Space Initializ

Public Authorit

User space text

Replace existin

Error Code

PARM

SPCDMN

Domain of us

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Cᑍ Check for errors on QUSCRTUS.

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

QUSBNC

IFGT ð

MOVEL'QUSCRTUS'APINAM

EXSR APIERR

ENDIF

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Cᑍ An error occurred accessing the user space.

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

ELSE

MOVEL'QUSROBJD'APINAM

EXSR APIERR

ENDIF

CPF98ð1 ELSE

BYTAVL > ð

ENDIF

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Cᑍ Set QSYLOBJP (via GETLST) to start a new list.

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

MOVE ᑍBLANKS CONHDL

EXSR GETLST

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Cᑍ Let's retrieve the generic header information from the user

Cᑍ space since OPM RPG does not have pointer support.

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Z-ADD1

Z-ADD192

CALL 'QUSRTVUS'

PARM

STRPOS

RCVLEN

Format 1ðð

SPCNAM

STRPOS

RCVLEN

QUSBP

Qual User Space

Start Position

Length of Data

Receiver Var.

Error Code

PARM

QUSBN

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

5-8 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Cᑍ Check for errors on QUSRTVUS.

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

QUSBNC

IFGT ð

MOVEL'QUSRTVUS'APINAM

EXSR APIERR

ENDIF

ADD QUSBPQ

ENDSR

STRPOS

Offset to List .5/

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Cᑍ Function:

Cᑍ

proc2

Cᑍ Description: This function processes each entry returned by

Cᑍ

QSYLOBJP.

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

PROC2

BEGSR

CALL 'QUSRTVUS'

PARM

SPCNAM

STRPOS

SIZENT

QSYB6

Qual User Space

Start Position

Length of Data

Receiver Var.

Error Code

QUSBN

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Cᑍ Check for errors on QUSRTVUS.

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

QUSBNC

IFGT ð

MOVEL'QUSRTVUS'APINAM

EXSR APIERR

ENDIF

EXCPTPRTENT

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Cᑍ After each entry, increment to the next entry.

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

STRPOS

ADD SIZENT

ENDSR

STRPOS

.7/

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Cᑍ Function:

Cᑍ

proc1

Cᑍ Description: This function processes each entry returned by

Cᑍ

QSYLOBJP.

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

PROC1 BEGSR

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Cᑍ If valid information was returned. .1/

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Z-ADDQUSBPS

IFEQ 'P'

OREQ 'C'

IFGT ð

NUMENT

QUSBPJ

NUMENT

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Cᑍ Get the size of each entry to use later. .4/

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Z-ADDQUSBPT SIZENT

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Cᑍ Increment to the first list entry.

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

ADD QUSBPQ

OFFSET

Chapter 5. List APIs 5-9

Download from Www.Somanuals.com. All Manuals Search And Download.

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Cᑍ Process all of the entries.

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

DO NUMENT

EXSR PROC2

ENDDO

.6/

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Cᑍ If all entries in this user space have been processed, check

Cᑍ if more entries exist than can fit in one user space.

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

QUSBPJ

IFEQ 'P'

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Cᑍ Address the input parameter header.

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

ADD QUSBPL

Z-ADD68

CALL 'QUSRTVUS'

PARM

STRPOS

RCVLEN

Format 1ðð

SPCNAM

STRPOS

RCVLEN

QUSBP

Qual User Space

Start Position

Length of Data

Receiver Var.

Error Code

PARM

QUSBN

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Cᑍ Check for errors on QUSRTVUS.

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

QUSBNC

IFGT ð

MOVEL'QUSRTVUS'APINAM

EXSR APIERR

ENDIF

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Cᑍ If the continuation handle in the input parameter header

Cᑍ is blank, then set the list status to complete.

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

QSYCRJ

IFEQ ᑍBLANKS

MOVE 'C'

ELSE

LSTSTS

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Cᑍ Else, call QSYLOBJP reusing the user space to get more

Cᑍ list entries.

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

MOVELQSYCRJ

EXSR GETLST

Z-ADD1

CONHDL

.2/

STRPOS

RCVLEN

Z-ADD192

CALL 'QUSRTVUS'

PARM

Format 1ðð

SPCNAM

STRPOS

RCVLEN

QUSBP

Qual User Space

Start Position

Length of Data

Receiver Var.

Error Code

PARM

QUSBN

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Cᑍ Check for errors on QUSRTVUS.

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

QUSBNC

IFGT ð

MOVEL'QUSRTVUS'APINAM

EXSR APIERR

ENDIF

MOVE QUSBPJ

LSTSTS

5-10 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

ENDIF

ELSE

HDL = BLANKS

INFOSTS = ð

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

CᑍIf there exists an unexpected status, log an error (not shown)

Cᑍand exit.

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

EXSR DONE

ENDIF

ENDSR

done();

#ENT > ð

USRSPC=P/C

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Cᑍ Function:

Cᑍ

proces

Cᑍ Description: Processes entries until they are complete.

Cᑍ

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

PROCES

BEGSR

MOVELQUSBPJ

DOUEQ'C'

OREQ 'I'

EXSR PROC1

ENDDO

LSTSTS

proces1();

ENDSR

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Cᑍ Function:

Cᑍ

Cᑍ Description: Exits the program.

done

Cᑍ

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

DONE

BEGSR

EXCPTENDLST

SETON

ENDSR

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Cᑍ Function:

Cᑍ

apierr

Cᑍ Description: This function prints the API name, and exception

Cᑍ identifier of an error that occurred.

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

APIERR

APINAM

QUSBND

BEGSR

DSPLY

EXSR DONE

ENDSR

Oᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Oᑍ Function:

Oᑍ

PRTENT

Oᑍ Description: This function prints the information returned in

Oᑍ user space.

Oᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

OQSYSPRT E 1ð6

PRTENT

QSYB6C

QSYB6D

QSYB6F

'Object: '

'Library: '

'Type: '

Chapter 5. List APIs 5-11

Download from Www.Somanuals.com. All Manuals Search And Download.

'Text: '

QSYB6J

Oᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Oᑍ Function:

Oᑍ

ENDLST

Oᑍ Description: This function prints the end of listing print

Oᑍ line and returns to the caller.

Oᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

OQSYSPRT E 1ð6

ENDLST

'ᑍᑍᑍ End of List'

List Objects That Adopt Owner Authority API—Example

Parameters

Required Parameter Group:

Qualified user space name

Format name

User

Object type

Continuation handle

Error code

Input

I/O

Char(20)

Char(8)

Char(10)

Char(20)

Char(*)

The List Objects That Adopt Owner Authority (QSYLOBJP) API puts a list of

objects that adopt an object owner's authority into a user space.

This API provides information similar to that provided by the Display Program Adopt

(DSPPGMADP) command.

Authorities and Locks

User Space Authority

*CHANGE

Authority to Library Containing User Space

*USE

User Profile Authority

*OBJMGT

Required Parameter Group

Qualified user space name

INPUT; CHAR(20)

The name of the existing user space to which the list of objects that adopt a

user's authority is returned. The first 10 characters specify the user space

name, and the second 10 characters specify the library. You can use these

special values for the library name:

*CURLIB The current library is used to locate the user space. If there is no

current library, QGPL (general purpose library) is used.

*LIBL

The library list is used to locate the user space.

5-12 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Format name

INPUT; CHAR(8)

The name of the format that returns information on the objects that adopt a

user's authority.

You can specify these formats:

OBJP0100

Each entry contains the object name, library, type, and object

in use indicator. For a detailed description of this format, see

“OBJP0100 Format” on page 5-14.

OBJP0200

Each entry contains the same information as format

OBJP0100 plus the object attribute and descriptive text. For a

detailed description of this format, see “OBJP0200 Format” on

page 5-14.

User name

INPUT; CHAR(10)

The user name for which the list of objects that adopt the user's authority is

returned. You can specify the following special value:

*CURRENT

The list of objects that adopt the authority of the user currently

running is returned. If *CURRENT is used, the name of the

current user is returned in the list header section of the user

space.

Object type

INPUT; CHAR(10)

The type of object for which the list of objects that adopt the user's authority is

returned. You can specify only the following special values:

*ALL

*PGM

*SQLPKG

*SRVPGM

Return entries for all object types that adopt authority.

Return entries for programs that adopt authority.

Return entries for SQL packages that adopt authority.

Return entries for service programs that adopt authority.

Continuation handle

INPUT; CHAR(20)

The handle used to continue from a previous call to this API that resulted in

partially complete information. You can determine if a previous call resulted in

partially complete information by checking the Information Status variable in the

generic user space header following the API call.

If the API is not attempting to continue from a previous call, this parameter

must be set to blanks. Otherwise, a valid continuation value must be supplied.

The value may be obtained from the list header section of the user space used

in the previous call. When continuing, the first entry in the returned list is the

entry that immediately follows the last entry returned in the previous call.

Error code

I/O; CHAR(*)

The structure in which to return error information. For the format of the struc-

ture, see "Error Code Parameter" in Chapter 2 of the System API Reference.

Chapter 5. List APIs 5-13

Download from Www.Somanuals.com. All Manuals Search And Download.

User Space Variables

The following tables describe the order and format of the data returned in the user

space. For detailed descriptions of the fields in the tables, see “Field Descriptions”

on page 5-15.

Input Parameter Section

Offset

Dec

Hex

Type

Field

CHAR(10)

CHAR(8)

CHAR(10)

CHAR(20)

User space name specified

User space library name specified

Format name

User name specified

Object type

Continuation handle .3/

Header Section

Offset

Dec

Hex

Type

Field

CHAR(10)

CHAR(20)

User name

Continuation handle .2/

OBJP0100 Format

Offset

Dec

Hex

Type

Field

CHAR(10)

CHAR(1)

Object name

Library name

Object type

Object in use

OBJP0200 Format

Offset

Dec

Hex

Type

Field

CHAR(10)

CHAR(1)

CHAR(10)

CHAR(50)

Object name

Library name

Object type

Object in use

Attribute

Text description

5-14 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Field Descriptions

Attribute. The object attribute.

Continuation handle (header section). A continuation point for the API. This

value is set based on the contents of the Information Status variable in the generic

header for the user space. The following situations can occur:

Ÿ Information status–C. The information returned in the user space is valid and

complete. No continuation is necessary and the continuation handle is set to

blanks.

Ÿ Information status–P. The information returned in the user space is valid but

incomplete. The user may call the API again, starting where the last call left

off. The continuation handle contains a value which may be supplied as an

input parameter in later calls.

Ÿ Information status–I. The information returned in the user space is not valid

and incomplete. The content of the continuation handle is unpredictable.

Continuation handle (input section). Used to continue from a previous call to

this API which resulted in partially complete information.

Format name. The name of the format used to return information on the objects

that adopt authority.

Library name. The name of the library containing the user space or object.

Object name. The name of the object that adopts the user's authority.

Object in use. Whether the object is in use when the API tries to access it. If the

object is in use, the API is not able to determine if the object adopts the user's

authority. If the object is in use, this field is Y. If not, this field is N.

Object type.

Ÿ Input Section: The type of object for which the list of objects adopting the user's

authority is returned.

Ÿ List Section: The type of object which adopts the user's authority.

Text description. The text description of the object.

User name. The name of the owner of the object.

User name specified. The name of the user for which the list of objects that

adopt the user's authority is returned.

User space library name specified. The name of the library that contains the

user space.

User space name specified. The name of the user space to which the list of

objects that adopt the users authority is returned.

Chapter 5. List APIs 5-15

Download from Www.Somanuals.com. All Manuals Search And Download.

Error Messages

CPF22FD E Continuation handle not valid for API &1.

CPF2204 E User profile &1 not found.

CPF2213 E Not able to allocate user profile &1.

CPF2217 E Not authorized to user profile &1.

CPF3CF1 E Error code parameter not valid.

CPF3C21 E Format name &1 is not valid.

CPF3C31 E Object type &1 is not valid.

CPF811A E User space &4 in &9 damaged.

CPF9801 E Object &2 in library &3 not found.

CPF9802 E Not authorized to object &2 in &3.

CPF9803 E Cannot allocate object &2 in library &3.

CPF9807 E One or more libraries in library list deleted.

CPF9808 E Cannot allocate one or more libraries on library list.

CPF9810 E Library &1 not found.

CPF9820 E Not authorized to use library &1.

CPF9830 E Cannot assign library &1.

CPF9872 E Program or service program &1 in library &2 ended. Reason code &3.

5-16 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Chapter 6. Original Program Model (OPM) and Integrated

Language Environment (ILE) Differences

This chapter contains an overview of how Original Program Model (OPM) APIs and

Integrated Language Environment (ILE) APIs differ from each other. The ILE APIs

include the UNIX-type APIs and the ILE CEE APIs among others.

You must have the ILE language compiler on your system to develop applications

that use any ILE APIs.

Contrasting OPM and ILE APIs

API Name

The maximum number of characters that an OPM API name can contain is 8,

whereas the maximum number in an ILE API name is 30. ILE API names are

case-sensitive.

Parameters

There are several types of parameters: required, optional, and omitted. The

AS/400 OPM and ILE APIs show the parameters in a Parameter box, whereas the

AS/400 UNIX-type APIs show them in a Syntax box. The ILE APIs include the

service program name at the bottom of the box.

Optional Parameters: Some of the OPM APIs have optional parameters. The

optional parameters form a group, and you must either include or exclude the entire

group.

OPM APIs do not have omitted parameters.

Omitted Parameters: The ILE APIs may have parameters that can be omitted.

When these parameters are omitted, you must pass a null pointer.

ILE APIs do not have optional parameters.

The required and optional parameters are discussed in more detail in “Required

Parameter Group” on page 3-3 and “Optional Parameter Group” on page 3-5.

Error Conditions

The error code parameter is common to most of the OPM APIs, and it is used to

return error codes and exception data to the application. The errors that are

returned for a given API are in the form of an error message and include the

7-character message identifier.

Some APIs use means other than the error code parameter for reporting error con-

ditions, as follows:

Ÿ The ILE CEE APIs use feedback codes and conditions.

Ÿ The UNIX-type APIs use errnos and return values.

Ÿ The national language data conversion APIs use errnos and return values.

 Copyright IBM Corp. 1997

6-1

Download from Www.Somanuals.com. All Manuals Search And Download.

Ÿ The Dynamic Screen Manager (DSM) supports returned values in addition to

the error code parameter.

The errnos are provided as include files in the QSYSINC library.

Pointers

Due to the greater availability of pointer support in ILE languages, there is a much

greater use of pointers in ILE APIs. The use of pointers can provide a performance

advantage.

Following are examples of an OPM API and an ILE API that do similar functions

(log or report software errors). The ILE API example makes use of pointers,

whereas the OPM API does not. Both programs log software errors by using first-

failure data capture (FFDC).

Logging Software Error (OPM API without Pointers)—ILE C

Example

This program calls the Log Software Error (QPDLOGER) API to perform FFDC.

The program does not make use of pointers. The OPM program physically moves

the data that is pointed to (shown at .1/ on page 6-6), which slows down perfor-

mance.

/ᑍ

ᑍ/

/ᑍProgram Name: FFDCPGM1

/ᑍ

/ᑍProgram Language: ILE C

/ᑍ

/ᑍDescription: This program illustrates how to use APIs to log

/ᑍ

software errors using FFDC.

/ᑍHeader Files Included: except

/ᑍ

stdio

/ᑍ

string

qmhchgem

qpdloger

qusec

/ᑍ

/ᑍAPIs Used:

/ᑍ

QPDLOGER

/ᑍ

System Includes

ᑍ/

#include <except.h>

#include <stdio.h>

#include <string.h>

/ᑍ from QCLE/H

ᑍ/

/ᑍ Miscellaneous Includes ᑍ/

#include <qmhchgem.h>

#include <qpdloger.h>

#include <qusec.h>

/ᑍ from QSYSINC/H

ᑍ/

6-2 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

/ᑍ

Structures

ᑍ/

typedef struct {

void ᑍparm1;

void ᑍparm2;

char ᑍpgm_name;

int

pgm_name_size;

} ffdc_info_t;

/ᑍ

Prototypes

ᑍ/

void UNEXPECTED_HDLR(_INTRPT_Hndlr_Parms_T ᑍ);

/ᑍ FUNCTION NAME: main

/ᑍ

ᑍ/

/ᑍ FUNCTION:

Generates exception and then passes control

/ᑍ

to exception handler.

Two character strings.

NONE

/ᑍ

/ᑍ INPUT:

/ᑍ

/ᑍ OUTPUT:

/ᑍ

/ᑍ EXCEPTIONS:

CPFxxxx - All unexpected CPF exceptions

MCHxxxx - All unexpected MCH exceptions

/ᑍ

void main(int argc, char ᑍargv[])

{

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ NOTE: argv will contain the parameters passed in to this

ᑍ/

/ᑍ

function. In this case, two parameters are passed

in.

/ᑍ The argv parameter contains the parameters that were passed as ᑍ/

/ᑍ character arrays. argv[ð] contains the program name, and the ᑍ/

/ᑍ parameter(s) starts with argv[1].

ᑍ/

char ᑍnulptr;

/ᑍ Pointer used to generate error ᑍ/

/ᑍ Program name ᑍ/

char pgm_name[3ð];

volatile ffdc_info_t ffdc_info; /ᑍ FFDC info for unexpected error ᑍ/

/ᑍ Set up FFDC information for unexpected error.

ᑍ/

ffdc_info.parm1 = argv[1];

ffdc_info.parm2 = argv[2];

ffdc_info.pgm_name = pgm_name;

memcpy(pgm_name, argv[ð], strlen(argv[ð]));

ffdc_info.pgm_name_size = strlen(argv[ð]);

/ᑍ Enable the exception handler, and pass ffdc_info into the

/ᑍ exception handler via the communications area so that data

ᑍ/

Chapter 6. Original Program Model (OPM) and Integrated Language Environment (ILE) Differences 6-3

Download from Www.Somanuals.com. All Manuals Search And Download.

/ᑍ can be used for FFDC.

ᑍ/

#pragma exception_handler (UNEXPECTED_HDLR, ffdc_info, ð, _C2_MH_ESCAPE)

/ᑍ Set the pointer to null, then try to increment. This will

/ᑍ generate an MCH36ð1 error that will be trapped by the

/ᑍ unexpected handler.

ᑍ/

nulptr = NULL;

nulptr++;

#pragma disable_handler

} /ᑍ main ᑍ/

/ᑍ FUNCTION NAME: UNEXPECTED_HDLR

/ᑍ

ᑍ/

/ᑍ FUNCTION:

Handle unexpected exception. This exception

ᑍ/

/ᑍ

handler is used to log the software error via ᑍ/

/ᑍ

FFDC.

ᑍ/

/ᑍ

/ᑍ INPUT:

Interrupt handler information

NONE

/ᑍ

/ᑍ OUTPUT:

/ᑍ

/ᑍ EXCEPTIONS:

CPFxxxx - All unexpected CPF exceptions

MCHxxxx - All unexpected MCH exceptions

/ᑍ

void UNEXPECTED_HDLR(_INTRPT_Hndlr_Parms_T ᑍerrmsg)

{

typedef struct {

char obj_name[3ð];

char obj_lib[3ð];

char obj_type[1ð];

} obj_info_t;

typedef struct {

int

data_offset;

data_length;

} data_info_t;

char

int

pgm_suspected[1ð],

msg_id[12],

msg_key[4],

print_job_log,

data[2ᑍ(sizeof(char ᑍ))],

ᑍdata_item,

ile_mod_name[11];

point_of_failure,

num_items,

num_objs;

data_info_t

obj_info_t

data_info[2];

obj_info[1];

6-4 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

ffdc_info_t ᑍffdc_info;

Qus_EC_t ErrorCode;

ErrorCode.Bytes_Provided = ð;

/ᑍ Getting pointer in local storage to the Communications Area.

ᑍ/

ffdc_info = (ffdc_info_t ᑍ)(errmsg->Com_Area);

/ᑍ Need to notify message handler that we will handle the error. ᑍ/

/ᑍ Leave the message in the job log, just mark it handled.

ᑍ/

QMHCHGEM(&(errmsg->Target),

ð,

/ᑍ Invocation pointer

/ᑍ Call stack counter

ᑍ/

(char ᑍ)&errmsg->Msg_Ref_Key,/ᑍ Message key

"ᑍHANDLE ",

/ᑍ Modification option

/ᑍ Reply text

/ᑍ Reply text length

/ᑍ Error code

"",

ð,

&ErrorCode);

/ᑍ Set up the suspected program. ᑍ/

memcpy(pgm_suspected, "ᑍPRV ", 1ð);

/ᑍ Set up the detection identifier. ᑍ/

memset(msg_id, ' ', 12);

memcpy(msg_id, errmsg->Msg_Id, 7);

/ᑍ Set up the message key.

ᑍ/

memcpy(msg_key, (char ᑍ)&errmsg->Msg_Ref_Key, 4);

/ᑍ Set up point of failure. Since this example program is small ᑍ/

/ᑍ and we know where the error occurred, we will just put a dummy ᑍ/

/ᑍ value in. However, this can be very useful information in

/ᑍ larger programs.

ᑍ/

point_of_failure = 1ðð;

/ᑍ Set up to print the job log.

ᑍ/

print_job_log = 'Y';

/ᑍ Set up data items.

ᑍ/

data_item = data;

/ᑍ Put in first parameter.

ᑍ/

Chapter 6. Original Program Model (OPM) and Integrated Language Environment (ILE) Differences 6-5

Download from Www.Somanuals.com. All Manuals Search And Download.

memcpy(data_item, (char ᑍ)ffdc_info->parm1, sizeof(char ᑍ)); .1/

/ᑍ Add in the second parameter.

ᑍ/

data_item += sizeof(char ᑍ);

memcpy(data_item, (char ᑍ)ffdc_info->parm2, sizeof(char ᑍ));

/ᑍ Reset the data item pointer.

ᑍ/

data_item -= sizeof(char ᑍ);

/ᑍ Set up data item offset/length information.

ᑍ/

data_info[ð].data_offset = ð;

data_info[ð].data_length = sizeof(char ᑍ);

data_info[1].data_offset = sizeof(char ᑍ);

data_info[1].data_length = sizeof(char ᑍ);

/ᑍ Set up the number of data items. In this case we only have one.ᑍ/

num_items = 2;

/ᑍ Set up the object name array. In this case, we have no objects ᑍ/

/ᑍ to dump, but we will put dummy values in to illustrate.

ᑍ/

memcpy(obj_info[ð].obj_name, "OBJUSRSPC

memcpy(obj_info[ð].obj_lib, "QTEMP

memcpy(obj_info[ð].obj_type, "ᑍUSRSPC ", 1ð);

", 3ð);

/ᑍ Set the number of objects in name array. ᑍ/

num_objs = ð;

/ᑍ Set up the ILE module name.

ᑍ/

memcpy(ile_mod_name, ffdc_info->pgm_name, ffdc_info->pgm_name_size);

/ᑍ Call QPDLOGER to perform FFDC.

ᑍ/

ErrorCode.Bytes_Provided = sizeof(ErrorCode);

QPDLOGER(pgm_suspected,

msg_id,

msg_key,

point_of_failure,

&print_job_log,

data_item,

data_info,

num_items,

obj_info,

6-6 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

num_objs,

&ErrorCode,

ile_mod_name);

} /ᑍ UNEXPECTED_HDLR ᑍ/

Reporting Software Error (ILE API with Pointers)—ILE C Example

This program calls the Report Software Error (QpdReportSoftwareError) API to

perform FFDC, and uses pointers. The ILE program sets a pointer (shown at .2/

on page 6-10) to point to the same location as in the OPM program (shown at .1/

on page 6-6).

/ᑍ

ᑍ/

/ᑍProgram Name: FFDCPGM2

/ᑍ

/ᑍProgram Language: ILE C

/ᑍ

/ᑍDescription: This program illustrates how to use APIs to log

/ᑍ

software errors using FFDC.

/ᑍHeader Files Included: except

/ᑍ

stdio

/ᑍ

string

qmhchgem

qpdsrvpg

qusec

/ᑍ

/ᑍAPIs Used:

/ᑍ

QpdReportSoftwareError

/ᑍ

System Includes

ᑍ/

#include <except.h>

#include <stdio.h>

#include <string.h>

/ᑍ from QCLE/H

ᑍ/

/ᑍ Miscellaneous Includes ᑍ/

#include <qmhchgem.h>

#include <qpdsrvpg.h>

#include <qusec.h>

/ᑍ from QSYSINC/H

ᑍ/

/ᑍ Definitions used for developing key information for FFDC. ᑍ/

#define CHARACTER 'C'

#define MAX_KEYS 3

#define MESSAGE "MSG"

#define MESSAGE_LEN 7

#define MSG_SYMPTOM_LEN 3

/ᑍ

Structures

ᑍ/

Chapter 6. Original Program Model (OPM) and Integrated Language Environment (ILE) Differences 6-7

Download from Www.Somanuals.com. All Manuals Search And Download.

typedef struct {

void ᑍparm1;

void ᑍparm2;

char ᑍpgm_name;

int

pgm_name_size;

} ffdc_info_t;

/ᑍ

Prototypes

ᑍ/

void UNEXPECTED_HDLR(_INTRPT_Hndlr_Parms_T ᑍ);

/ᑍ FUNCTION NAME: main

/ᑍ

ᑍ/

/ᑍ FUNCTION:

Generates exception and then passes control

/ᑍ

to exception handler.

Two character strings.

NONE

/ᑍ

/ᑍ INPUT:

/ᑍ

/ᑍ OUTPUT:

/ᑍ

/ᑍ EXCEPTIONS:

CPFxxxx - All unexpected CPF exceptions

MCHxxxx - All unexpected MCH exceptions

/ᑍ

void main(int argc, char ᑍargv[])

{

/ᑍ NOTE: argv will contain the parameters passed in to this

ᑍ/

/ᑍ

function. In this case, two parameters are passed

in.

/ᑍ The argv parameter contains the parameters that were passed as ᑍ/

/ᑍ character arrays. argv[ð] contains the program name, and the ᑍ/

/ᑍ parameter(s) starts with argv[1].

ᑍ/

char ᑍnulptr;

/ᑍ Pointer used to generate error ᑍ/

/ᑍ Program name ᑍ/

char pgm_name[3ð];

volatile ffdc_info_t ffdc_info; /ᑍ FFDC info for unexpected error ᑍ/

/ᑍ Set up FFDC information for unexpected error.

ᑍ/

ffdc_info.parm1 = argv[1];

ffdc_info.parm2 = argv[2];

ffdc_info.pgm_name = pgm_name;

memcpy(pgm_name, argv[ð], strlen(argv[ð]));

ffdc_info.pgm_name_size = strlen(argv[ð]);

/ᑍ Enable the exception handler, and pass ffdc_info into the

/ᑍ exception handler via the communications area so that data

/ᑍ can be used for FFDC.

ᑍ/

6-8 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

#pragma exception_handler (UNEXPECTED_HDLR, ffdc_info, ð, _C2_MH_ESCAPE)

/ᑍ Set the pointer to null, then try to increment. This will

/ᑍ generate an MCH36ð1 error that will be trapped by the

/ᑍ unexpected handler.

ᑍ/

nulptr = NULL;

nulptr++;

#pragma disable_handler

} /ᑍ main ᑍ/

/ᑍ FUNCTION NAME: UNEXPECTED_HDLR

/ᑍ

ᑍ/

/ᑍ FUNCTION:

Handle unexpected exception. This exception

ᑍ/

/ᑍ

handler is used to log the software error via ᑍ/

/ᑍ

FFDC.

ᑍ/

/ᑍ

/ᑍ INPUT:

Interrupt handler information

NONE

/ᑍ

/ᑍ OUTPUT:

/ᑍ

/ᑍ EXCEPTIONS:

CPFxxxx - All unexpected CPF exceptions

MCHxxxx - All unexpected MCH exceptions

/ᑍ

void UNEXPECTED_HDLR(_INTRPT_Hndlr_Parms_T ᑍerrmsg)

{

int

i = ð,

MsgLen = ð,

number_of_keys = ð;

pgm_name[3ð],

char

context_name[3ð],

lib_name[5],

symptom_msg_data[MESSAGE_LEN],

symptom_msg_keyword[MSG_SYMPTOM_LEN];

ᑍffdc_info;

ffdc_info_t

Qpd_Data_t

data_key,

data_key2;

ffdc_keys[MAX_KEYS];

Qpd_Suspected_Module_t module_key;

Qpd_Key_Pointer_t

Qpd_Symptom_t

Qus_EC_t

symptom_msg_key;

ErrorCode;

ErrorCode.Bytes_Provided = ð;

/ᑍ Getting pointer in local storage to the Communications Area.

ᑍ/

ffdc_info = (ffdc_info_t ᑍ)(errmsg->Com_Area);

/ᑍ Need to notify message handler that we will handle the error. ᑍ/

Chapter 6. Original Program Model (OPM) and Integrated Language Environment (ILE) Differences 6-9

Download from Www.Somanuals.com. All Manuals Search And Download.

/ᑍ Leave the message in the job log, just mark it handled.

ᑍ/

QMHCHGEM(&(errmsg->Target),

ð,

/ᑍ Invocation pointer

/ᑍ Call stack counter

ᑍ/

(char ᑍ)&errmsg->Msg_Ref_Key,/ᑍ Message key

"ᑍHANDLE ",

/ᑍ Modification option

/ᑍ Reply text

/ᑍ Reply text length

/ᑍ Error code

"",

ð,

&ErrorCode);

/ᑍ Initialize module suspected key for FFDC. ᑍ/

ffdc_keys[number_of_keys++].Suspected_Module = &module_key;

module_key.Key = Qpd_Suspected_Module;

module_key.Module_Name_Length = ffdc_info->pgm_name_size;

module_key.Library_Name_Length = 7;

module_key.Module_Name = pgm_name;

memcpy(pgm_name, ffdc_info->pgm_name, ffdc_info->pgm_name_size);

module_key.Library_Name = lib_name;

memcpy(lib_name, "TESTLIB", 7);

/ᑍ Initialize symptom keys for FFDC.

ᑍ/

ffdc_keys[number_of_keys++].Symptom = &symptom_msg_key;

symptom_msg_key.Key = Qpd_Symptom;

symptom_msg_key.Keyword_Length = MSG_SYMPTOM_LEN;

symptom_msg_key.Data_Length = MESSAGE_LEN;

symptom_msg_key.Data_Type = CHARACTER;

memcpy(symptom_msg_keyword, MESSAGE, MSG_SYMPTOM_LEN);

symptom_msg_key.Keyword = symptom_msg_keyword;

memcpy(symptom_msg_data, errmsg->Msg_Id, MESSAGE_LEN);

symptom_msg_key.Data = symptom_msg_data;

/ᑍ Parameter 1 information

ᑍ/

ffdc_keys[number_of_keys++].Data = &data_key;

data_key.Key = Qpd_Data;

data_key.Data_Length = sizeof(char ᑍ);

data_key.Data_Id = 1;

data_key.Data = ffdc_info->parm1;

.2/

/ᑍ Parameter 2 information ᑍ/

ffdc_keys[number_of_keys++].Data = &data_key2;

data_key2.Key = Qpd_Data;

data_key2.Data_Length = sizeof(char ᑍ);

data_key2.Data_Id = 1;

data_key2.Data = ffdc_info->parm2;

/ᑍ Call QpdReportSoftwareError to perform FFDC.

ᑍ/

ErrorCode.Bytes_Provided = sizeof(ErrorCode);

QpdReportSoftwareError(ffdc_keys,

6-10 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

&number_of_keys,

&ErrorCode);

} /ᑍ UNEXPECTED_HDLR ᑍ/

Chapter 6. Original Program Model (OPM) and Integrated Language Environment (ILE) Differences 6-11

Download from Www.Somanuals.com. All Manuals Search And Download.

6-12 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Chapter 7. Machine Interface Programming

This chapter is for programmers interested in creating machine interface (MI) pro-

grams. While some MI instructions are discussed within the context of how to

develop MI programs, this chapter makes no attempt to review the full range of MI

instructions. The goal of this chapter is to provide a sufficient base of knowledge

so that you can begin to use the MI language. After reading this chapter, you

should be able to develop, create, run, and debug an AS/400 MI program. When

reading this chapter, you will need access to the System API Reference,

SC41-5801, and the Machine Interface Functional Reference, SC41-5810, because

these two books are referred to extensively.

Machine Interface Instructions—Introduction

Programs and procedures are the two basic units of execution on the AS/400. Pro-

grams come in two flavors: the original program model (OPM) and the Integrated

Language Environment (ILE). MI programs can be created only for the OPM envi-

ronment. If you require ILE support in the development of your applications, use

ILE C and its built-in MI support.

In the OPM environment, a program is comprised of two basic components: the

object definition table (ODT) and an instruction stream. In the case of MI pro-

grams, the program is created using the Create Program (QPRCRTPG) API. This

API is documented in the System API Reference.

The ODT is the means for defining all objects¹that are referred to by the MI

instruction stream. An ODT definition of an object does not actually allocate

storage for the object. It does, however, define when and how much storage is to

be allocated and also the attributes of the storage (for example, the data type of the

object). The ODT is built from the declare (DCL) statements found in the source

used to create a program. Because DCL statements are actually instructions to the

QPRCRTPG API and not MI instructions, they are defined in the QPRCRTPG API.

The types of objects that can be declared are:

Scalar

Pointer

Machine space pointer

Operand list

Instruction definition list

Exception description

Space

Constant

The instruction stream defines the set of operations to be performed by the

program. The instruction stream is built from the MI instructions found in the

source used to create a program. The various MI instructions that you can use are

defined in the Machine Interface Functional Reference.

The term objects in this chapter refers to program data elements and not OS/400 object types such as a *FILE, *PGM, *USRPRF,

and so on.

 Copyright IBM Corp. 1997

7-1

Download from Www.Somanuals.com. All Manuals Search And Download.

Within the source used to create a program, there is a type of statement called a

directive. Directive statements are defined in the System API Reference in the

section discussing the QPRCRTPG API and are used to do the following:

Ÿ Control the formatting of the output listing, such as the title, page ejection, and

so on.

Ÿ Define entry points within the program for external and internal calls.

Ÿ Define breakpoints within the program to associate a breakpoint name to a par-

ticular MI instruction.

Ÿ Specify the end of the program source.

The program end (PEND) directive must be the last statement in the source, and it

functions as a return external (RTX) MI instruction if logically processed as part of

the instruction stream.

Noncomment source statements (declares, instructions, and directives) are always

ended by a semicolon (;). Comments always begin with a slash and asterisk (/ᑍ)

and end with an asterisk and slash (ᑍ/).

Writing an MI Program—Example

This topic shows how to write a simple MI program that receives two packed-

decimal parameters and returns the larger value through a third parameter. This

program demonstrates how to do the following:

Ÿ Define an external entry point

Ÿ Define and access parameters

Ÿ Use conditional branching

Ÿ Assign a value to a scalar object

Ÿ End the program

Note: When reviewing this source code, unless noted otherwise, you can find all

directive and DCL statements in the System API Reference; all other state-

ments are in the Machine Interface Functional Reference. While this

chapter attempts to discuss the intent of a statement, refer to the applicable

reference book for specific details.

Setting the Entry Point

First the program, MI01 in this example, needs an ENTRY directive statement to

designate its external entry point. The following directive declares an unnamed (the

*) external (the EXT) entry point, which is called with a parameter list corresponding

to PARM_LIST (defined later in the source code):

ENTRY ᑍ (PARM_LIST) EXT;

Setting the Declare Statements

OS/400 programs typically pass parameters by reference as part of the high-level

language (HLL) calling convention. Because OS/400 programs pass by reference

(that is, address and not value), the program also needs to define three space

pointers (how storage is referenced) to represent the three parameters being

passed. This is accomplished by the following directives:

DCL

SPCPTR

ARG1@

PARM;

ARG2@

RESULT@

7-2 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

To associate these three space pointers with the parameters being passed to the

program, the following operand list (OL) is declared:

DCL

PARM_LIST

(ARG1@,

ARG2@,

RESULT@)

PARM

/ᑍ Name of OL is PARM_LIST ᑍ/

/ᑍ The first parameter

/ᑍ The second parameter

/ᑍ The third parameter

ᑍ/

EXT; /ᑍ External parameter list ᑍ/

The names ARG1@, ARG2@, RESULT@, and PARM_LIST are chosen by you

and are not mandated by the AS/400 system. You can choose any valid name for

any object data element. For a definition of what constitutes a valid name, see

“Name” in the “Program Syntax” topic of the Create Program (QPRCRTPG) API in

the System API Reference.

Now that the program has established addressability (the space pointers) to the

three parameters, the program needs to declare how to map (or view) the storage

addressed. The following declarations define the storage addressed (the BAS

argument) by the three space pointer parameters as being packed-decimal (PKD)

scalar data objects (DD) with 15 digits, 5 digits being to the right of the decimal

point:

DCL

ARG1

PKD(15,5)

BAS(ARG1@);

BAS(ARG2@);

BAS(RESULT@);

ARG2

RESULT

The names ARG1, ARG2, and RESULT are chosen arbitrarily, but, for ease of

reading, are similar to the basing space pointers ARG1@, ARG2@, and

RESULT@. The declarations of packed 15,5 are used for consistency with CL.

The declared type and size could be of any other valid type and size. The true

requirement is that the calling program and the MI program agree on the type and

size.

Starting the Instruction Stream

With all the needed declarations now done, the instruction stream definition, where

the program will compare the numeric values (CMPNV instruction) of parameters

one and two, is started:

CMPNV(B)

ARG1,ARG2 / LO(ITS2);

The program then branches (the (B) extender to CMPNV) to label ITS2 if ARG1 is

less than ARG2 (the /LO branch target).

Note: MI instructions such as CMPNV are defined in the Machine Interface Func-

tional Reference. Pervasive instruction extenders such as branch (B) and

target keywords (LO, HI, EQ, and so on) are defined in the System API

Reference under “Instruction Statement,” which is a subheading in the

“Program Syntax” topic of the Create Program (QPRCRTPG) API.

If ARG1 is not low (LO) when compared to ARG2, the next MI instruction in the

source stream is run. When the next MI instruction is run, it copies the numeric

value (CPYNV instruction) of ARG1 to RESULT and, following that, branches to

label RETURN:

CPYNV

RESULT,ARG1;

RETURN;

If ARG2 was greater than ARG1, the CPYNV instruction at label ITS2 is run, setting

RESULT to the value of ARG2:

Chapter 7. Machine Interface Programming 7-3

Download from Www.Somanuals.com. All Manuals Search And Download.

ITS2: CPYNV

The program has now finished processing and ends:

RETURN: RTX ᑍ;

RESULT,ARG2;

PEND;

The previous return external (RTX) instruction is not needed because it is implied

by the PEND directive. The RTX instruction is included to add clarity to the

program flow.

MI01 Program—Complete Code Example

Put all together, the program looks like this:

/ᑍ

ᑍ/

Program Name: MIð1

Programming Language: MI

Description: Return the larger of two packed arguments.

Header Files Included: None

ENTRY ᑍ (PARM_LIST) EXT;

DCL

SPCPTR

ARG1@

ARG2@

PARM;

RESULT@

PARM_LIST

(ARG1@,

ARG2@,

RESULT@)

PARM

ARG1

ARG2

RESULT

EXT;

DCL

PKD(15,5)

BAS(ARG1@);

BAS(ARG2@);

BAS(RESULT@);

CMPNV(B)

CPYNV

ARG1,ARG2 / LO(ITS2);

RESULT,ARG1;

RETURN;

ITS2: CPYNV

RETURN: RTX

PEND;

RESULT,ARG2;

ᑍ;

Compiling a Program

If you enter the source into a source physical file, you can now compile the source

and create an MI program. To create the program, use the Create Program

(QPRCRTPG) API documented in the System API Reference.

Note: The QPRCRTPG API assumes that the source statements presented to it

are in code page 37. See the introduction to the Machine Interface Func-

tional Reference for the specific code points required to build MI programs.

7-4 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Using CLCRTPG to Create an MI Program

Assume that the source is in a member named MI01 in the source file MISRC,

which is created with a default record length (RCDLEN) of 92. The following

CLCRTPG CL program can be used to create an MI program called MI01. (An MI

program to call the Create Program (QPRCRTPG) API is developed in “Creating an

MI Version of CLCRTPG” on page 7-11.)

Note: All non-MI source examples are provided in CL, because CL is the one lan-

guage (other than REXX) that is standard on all AS/400 systems. Other

high-level languages (HLLs) could be used in place of the CL programs

(and in many cases would have been easier).

The following program reads a source file member into a program variable

(&MIPGMSRC) and then does a CALL to the QPRCRTPG API. This program has

many limitations (the major limitation is a program variable-size limit of 2000 bytes

for the source), but provides for a reasonably simple MI program creation scenario:

/ᑍ

ᑍ/

Program Name: CLCRTPG

Programming Language: CL

Description: Create an MI program using the QPRCRTPG API.

Header Files Included: None

PGM

DCLF

DCL

PARM(&SRCMBR)

FILE(MISRC)

VAR(&SRCMBR) TYPE(ᑍCHAR) LEN(1ð)

VAR(&MIPGMSRC) TYPE(ᑍCHAR) LEN(2ððð)

VAR(&MIPGMSRCSZ) TYPE(ᑍCHAR) LEN(4)

VAR(&OFFSET) TYPE(ᑍDEC) LEN(5 ð) VALUE(1)

VAR(&PGMNAM) TYPE(ᑍCHAR) LEN(2ð) +

VALUE('

ᑍCURLIB ')

DCL

VAR(&PGMTXT) TYPE(ᑍCHAR) LEN(5ð) +

VALUE('Compare two packed arguments and +

return larger')

DCL

VAR(&PGMSRCF) TYPE(ᑍCHAR) LEN(2ð) +

VALUE('ᑍNONE')

DCL

VAR(&PGMSRCM) TYPE(ᑍCHAR) LEN(1ð) VALUE(' ')

VAR(&PGMSRCCHG) TYPE(ᑍCHAR) LEN(13) VALUE(' ')

VAR(&PRTFNAM) TYPE(ᑍCHAR) LEN(2ð) +

VALUE('QSYSPRT ᑍLIBL

DCL

RCVF

VAR(&PRTSTRPAG) TYPE(ᑍCHAR) LEN(4) +

VALUE(X'ððððððð1')

VAR(&PGMPUBAUT) TYPE(ᑍCHAR) LEN(1ð) +

VALUE('ᑍALL

VAR(&PGMOPTS) TYPE(ᑍCHAR) LEN(22) +

VALUE('ᑍLIST ᑍREPLACE ')

VAR(&NUMOPTS) TYPE(ᑍCHAR) LEN(4) +

VALUE(X'ððððððð2')

LOOP:

Chapter 7. Machine Interface Programming 7-5

Download from Www.Somanuals.com. All Manuals Search And Download.

MONMSG

CHGVAR

GOTO

CHGVAR

CALL

MSGID(CPFð864) EXEC(GOTO CMDLBL(CRTPGM))

VAR(%SST(&MIPGMSRC &OFFSET 8ð)) VALUE(&SRCDTA)

VAR(&OFFSET) VALUE(&OFFSET + 8ð)

CMDLBL(LOOP)

VAR(%SST(&PGMNAM 1 1ð)) VALUE(&SRCMBR)

VAR(%BIN(&MIPGMSRCSZ)) VALUE(&OFFSET)

PGM(QSYS/QPRCRTPG) PARM(&MIPGMSRC +

&MIPGMSRCSZ &PGMNAM &PGMTXT &PGMSRCF +

&PGMSRCM &PGMSRCCHG &PRTFNAM &PRTSTRPAG +

&PGMPUBAUT &PGMOPTS &NUMOPTS)

CRTPGM:

ENDPGM

Creating the MI Example Program

After creating the CL program (assumed to be called CLCRTPG), the following

statements create the previous MI program MI01:

DLTOVR MISRC

OVRDBF MISRC MBR(MIð1)

CALL CLCRTPG MIð1

Note: If the creation of MI01 fails, you should closely compare your source to that

shown in this chapter. In general, consider the QPRCRTPG error mes-

sages that refer to “probable compiler error” as referring to your input

source and not that the QPRCRTPG API itself is in error. (QPRCRTPG

assumes its input is probably from a high-level language (HLL) compiler.)

If the error message is CPF6399 (Identifier not declared), you can get an

object definition table (ODT) listing by adding *XREF to the option template

parameter (variable &PGMOPTS in the CLCRTPG program) when calling

the QPRCRTPG API. Add *XREF to the existing *LIST and *REPLACE

options, and change the number of option template entries parameter (vari-

able &NUMOPTS) to 3.

Testing MI01

In this topic, assume that MI01 was successfully created. Test the MI01 program

with the following CL01 CL program:

/ᑍ

ᑍ/

Program Name: CLð1

Programming Language: CL

Description: Test the MI program MIð1.

Header Files Included: None

PGM

DCL

PARM(&ARG1 &ARG2)

VAR(&ARG1) TYPE(ᑍDEC) LEN(15 5)

VAR(&ARG2) TYPE(ᑍDEC) LEN(15 5)

VAR(&RESULT) TYPE(ᑍDEC) LEN(15 5)

VAR(&MSG) TYPE(ᑍCHAR) LEN(2ð)

VAR(&USR) TYPE(ᑍCHAR) LEN(1ð)

7-6 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

RTVJOBA

CALL

CHGVAR

SNDMSG

ENDPGM

USER(&USR)

PGM(MIð1) PARM(&ARG1 &ARG2 &RESULT)

VAR(&MSG) VALUE(&RESULT)

MSG(&MSG) TOUSR(&USR)

The following statement calls the CL01 program:

CALL CLð1 (-5 6)

This test should cause a message to be sent to your user message queue with the

following value:

ððððððððððððð6.ððððð

Debugging the MI Program

The MI program (MI01) that you created is a standard *PGM object on the AS/400

system. As you would expect, you can call MI01 from other high-level languages.

You can delete MI01 with the Delete Program (DLTPGM) command, save and

restore MI01 using the standard save (SAV) and restore (RST) commands, and so

on.

You can also debug it using the standard debugger on the AS/400 system. To

debug it, you need to look at the listing produced by the QPRCRTPG API to deter-

mine the MI instruction number. Then use that number with the Add Breakpoint

(ADDBKP) CL command. For example, when creating MI01 in the previous exer-

cise, the following listing was generated by QPRCRTPG:

5763SS1 V3R1Mð 94ð9ð9

Generated Output

ð8/ð8/94 ð9:46:36 Page

SEQ.1/INST Offset

ðððð1

Generated Code

ᑍ... ... 1 ... ... 2 ... ... 3 ... ... 4 ... ... 5 ... ... 6 ... ... 7 ... ... 8

ENTRY ᑍ (PARM_LIST) EXT

;

ðððð2

DCL SPCPTR ARG1@ PARM

ðððð3

DCL SPCPTR ARG2@ PARM

ðððð4

DCL SPCPTR RESULT@ PARM

ðððð5

DCL OL PARM_LIST (ARG1@, ARG2@, RESULT@) PARM EXT

DCL DD ARG1 PKD(15,5) BAS(ARG1@)

DCL DD ARG2 PKD(15,5) BAS(ARG2@)

DCL DD RESULT PKD(15,5) BAS(RESULT@)

CMPNV(B) ARG1,ARG2 / LO(ITS2)

ðððð6

ðððð7

ðððð8

ðððð9 ððð1 ððððð4 3C46 2ððð ððð6 ððð7

ððð9

ððð1ð ððð2 ðððððE 1ð42 ððð8 ððð6

ððð11 ððð3 ðððð14 1ð11 ðððA

ððð12 ððð4 ðððð18 3ð42 ððð8 ððð7

ððð13 ððð5 ðððð1E 22A1 ðððð .2/

ððð14 ððð6 ðððð22 ð26ð

CPYNV RESULT,ARG1

B RETURN

CPYNV RESULT,ARG2

;

ITS2:

;

RETURN: RTX ᑍ

PEND

;

5763SS1 V3R1Mð 94ð9ð9

Generated Output

Semantics and ODT Syntax Diagnostics

Generated Output

ð8/ð8/94 ð9:46:36 Page

MSGID

ODT

ODT Name

5763SS1 V3R1Mð 94ð9ð9

MSGID MI Instruction Stream Semantic Diagnostics

ð8/ð8/94 ð9:46:36 Page

Setting Breakpoints in the MI Program

To view the value of RESULT at label RETURN, you first determine that RETURN

corresponds to MI instruction (.1/) 0005 (.2/) and enter the following CL com-

mands:

STRDBG PGM(MIð1)

ADDBKP STMT('/ððð5') PGMVAR((RESULT ()))

CALL CLð1 (-5

The following display is shown:

Chapter 7. Machine Interface Programming 7-7

Download from Www.Somanuals.com. All Manuals Search And Download.

Display Breakpoint

Statement/Instruction . . . . . . . . . : /ððð5

Program . . . . . . . . . . . . . . . . : MIð1

Recursion level . . . . . . . . . . . . : 1

Start position . . . . . . . . . . . . : 1

Format . . . . . . . . . . . . . . . . : ᑍCHAR

Length . . . . . . . . . . . . . . . . : ᑍDCL

Variable . . . . . . . . . . . . . . . : RESULT

Type . . . . . . . . . . . . . . . . :

Length . . . . . . . . . . . . . . . :

6.ððððð'

PACKED

15 5

Breakpoints also can be set with a directive statement. Given that the MI01

program is able to be debugged and a break directive was not used, the purpose

for which you use the directive may not be obvious. As mentioned in “Creating the

MI Example Program” on page 7-6, many expected users of the QPRCRTPG API

are compilers of HLLs. The break (BRK) directive allows users of the QPRCRTPG

API to associate an HLL statement identifier with a generated MI instruction. For

example, assume that MI01 was developed to be an implementation of a fictional

HLL language statement such as:

RESULT = MAX(ARG1, ARG2)

This assigns the MAX (defined as the largest argument) of ARG1 or ARG2 to

RESULT. Also assume that an HLL programmer had written a program called

HLLEXAMPLE with the following statements:

ðððð1 RESULT = MAX(ARG1, ARG2)

ðððð2 EXIT

By using break (BRK) directives, the QPRCRTPG user or compiler could associate

the HLL statements with the generated MI instructions in the following way:

/ᑍ

ᑍ/

Program Name: MIð1

Programming Language: MI

Description: Demonstrate how to associate HLL statement

identifiers with MI instructions using BRK

directives.

Header Files Included: None

ENTRY ᑍ (PARM_LIST) EXT;

DCL

SPCPTR

ARG1@

ARG2@

PARM;

RESULT@

PARM_LIST

(ARG1@,

ARG2@,

RESULT@)

PARM

EXT;

PKD(15,5)

DCL

ARG1

ARG2

BAS(ARG1@);

BAS(ARG2@);

7-8 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

DCL

BRK "ðððð1";

CMPNV(B)

CPYNV

ITS2: CPYNV

BRK "ðððð2";

RETURN: RTX

PEND;

RESULT

PKD(15,5)

BAS(RESULT@);

ARG1,ARG2 / LO(ITS2);

RESULT,ARG1;

RETURN;

RESULT,ARG2;

ᑍ;

This allows the HLL programmer to use the following to debug the HLL program by

using the statement identifiers of the HLL:

STRDBG PGM(HLLEXAMPLE)

ADDBKP STMT(ðððð2) PGMVAR((RESULT ()))

The following display shows that the HLL statement 00002 has been equated with

MI instruction 0005 due to the use of BRK directives:

Display Breakpoint

Statement/Instruction . . . . . . . . . : ðððð2 /ððð5

Program . . . . . . . . . . . . . . . . : HLLEXAMPLE

Recursion level . . . . . . . . . . . . : 1

Start position . . . . . . . . . . . . : 1

Format . . . . . . . . . . . . . . . . : ᑍCHAR

Length . . . . . . . . . . . . . . . . : ᑍDCL

Variable . . . . . . . . . . . . . . . : RESULT

Type . . . . . . . . . . . . . . . . :

Length . . . . . . . . . . . . . . . :

6.ððððð'

PACKED

15 5

Handling Exceptions in the MI Program

As coded, the MI01 program works fine when it is passed packed decimal parame-

ters. But when the MI01 program is passed other data types, such as in CALL

CL01 (abc 6), exceptions occur. To handle these exceptions, additional state-

ments could be added to MI01 so that:

Ÿ A 1-character return code parameter returns a status where ð indicates no

error and 1 indicates an error occurred.

Ÿ An exception description is defined to handle MCH1202 decimal data errors.

Add the following statements to MI01:

1. Declare a fourth space parameter to receive the return code parameter:

DCL

SPCPTR

RC@

PARM;

2. Update the operand list directive for PARM_LIST:

DCL

PARM_LIST

(ARG1@,

ARG2@,

RESULT@,

RC@)

/ᑍ the new parameter ᑍ/

PARM

EXT;

3. Declare the storage addressed by RC@ as a 1-byte character data element:

DCL DD RC CHAR(1) BAS(RC@);

Chapter 7. Machine Interface Programming 7-9

Download from Www.Somanuals.com. All Manuals Search And Download.

4. Declare an exception handler for MCH1202. With this exception description, all

occurrences of MCH1202 will cause an immediate (IMD) branch to label

M1202.

DCL

EXCM

DATAERROR EXCID(H'ðCð2') BP (M12ð2) IMD;

Note: The EXCID is the hexadecimal representation of the message identifier

string 1202 where 12 = X'0C' and 02 = X'02'. While most MCH

errors follow this relationship of message ID string to hexadecimal

EXCID, you should always refer to the Machine Interface Functional

Reference to determine what specific exception IDs may be signaled by

a given MI statement.

5. Because label M1202 is being used to indicate an error, set the return code to

1 by using copy bytes left-justified and then end:

M12ð2: CPYBLA

RC,'1';

ᑍ;

RTX

PEND;

A more complete example of how to handle exceptions is provided in “Handling

Exceptions in the MICRTPG2 Program” on page 7-27.

6. Because the non-M1202 path indicates that no error was detected, update the

normal return path:

RETURN: CPYBLA

RC,'ð';

7. Because M1202 was appended to the end of the MI01 source, remove the ori-

ginal MI01 PEND directive.

The following is an updated view of the MI01 program:

/ᑍ

ᑍ/

Program Name: MIð1

Programming Language: MI

Description: Enhanced version of MI program MIð1 that

demonstrates enabling an exception monitor.

Header Files Included: None

ENTRY ᑍ (PARM_LIST) EXT;

DCL

SPCPTR

ARG1@

ARG2@

RESULT@

RC@

PARM;

PARM_LIST

(ARG1@,

ARG2@,

RESULT@,

RC@)

PARM

EXT;

DCL

ARG1

PKD(15,5)

BAS(ARG1@);

BAS(ARG2@);

BAS(RESULT@);

ARG2

RESULT

7-10 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

DCL

CHAR(1)

BAS(RC@);

EXCM

CMPNV(B)

CPYNV

DATAERROR EXCID(H'ðCð2') BP (M12ð2) IMD;

ARG1,ARG2 / LO(ITS2);

RESULT,ARG1;

RETURN;

RESULT,ARG2;

RC,'ð';

ᑍ;

ITS2: CPYNV

RETURN: CPYBLA

RTX

M12ð2: CPYBLA

RTX

RC,'1';

ᑍ;

PEND;

The following example updates CL01 to support the new return code parameter:

/ᑍ

ᑍ/

Program Name: CLð1

Programming Language: CL

Description: Enhanced version of CL program CLð1 that

demonstrates the use of enhanced MIð1.

Header Files Included: None

PGM

PARM(&ARG1 &ARG2)

DCL

VAR(&ARG1) TYPE(ᑍDEC) LEN(15 5)

VAR(&ARG2) TYPE(ᑍDEC) LEN(15 5)

VAR(&RESULT) TYPE(ᑍDEC) LEN(15 5)

VAR(&RC) TYPE(ᑍCHAR) LEN(1)

VAR(&MSG) TYPE(ᑍCHAR) LEN(2ð)

VAR(&USR) TYPE(ᑍCHAR) LEN(1ð)

USER(&USR)

DCL

RTVJOBA

CALL

PGM(MIð1) PARM(&ARG1 &ARG2 &RESULT &RC)

COND(&RC = 'ð') +

THEN(CHGVAR

VAR(&MSG) VALUE(&RESULT))

ELSE +

CHGVAR

SNDMSG

ENDPGM

VAR(&MSG) VALUE('ERROR FOUND')

MSG(&MSG) TOUSR(&USR)

After recompiling the MI01 program and the CL01 program, CALL CL01 (abc 6)

now results in the following message (not the previous MCH1202):

ERROR FOUND

Creating an MI Version of CLCRTPG

The topics previous to this discuss how to create MI01 to be a reasonably complete

program. This topic discusses how to create an MI version of the CLCRTPG

program that can be used to create MI programs. This program is called

MICRTPG.

Chapter 7. Machine Interface Programming 7-11

Download from Www.Somanuals.com. All Manuals Search And Download.

Because the CLCRTPG program is used to create the initial version of MICRTPG

and CLCRTPG can support only as many as 2000 bytes of source in the

&MIPGMSRC variable, MICRTPG is initially defined with a minimal set of function.

Significant additions to the MICRTPG program can be made after it is used as a

building block in the creation of MI programs.

In the initial design (see the program flow on page 7-13), there are four programs.

The first program is a CL program (CL03) that does the following:

Ÿ Creates a user space (*USRSPC) object of 64KB size to hold the MI source.

Ÿ Overrides the MISRC file to the appropriate source physical file and

member.1/.

Ÿ Calls a second CL program (CL04), which loads the selected MISRC member

into the user space (*USRSPC).2/.

Ÿ Calls an MI program (MICRTPG).3/. The MICRTPG program calls CL

program CL05.4/ and passes addressability to the *USRSPC, where CL05

then calls the QPRCRTPG API.5/.

The MICRTPG program demonstrates how to do the following:

Ÿ Define a structure

Ÿ Initialize declared storage

Ÿ Use two different approaches to resolve a system pointer to an external object

Ÿ Assign a space pointer to address a user space

Ÿ Call a program and pass three parameters

The overall program flow appears as follows:

CL Pgm CL03

MISRC

CL Pgm

CL04

USRSPC

MI Pgm MICRTPG

CL Pgm

CL05

API

QPRCRTPG

RV3W216-2

Figure 7-1. Program Flow for Creating the MICRTPG Program

7-12 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Source for the CL03 Program

The source for CL03 follows:

/ᑍ

ᑍ/

Program Name: CLð3

Programming Language: CL

Description: Main driver program for initial version of

MI program MICRTPG. This program creates a

ᑍUSRSPC, calls CLð4 to load MI source from

a ᑍSRC physical file into the ᑍUSRSPC, and

then calls MICRTPG to create MI programs.

Header Files Included: None

PGM

DCL

PARM(&FILE &MBR)

VAR(&FILE) TYPE(ᑍCHAR) LEN(1ð)

VAR(&MBR) TYPE(ᑍCHAR) LEN(1ð)

VAR(&SPCNAM) TYPE(ᑍCHAR) LEN(2ð) +

VALUE('

ᑍCURLIB ')

DCL

VAR(&SPCEXTATR) TYPE(ᑍCHAR) LEN(1ð) VALUE(' ')

VAR(&SPCSIZ) TYPE(ᑍCHAR) LEN(4) +

VALUE(X'ððð1ðððð')

DCL

VAR(&SPCINTVAL) TYPE(ᑍCHAR) LEN(1) VALUE(X'ðð')

VAR(&SPCSPCAUT) TYPE(ᑍCHAR) LEN(1ð) +

VALUE('ᑍALL')

DCL

VAR(&SPCTXTDSC) TYPE(ᑍCHAR) LEN(5ð) VALUE(' ')

VAR(&SPCRPLOPT) TYPE(ᑍCHAR) LEN(1ð) +

VALUE('ᑍYES')

VAR(&ERRCOD) TYPE(ᑍCHAR) LEN(4) +

VALUE(X'ðððððððð')

DCL

VAR(&SPCDMN) TYPE(ᑍCHAR) LEN(1ð) VALUE('ᑍUSER')

VAR(&BINOFFSET) TYPE(ᑍCHAR) LEN(4) +

VALUE(X'ððððððð1')

CHGVAR

CALL

VAR(%SST(&SPCNAM 1 1ð)) VALUE(&MBR)

PGM(QUSCRTUS) PARM(&SPCNAM &SPCEXTATR +

&SPCSIZ &SPCINTVAL &SPCSPCAUT &SPCTXTDSC +

&SPCRPLOPT &ERRCOD &SPCDMN)

OVRDBF

CALL

FILE(MISRC) TOFILE(&FILE) MBR(&MBR)

PGM(CLð4) PARM(&MBR &BINOFFSET)

PGM(MICRTPG) PARM(&MBR &BINOFFSET)

CALL

ENDPGM

Source for the CL04 Program

The source for CL04 follows:

/ᑍ

ᑍ/

Program Name: CLð4

Programming Language: CL

Chapter 7. Machine Interface Programming 7-13

Download from Www.Somanuals.com. All Manuals Search And Download.

/ᑍ

ᑍ/

Description: Load a source physical file member into the

ᑍUSRSPC named &MBR.

Header Files Included: None

PGM

DCLF

DCL

PARM(&MBR &BINOFFSET)

FILE(MISRC)

VAR(&MBR) TYPE(ᑍCHAR) LEN(1ð)

VAR(&BINOFFSET) TYPE(ᑍCHAR) LEN(4)

VAR(&OFFSET) TYPE(ᑍDEC) LEN(8 ð) VALUE(1)

VAR(&LENGTH) TYPE(ᑍCHAR) LEN(4) +

VALUE(X'ðððððð5ð')

DCL

VAR(&SPCNAM) TYPE(ᑍCHAR) LEN(2ð) +

VALUE('

ᑍLIBL

CHGVAR

RCVF

VAR(%SST(&SPCNAM 1 1ð)) VALUE(&MBR)

LOOP:

DONE:

MONMSG

CALL

MSGID(CPFð864) EXEC(GOTO CMDLBL(DONE))

PGM(QUSCHGUS) PARM(&SPCNAM &BINOFFSET +

&LENGTH &SRCDTA 'ð')

CHGVAR

GOTO

VAR(&OFFSET) VALUE(&OFFSET + 8ð)

VAR(%BIN(&BINOFFSET)) VALUE(&OFFSET)

CMDLBL(LOOP)

ENDPGM

Source for the CL05 Program

The source for CL05 follows:

/ᑍ

ᑍ/

Program Name: CLð5

Programming Language: CL

Description: Create an MI program using the QPRCRTPG API.

Header Files Included: None

PGM

DCL

PARM(&SRCMBR &MIPGMSRC &MIPGMSRCSZ)

VAR(&SRCMBR) TYPE(ᑍCHAR) LEN(1ð)

VAR(&MIPGMSRC) TYPE(ᑍCHAR) LEN(1)

VAR(&MIPGMSRCSZ) TYPE(ᑍCHAR) LEN(4)

VAR(&PGMNAM) TYPE(ᑍCHAR) LEN(2ð) +

VALUE('

ᑍCURLIB ')

DCL

VAR(&PGMTXT) TYPE(ᑍCHAR) LEN(5ð) +

VALUE(' ')

VAR(&PGMSRCF) TYPE(ᑍCHAR) LEN(2ð) +

VALUE('ᑍNONE')

DCL

VAR(&PGMSRCM) TYPE(ᑍCHAR) LEN(1ð) VALUE(' ')

VAR(&PGMSRCCHG) TYPE(ᑍCHAR) LEN(13) VALUE(' ')

7-14 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

DCL

VAR(&PRTFNAM) TYPE(ᑍCHAR) LEN(2ð) +

VALUE('QSYSPRT ᑍLIBL ')

VAR(&PRTSTRPAG) TYPE(ᑍCHAR) LEN(4) +

VALUE(X'ððððððð1')

VAR(&PGMPUBAUT) TYPE(ᑍCHAR) LEN(1ð) +

VALUE('ᑍALL

VAR(&PGMOPTS) TYPE(ᑍCHAR) LEN(22) +

VALUE('ᑍLIST ᑍREPLACE ')

VAR(&NUMOPTS) TYPE(ᑍCHAR) LEN(4) +

VALUE(X'ððððððð2')

CHGVAR

CALL

VAR(%SST(&PGMNAM 1 1ð)) VALUE(&SRCMBR)

PGM(QSYS/QPRCRTPG) PARM(&MIPGMSRC +

&MIPGMSRCSZ &PGMNAM &PGMTXT &PGMSRCF +

&PGMSRCM &PGMSRCCHG &PRTFNAM &PRTSTRPAG +

&PGMPUBAUT &PGMOPTS &NUMOPTS)

ENDPGM

Source for the MICRTPG Program

The source for MICRTPG follows:

/ᑍ

ᑍ/

Program Name: MICRTPG

Programming Language: MI

Description: Initial version of MI program to create

additional MI programs using the QPRCRTPG API. ᑍ/

ᑍ/

Header Files Included: None

ENTRY ᑍ (PARM_LIST) EXT;

DCL SPCPTR MBR@ PARM;

DCL SPCPTR BINOFFSET@ PARM;

DCL OL PARM_LIST (MBR@, BINOFFSET@) PARM EXT;

DCL DD MBR CHAR(1ð) BAS(MBR@);

DCL DD BINOFFSET BIN(4) BAS(BINOFFSET@);

DCL DD RSLVOBJ CHAR(34);

DCL DD RSLVTYPE CHAR(1) DEF(RSLVOBJ) POS(1) INIT(X'19');

DCL DD RSLVSUBTYPE CHAR(1) DEF(RSLVOBJ) POS(2) INIT(X'34');

DCL DD RSLVNAME CHAR(3ð) DEF(RSLVOBJ) POS(3);

DCL DD RSLVAUTH CHAR(2) DEF(RSLVOBJ) POS(33) INIT(X'ðððð');

DCL SYSPTR USRSPCOBJ;

DCL SPCPTR USRSPC;

DCL SYSPTR CLð5 INIT("CLð5", TYPE(PGM));

DCL OL CLð5OL (MBR@, USRSPC, BINOFFSET@) ARG;

CPYBLAP RSLVNAME, MBR, ' ';

RSLVSP USRSPCOBJ, RSLVOBJ, ᑍ, ᑍ;

SETSPPFP USRSPC, USRSPCOBJ;

CALLX CLð5, CLð5OL, ᑍ;

RTX ᑍ;

PEND;

Chapter 7. Machine Interface Programming 7-15

Download from Www.Somanuals.com. All Manuals Search And Download.

Understanding the MICRTPG Program (by Sections of Code)

You will recognize some of these statements from the MI01 example, but others

are new.

The following statements, which you have seen, for example, in “MI01

Program—Complete Code Example,” define the entry point to this program and the

parameters being passed on the call:

ENTRY ᑍ (PARM_LIST) EXT;

DCL SPCPTR MBR@ PARM;

DCL SPCPTR BINOFFSET@ PARM;

DCL OL PARM_LIST (MBR@, BINOFFSET@) PARM EXT;

DCL DD MBR CHAR(1ð) BAS(MBR@);

DCL DD BINOFFSET BIN(4) BAS(BINOFFSET@);

Declaring the Structure

The following, however, are new statements:

DCL DD RSLVOBJ CHAR(34);

DCL DD RSLVTYPE CHAR(1) DEF(RSLVOBJ) POS(1) INIT(X'19');

DCL DD RSLVSUBTYPE CHAR(1) DEF(RSLVOBJ) POS(2) INIT(X'34');

DCL DD RSLVNAME CHAR(3ð) DEF(RSLVOBJ) POS(3);

DCL DD RSLVAUTH CHAR(2) DEF(RSLVOBJ) POS(33) INIT(X'ðððð');

These statements declare a structure named RSLVOBJ that comprises four subele-

ments defined within it. The subelements specify their position relative to the start

of the structure RSLVOBJ. In the cases of the RSLVTYPE, RSLVSUBTYPE, and

RSLVAUTH data elements, they initialize the associated storage.

The RSLVOBJ structure is used later in the program as an input to the resolve

system pointer (RSLVSP) MI instruction. The RSLVSP instruction resolves (estab-

lishes addressability) to a user space (*USRSPC) (the X'1934' object type and

subtype) named RSLVNAME (assigned from the source member name (MBR) data

element). This user space is the one created in “Source for the CL03 Program” on

page 7-13. If you are interested in the details of this structure, see the Machine

Interface Functional Reference under RSLVSP. For other valid object types and

subtypes, see AS/400 Licensed Internal Code Diagnostic Aids – Volume 1,

LY44-5900, and AS/400 Licensed Internal Code Diagnostic Aids – Volume 2,

LY44-5901.

Note: In the declare (DCL) statement of RSLVOBJ, the leading blanks used to

indent the subelements (for example, RSLVTYPE and RSLVSUBTYPE) are

strictly to enhance the readability of the source. They are not a requirement

of the QPRCRTPG API. In general, you can use strings of blanks of any

length in the source of a program. Blanks, one or more, are simply used as

delimiters in identifying tokens. The major exception is the INIT argument

of a DCL statement where the number of blanks is important. For example,

the previous declare statement could have been written as follows and other

than readability, nothing would have been lost:

DCL DD RSLVOBJ CHAR(34); DCL DD RSLVTYPE CHAR(1)

DEF(RSLVOBJ) POS(1) INIT(X'19');

DEF(RSLVOBJ)

DCL DD RSLVSUBTYPE CHAR(1)

POS(2)

INIT(X'34'); DCL DD RSLVNAME CHAR(3ð) DEF(RSLVOBJ) POS(3); DCL

DD RSLVAUTH CHAR(2) DEF(RSLVOBJ) POS(33) INIT(X'ðððð');

7-16 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Declaring Pointers

The next statements declare a system pointer named USRSPCOBJ and a space

pointer named USRSPC. USRSPCOBJ contains the address of the *USRSPC

object after the execution of the RSLVSP instruction later in the instruction stream.

USRSPC addresses the first byte of the *USRSPC:

DCL SYSPTR USRSPCOBJ;

DCL SPCPTR USRSPC;

Defining an External Call

Because this program also uses the call external (CALLX) instruction to call the CL

program CL05, define a system pointer for CL05:

DCL SYSPTR CLð5 INIT("CLð5", TYPE(PGM));

The preceding statement causes the QPRCRTPG API to initialize the system

pointer CL05 to the name of the PGM CL05. The CL05 pointer is not set to the

address of the CL05 object—this happens the first time the CL05 pointer is referred

to in the instruction stream. If you review the System API Reference for this

declare statement, notice that the context (CTX) argument uses the default. Using

the context default (better known as library to most programmers) is equivalent to

specifying *LIBL. *LIBL is referred to as the process name resolution list in the

Machine Interface Functional Reference.

Because this program calls the CL05 program (CALLX CL05) with parameters, it

now defines an operand list CL05OL, which specifies the arguments to be passed

on the CALLX:

DCL OL CLð5OL (MBR@, USRSPC, BINOFFSET@) ARG;

When you get to the instruction stream of MICRTPG, copy the passed parameter

MBR to the data structure element RSLVNAME. As RSLVNAME is defined as

CHAR(30) and MBR is CHAR(10), the program uses the copy bytes left-justified

with pad (CPYBLAP) instruction to set the rightmost 20 bytes of RSLVNAME to the

value of the third argument (in this case, blanks):

CPYBLAP RSLVNAME, MBR, ' ';

Having established the *USRSPC name, use the RSLVSP instruction to get

addressability to the object itself:

RSLVSP USRSPCOBJ, RSLVOBJ, ᑍ, ᑍ;

Note: Similar to how the *USRSPC name was resolved, RSLVSP could be used

with a type of X'02' and a subtype of X'01' to resolve a system pointer to

the CL05 *PGM object. The two different approaches were used to demon-

strate the different styles (RSLVSP is clearly more flexible) and also to stay

within the 2000-byte limit of the program source size imposed by the

CLCRTPG program.

Then set the USRSPC space pointer to the first byte of the *USRSPC:

SETSPPFP USRSPC, USRSPCOBJ;

Chapter 7. Machine Interface Programming 7-17

Download from Www.Somanuals.com. All Manuals Search And Download.

Calling the CL05 Program

Now the program will call the CL05 program (CALLX CL05) and pass the address

of the *USRSPC as a parameter (along with the member name, program name,

and the size of the source stream). When you call CL05 with the operand list

CL05OL, CL05 passes the actual space pointer USRSPC. CL05 does not pass a

space pointer that refers to the space pointer USRSPC (as opposed to how MBR@

and BINOFFSET@ are passed to refer to MBR and BINOFFSET, respectively).

This has the effect of having the CL05 program treat the *USRSPC storage as the

parameter:

CALLX CLð5, CLð5OL, ᑍ;

Finally, as the program comes to an end, this is the return external instruction and

pend directive for the initial version of MICRTPG:

RTX ᑍ;

PEND;

Creating the MICRTPG Program

To create MICRTPG, use the following CL commands:

DLTOVR MISRC

OVRDBF MISRC MBR(MICRTPG)

CALL CLCRTPG MICRTPG

Assuming a successful creation, the CLCRTPG program is not used again because

of the MI base with which to work (for example, MICRTPG is used as a boot-strap

for further compiler enhancement).

Enhanced Version of the MICRTPG Program

Now that the MICRTPG program provides addressability (through the *USRSPC as

a parameter to the CL05 program) for as many as 64KB of input source, a new

version of MICRTPG (named MICRTPG2) will incorporate the functions of the CL03

program and the CL05 program. A modified form of CL04 (renamed to CL06) is

used in these examples to read the MISRC source physical file because MI instruc-

tion support for database access is beyond the scope of this chapter.

The MICRTPG2 program demonstrates how to do the following:

Ÿ Receive a variable number of parameters

Ÿ Use static and automatic storage

Ÿ Create a space object

Ÿ Perform arithmetic operations

Understanding the MICRTPG2 Program (by Sections of Code)

Writing the program code for MICRTPG2:

1. Define the entry point and associated parameters:

ENTRY ᑍ (PARM_LIST) EXT;

DCL SPCPTR FIL@ PARM;

DCL SPCPTR MBR@ PARM;

DCL OL PARM_LIST (MBR@, FIL@) PARM EXT MIN(1);

DCL DD FIL CHAR(1ð) BAS(FIL@);

DCL DD MBR CHAR(1ð) BAS(MBR@);

DCL DD NUM_PARMS BIN(4);

7-18 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

2. Have MICRTPG2 create an automatically extendable space (it can automat-

ically increase to as many as 16MB in size) using the Create Space (CRTS)

instruction. Because the CRTS instruction requires a definition template, you

need to define it (see the Machine Interface Functional Reference for details).

The following template creates a space (type and subtype equal to X'19EF')

that is defined through the OBJCRTOPT data element.1/. The space is

defined as temporary (the next initial program load (IPL) will free up the storage

occupied by the space), extendable up to as many as 16MB, and within a

context (a library).

DCL DD CRTSTMPLT CHAR(16ð) BDRY(16);

DCL DD TMPLTSPEC CHAR(8) DEF(CRTSTMPLT) POS(1);

DCL DD TMPLTSIZE BIN(4) DEF(TMPLTSPEC) POS(1) INIT(16ð);

DCL DD TMPLTBA BIN(4) DEF(TMPLTSPEC) POS(5) INIT(ð);

DCL DD OBJID CHAR(32) DEF(CRTSTMPLT) POS(9);

DCL DD SPCTYPE CHAR(1) DEF(OBJID) POS(1) INIT(X'19');

DCL DD SPCSUBTYPE CHAR(1) DEF(OBJID) POS(2) INIT(X'EF');

DCL DD SPCNAME CHAR(3ð) DEF(OBJID) POS(3) INIT(" ");

DCL DD OBJCRTOPT CHAR(4) DEF(CRTSTMPLT) POS(41) INIT(X'6ðð2ðððð');.1/

DCL DD OBJRCVOPTS CHAR(4) DEF(CRTSTMPLT) POS(45);

DCL DD ᑍ CHAR(2) DEF(OBJRCVOPTS) POS(1) INIT(X'ðððð');

DCL DD ASP CHAR(2) DEF(OBJRCVOPTS) POS(3) INIT(X'ðððð');

DCL DD SPCSIZ BIN(4) DEF(CRTSTMPLT) POS(49) INIT(1);

DCL DD INTSPCVAL CHAR(1) DEF(CRTSTMPLT) POS(53) INIT(X'ðð');

DCL DD PERFCLASS CHAR(4) DEF(CRTSTMPLT) POS(54) INIT(X'ðððððððð');

DCL DD ᑍ CHAR(1) DEF(CRTSTMPLT) POS(58) INIT(X'ðð');

DCL DD PUBAUT CHAR(2) DEF(CRTSTMPLT) POS(59) INIT(X'ðððð');

DCL DD TMPLTEXTN BIN(4) DEF(CRTSTMPLT) POS(61) INIT(96);

DCL SYSPTR CONTEXT DEF(CRTSTMPLT) POS(65);

DCL SYSPTR ACCESSGRP DEF(CRTSTMPLT) POS(81);

DCL SYSPTR USRPRF DEF(CRTSTMPLT) POS(97);

DCL DD MAXSPCSIZ BIN(4) DEF(CRTSTMPLT) POS(113) INIT(ð);

DCL DD DOMAIN CHAR(2) DEF(CRTSTMPLT) POS(117) INIT(X'ððð1');

DCL DD ᑍ CHAR(42) DEF(CRTSTMPLT) POS(119) INIT((42)X'ðð');

3. Establish addressability to the CRTS template:

DCL SPCPTR CRTSTMPLT@ INIT(CRTSTMPLT);

4. Because the space is defined to be in a context, supply the address of the

context in the previous CRTS template. This program uses the QTEMP context

that is identified by the following:

DCL SYSPTR QTEMP@ BASPCO POS(65);

Use the copy bytes with pointers instruction (CPYBWP) to set the template

context data element.

CPYBWP CONTEXT, QTEMP@;

5. In the instruction stream, create the space:

CRTS USRSPC@, CRTSTMPLT@;

This returns a system pointer to the created space in the system pointer:

DCL SYSPTR USRSPC@;

6. Declare a space pointer for addressability to the space through a space pointer

(as opposed to the system pointer returned by the CRTS instruction):

DCL SPCPTR USRSPC;

Chapter 7. Machine Interface Programming 7-19

Download from Www.Somanuals.com. All Manuals Search And Download.

7. To keep track of how many bytes of source are loaded into the *USRSPC,

define BINOFFSET. BINOFFSET is also being defined very specifically as an

integer (BIN(4)) because it will be used later in the program with the set space

pointer offset (SETSPPO) MI instruction. This requires an integer argument to

refer to the space:

DCL DD BINOFFSET BIN(4) AUTO INIT(ð);

8. Because the size of the source is also a parameter to the QPRCRTPG API,

define a space pointer to refer to BINOFFSET:

DCL SPCPTR BINOFFSET@ AUTO INIT(BINOFFSET);

The two previous declare statements have also introduced a new attribute to

the DCL statement. Previously, all of the DCLs used the default of static

(STAT) storage. BINOFFSET and BINOFFSET@, on the other hand, are being

allocated from automatic (AUTO) storage. Many hours of debug time can be

saved if you clearly understand how the AS/400 manages these two types of

storage. For more information on the types of storage, see “AS/400 Program

Storage” on page 7-36.

So that the program does not retain the size of the source loaded from pre-

vious invocations of the program, you can declare BINOFFSET as being auto-

matic. Because BINOFFSET@ needs to be set to the address of BINOFFSET

(so that BINOFFSET can be passed as a parameter to CL06), you will also

declare it as automatic. An alternative to using automatic storage would have

been to explicitly set a static storage BINOFFSET to 0 by using CPYNV, but

this does not allow for a discussion of the storage management differences.

9. Use the CL06 program to load the space after it is created. Because CL06 is

limited to only 2000 bytes of addressability per parameter per call (CALLX), the

MICRTPG2 program uses the Override with Database File (OVRDBF) CL

command to cause the CL06 program to read and load twenty 80-byte source

records per call. The source records are read starting at 1 on the first call, 21

on the second, 41 on the third, and so on. To run CL commands from the

MICRTPG2 program, the program uses the Execute Command (QCMDEXC)

API:

DCL SYSPTR QCMDEXC INIT("QCMDEXC", CTX("QSYS"), TYPE(PGM));

10. Format the appropriate character strings for the Override with Database File

(OVRDBF) CL command:

Note: In the following declare (DCL) statement for CLOVRCMD, the 3 strings

of '1234567890' are used strictly so that you can see that 10 bytes are

being used. The strings themselves are overridden by the subsequent

subelement DCLs for FILNAM, MBRNAM, and RECNUM, and could be

replaced by 10 blanks:

DCL DD CLOVRCMD CHAR(65);

DCL DD OVRSTR CHAR(39) DEF(CLOVRCMD) POS(1)

INIT("OVRDBF MISRC 123456789ð MBR(123456789ð)");

DCL DD OVRSTR2 CHAR(26) DEF(CLOVRCMD) POS(4ð)

INIT(" POSITION(ᑍRRN 123456789ð)");

DCL DD FILNAM CHAR(1ð) DEF(CLOVRCMD) POS(14);

DCL DD MBRNAM CHAR(1ð) DEF(CLOVRCMD) POS(29);

DCL DD RECNUM ZND(1ð,ð) DEF(CLOVRCMD) POS(55);

11. Format the appropriate character strings for the Delete Override (DLTOVR) CL

command. Because the OVRDBF commands are issued repetitively to

progress through the source, the previous overrides need to be deleted:

7-20 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

DCL DD CLDLTCMD CHAR(12) INIT("DLTOVR MISRC");

12. Establish space pointers to the CL command parameters, and, because the

QCMDEXC API is being used, define the CL command string lengths as

parameters:

DCL SPCPTR CLOVRCMD@ INIT(CLOVRCMD);

DCL SPCPTR CLDLTCMD@ INIT(CLDLTCMD);

DCL DD CLOVRLNG PKD(15,5) INIT(P'65'); /ᑍ Length of OVRDBF CL cmd ᑍ/

DCL SPCPTR CLOVRLNG@ INIT(CLOVRLNG);

DCL DD CLDLTLNG PKD(15,5) INIT(P'12'); /ᑍ Length of DLTOVR CL cmd ᑍ/

DCL SPCPTR CLDLTLNG@ INIT(CLDLTLNG);

13. Define the operand list (OL) definitions for calling the QCMDEXC API under the

two different conditions:

DCL OL QCMDOVROL (CLOVRCMD@, CLOVRLNG@) ARG;

DCL OL QCMDDLTOL (CLDLTCMD@, CLDLTLNG@) ARG;

14. Because CALLX CL06 is called to load the space, declare its system pointer,

parameters, and OL:

DCL SYSPTR CLð6 INIT("CLð6", TYPE(PGM));

DCL DD OFFSET PKD(15,5);

DCL SPCPTR OFFSET@ INIT(OFFSET);

DCL OL CLð6OL (USRSPC, OFFSET@) ARG;

15. Declare the system pointer, parameters, and OL for the QPRCRTPG API:

DCL DD PGM CHAR(2ð);

DCL DD PGMNAM CHAR(1ð) DEF(PGM) POS(1);

DCL DD PGMLIBNAM CHAR(1ð) DEF(PGM) POS(11) INIT("ᑍCURLIB ");

DCL SPCPTR PGM@ INIT(PGM);

DCL DD PGMTXT CHAR(5ð) INIT(" ");

DCL SPCPTR PGMTXT@ INIT(PGMTXT);

DCL DD PGMSRCF CHAR(2ð) INIT("ᑍNONE");

DCL SPCPTR PGMSRCF@ INIT(PGMSRCF);

DCL DD PGMSRCM CHAR(1ð) INIT(" ");

DCL SPCPTR PGMSRCM@ INIT(PGMSRCM);

DCL DD PGMSRCCHG CHAR(13) INIT(" ");

DCL SPCPTR PGMSRCCHG@ INIT(PGMSRCCHG);

DCL DD PRTFNAM CHAR(2ð) INIT("QSYSPRT ᑍLIBL

DCL SPCPTR PRTFNAM@ INIT(PRTFNAM);

DCL DD PRTSTRPAG BIN(4) INIT(1);

");

DCL SPCPTR PRTSTRPAG@ INIT(PRTSTRPAG);

DCL DD PGMPUBAUT CHAR(1ð) INIT("ᑍALL

DCL SPCPTR PGMPUBAUT@ INIT(PGMPUBAUT);

");

DCL DD PGMOPTS(16) CHAR(11) INIT((1)"ᑍLIST", ᑍ(2)(1)"ᑍREPLACE");

DCL SPCPTR PGMOPTS@ INIT(PGMOPTS);

DCL DD NUMOPTS BIN(4) INIT(2);

DCL SPCPTR NUMOPTS@ INIT(NUMOPTS);

DCL OL QPRCRTPGOL (USRSPC, BINOFFSET@, PGM@, PGMTXT@, PGMSRCF@,

PGMSRCM@, PGMSRCCHG@, PRTFNAM@, PRTSTRPAG@,

PGMPUBAUT@, PGMOPTS@, NUMOPTS@) ARG;

DCL SYSPTR QPRCRTPG INIT("QPRCRTPG", CTX("QSYS"), TYPE(PGM));

Chapter 7. Machine Interface Programming 7-21

Download from Www.Somanuals.com. All Manuals Search And Download.

Beginning the Instruction Stream

Begin the instruction stream definition by doing the following:

1. Use the store parameter list length (STPLLEN) instruction to determine the

number of parameters that were passed to the program:

STPLLEN NUM_PARMS;

2. If the number of parameters is 1, assign FILNAM to the value MISRC (the

default that this program supports for the source physical file) and branch to

label PARM1 to set the source member name:

CMPNV(B) NUM_PARMS, 2 / EQ(PARM2);

CPYBLAP FILNAM, 'MISRC', ' ';

B PARM1;

3. If the number of parameters is 2, assign FILNAM to the value of the second

parameter:

PARM2: CPYBLA FILNAM, FIL;

4. Assign the source member name:

PARM1: CPYBLA MBRNAM, MBR;

5. Assign the proper context for the space:

CPYBWP CONTEXT, QTEMP@;

6. After establishing the context of the space, now create the space:

CRTS USRSPC@, CRTSTMPLT@;

7. Assign the space pointer USRSPC to address the first byte of the space:

SETSPPFP USRSPC, USRSPC@;

8. Set the OVRDBF CL command to start with POSITION(1):

CPYNV RECNUM, 1;

Using Static Storage to Your Advantage

In “Beginning the Instruction Stream,” the instructions in steps 5, 6, and 7 can be

done once and the space reused on subsequent invocations of the program. As a

performance enhancement, add a check to see if this program has been previously

invoked. To do the check, add a control field, and conditionally branch around the

CRTS-oriented instructions if this call is not the initial call:

STPLLEN NUM_PARMS;

CMPNV(B) NUM_PARMS, 2 / EQ(PARM2);

CPYBLAP FILNAM, 'MISRC', ' ';

B PARM1;

PARM2: CPYBLA FILNAM, FIL;

PARM1: CPYBLA MBRNAM,MBR;

CMPBLA(B) READY, '1' / EQ(SKIP);

CPYBWP CONTEXT, QTEMP@;

CRTS USRSPC@, CRTSTMPLT@;

SETSPPFP USRSPC,USRSPC@;

CPYBLA READY, '1';

SKIP: CPYNV RECNUM, 1;

Resuming the program flow of the MICRTPG2 program from “Beginning the Instruc-

tion Stream” on page 7-22, you should have the program perform the following:

7-22 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

1. Fall into a loop (the MORE label) until all source records are loaded as the

source physical file member position is overridden:

MORE: CALLX QCMDEXC, QCMDOVROL, ᑍ;

2. Instruct the CL06 program to load source records from the start of the input

buffer, which is actually the BINOFFSET into the space created earlier:

CPYNV OFFSET,1;

CALLX CLð6, CLð6OL, ᑍ;

3. Back out (subtract) the base-1 nature of CL using the short (the (S) extender)

form of the subtract numeric (SUBN) instruction:

SUBN(S) OFFSET, 1;

4. Add the number of MI source bytes processed by CL06 to the offset into the

space (for the next call):

ADDN(S) BINOFFSET, OFFSET;

SETSPPO USRSPC, BINOFFSET;

5. Update the Override with Database File (OVRDBF) position parameter for the

next call to CL06:

ADDN(S) RECNUM, 2ð;

6. Delete the previous OVRDBF:

CALLX QCMDEXC, QCMDDLTOL, ᑍ;

7. Check to see if all records were processed, and if not, branch to label MORE to

load more source records:

CMPNV(B) OFFSET, 16ðð /EQ(MORE);

Otherwise, assume that all source was loaded and prepare for calling the

QPRCRTPG API by setting the program name:

CPYBLA PGMNAM, MBR;

8. Reset the space pointer from the source of the input program to the start of the

space. This resetting of the static storage USRSPC is also assumed in the

branch to label SKIP earlier in the program:

SETSPPO USRSPC,ð;

9. Call the QPRCRTPG API to create the MI program:

CALLX QPRCRTPG, QPRCRTPGOL, ᑍ;

10. Indicate that the program is done:

RTX ᑍ;

PEND;

MICRTPG2 Complete Program—MI Code Example

In its consolidated state, this is the new MICRTPG2 program:

/ᑍ

ᑍ/

Program Name: MICRTPG2

Programming Language: MI

Description: Initial version of MI program MICRTPG2,

Chapter 7. Machine Interface Programming 7-23

Download from Www.Somanuals.com. All Manuals Search And Download.

/ᑍ

which calls QPRCRTPG API.

ᑍ/

Header Files Included: None

/ᑍ Entry point and associated parameters

ᑍ/

ENTRY ᑍ (ᑍENTRY) EXT;

DCL SPCPTR FIL@ PARM;

DCL SPCPTR MBR@ PARM;

DCL OL ᑍENTRY (MBR@, FIL@) PARM EXT MIN(1);

DCL DD FIL CHAR(1ð) BAS(FIL@);

DCL DD MBR CHAR(1ð) BAS(MBR@);

DCL DD NUM_PARMS BIN( 4);

/ᑍ Control field for first time initialization ᑍ/

DCL DD READY CHAR( 1) INIT("ð");

/ᑍ Binary offset into the space

ᑍ/

DCL DD BINOFFSET BIN(4) AUTO INIT(ð);

DCL SPCPTR BINOFFSET@ AUTO INIT(BINOFFSET);

/ᑍ Pointers for accessing the space

DCL SPCPTR USRSPC;

DCL SYSPTR USRSPC@;

/ᑍ QCMDEXC and associated CL commands

DCL SYSPTR QCMDEXC INIT("QCMDEXC", CTX("QSYS"), TYPE(PGM));

DCL DD CLOVRCMD CHAR(65);

DCL DD OVRSTR CHAR(39) DEF(CLOVRCMD) POS(1)

INIT("OVRDBF MISRC 123456789ð MBR(123456789ð)");

DCL DD OVRSTR2 CHAR(26) DEF(CLOVRCMD) POS(4ð)

INIT(" POSITION(ᑍRRN 123456789ð)");

DCL DD FILNAM CHAR(1ð) DEF(CLOVRCMD) POS(14);

DCL DD MBRNAM CHAR(1ð) DEF(CLOVRCMD) POS(29);

DCL DD RECNUM ZND(1ð,ð) DEF(CLOVRCMD) POS(55);

DCL SPCPTR CLOVRCMD@ INIT(CLOVRCMD);

DCL DD CLOVRLNG PKD(15,5) INIT(P'65');

DCL SPCPTR CLOVRLNG@ INIT(CLOVRLNG);

DCL OL QCMDOVROL (CLOVRCMD@, CLOVRLNG@) ARG;

DCL DD CLDLTCMD CHAR(12) INIT("DLTOVR MISRC");

DCL SPCPTR CLDLTCMD@ INIT(CLDLTCMD);

DCL DD CLDLTLNG PKD(15,5) INIT(P'12');

DCL SPCPTR CLDLTLNG@ INIT(CLDLTLNG);

DCL OL QCMDDLTOL (CLDLTCMD@, CLDLTLNG@) ARG;

/ᑍ CLð6 and associated parameters

ᑍ/

DCL SYSPTR CLð6 INIT("CLð6", TYPE(PGM));

DCL DD OFFSET PKD(15,5);

DCL SPCPTR OFFSET@ INIT(OFFSET);

DCL OL CLð6OL (USRSPC, OFFSET@) ARG;

7-24 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

/ᑍ Access QTEMP address

ᑍ/

DCL SYSPTR QTEMP@ BASPCO

POS(65);

/ᑍ Template for CRTS MI instruction

ᑍ/

DCL DD CRTSTMPLT CHAR(16ð) BDRY(16);

DCL DD TMPLTSPEC CHAR(8) DEF(CRTSTMPLT) POS(1);

DCL DD TMPLTSIZE BIN(4) DEF(TMPLTSPEC) POS(1) INIT(16ð);

DCL DD TMPLTBA BIN(4) DEF(TMPLTSPEC) POS(5) INIT(ð);

DCL DD OBJID CHAR(32) DEF(CRTSTMPLT) POS(9);

DCL DD SPCTYPE CHAR(1) DEF(OBJID) POS(1) INIT(X'19');

DCL DD SPCSUBTYPE CHAR(1) DEF(OBJID) POS(2) INIT(X'EF');

DCL DD SPCNAME CHAR(3ð) DEF(OBJID) POS(3) INIT("MICRTPG2");

DCL DD OBJCRTOPT CHAR(4) DEF(CRTSTMPLT) POS(41) INIT(X'6ðð2ðððð');

DCL DD OBJRCVOPTS CHAR(4) DEF(CRTSTMPLT) POS(45);

DCL DD ᑍ CHAR(2) DEF(OBJRCVOPTS) POS(1) INIT(X'ðððð');

DCL DD ASP CHAR(2) DEF(OBJRCVOPTS) POS(3) INIT(X'ðððð');

DCL DD SPCSIZ BIN(4) DEF(CRTSTMPLT) POS(49) INIT(1);

DCL DD INTSPCVAL CHAR(1) DEF(CRTSTMPLT) POS(53) INIT(X'ðð');

DCL DD PERFCLASS CHAR(4) DEF(CRTSTMPLT) POS(54) INIT(X'ðððððððð');

DCL DD ᑍ CHAR(1) DEF(CRTSTMPLT) POS(58) INIT(X'ðð');

DCL DD PUBAUT CHAR(2) DEF(CRTSTMPLT) POS(59) INIT(X'ðððð');

DCL DD TMPLTEXTN BIN(4) DEF(CRTSTMPLT) POS(61) INIT(96);

DCL SYSPTR CONTEXT DEF(CRTSTMPLT) POS(65);

DCL SYSPTR ACCESSGRP DEF(CRTSTMPLT) POS(81);

DCL SYSPTR USRPRF DEF(CRTSTMPLT) POS(97);

DCL DD MAXSPCSIZ BIN(4) DEF(CRTSTMPLT) POS(113) INIT(ð);

DCL DD DOMAIN CHAR(2) DEF(CRTSTMPLT) POS(117) INIT(X'ððð1');

DCL DD ᑍ CHAR(42) DEF(CRTSTMPLT) POS(119) INIT((42)X'ðð');

DCL SPCPTR CRTSTMPLT@ INIT(CRTSTMPLT);

/ᑍ QPRCRTPG and associated parameters

ᑍ/

DCL DD PGM CHAR(2ð);

DCL DD PGMNAM CHAR(1ð) DEF(PGM) POS(1);

DCL DD PGMLIBNAM CHAR(1ð) DEF(PGM) POS(11) INIT("ᑍCURLIB ");

DCL SPCPTR PGM@ INIT(PGM);

DCL DD PGMTXT CHAR(5ð) INIT(" ");

DCL SPCPTR PGMTXT@ INIT(PGMTXT);

DCL DD PGMSRCF CHAR(2ð) INIT("ᑍNONE");

DCL SPCPTR PGMSRCF@ INIT(PGMSRCF);

DCL DD PGMSRCM CHAR(1ð) INIT(" ");

DCL SPCPTR PGMSRCM@ INIT(PGMSRCM);

DCL DD PGMSRCCHG CHAR(13) INIT(" ");

DCL SPCPTR PGMSRCCHG@ INIT(PGMSRCCHG);

DCL DD PRTFNAM CHAR(2ð) INIT("QSYSPRT ᑍLIBL

DCL SPCPTR PRTFNAM@ INIT(PRTFNAM);

DCL DD PRTSTRPAG BIN(4) INIT(1);

");

DCL SPCPTR PRTSTRPAG@ INIT(PRTSTRPAG);

DCL DD PGMPUBAUT CHAR(1ð) INIT("ᑍALL

DCL SPCPTR PGMPUBAUT@ INIT(PGMPUBAUT);

");

DCL DD PGMOPTS(16) CHAR(11) INIT((1)"ᑍLIST", ᑍ(2)(1)"ᑍREPLACE",

ᑍ(3)(1)"ᑍXREF");

DCL SPCPTR PGMOPTS@ INIT(PGMOPTS);

DCL DD NUMOPTS BIN(4) INIT(3);

Chapter 7. Machine Interface Programming 7-25

Download from Www.Somanuals.com. All Manuals Search And Download.

DCL SPCPTR NUMOPTS@ INIT(NUMOPTS);

DCL OL QPRCRTPGOL (USRSPC, BINOFFSET@, PGM@, PGMTXT@, PGMSRCF@,

PGMSRCM@, PGMSRCCHG@, PRTFNAM@, PRTSTRPAG@,

PGMPUBAUT@, PGMOPTS@, NUMOPTS@) ARG;

DCL SYSPTR QPRCRTPG INIT("QPRCRTPG", CTX("QSYS"), TYPE(PGM));

/ᑍ Start of instruction stream

ᑍ/

STPLLEN NUM_PARMS;

CMPNV(B) NUM_PARMS, 2 / EQ(PARM2);

CPYBLAP FILNAM, 'MISRC', ' ';

B PARM1;

PARM2: CPYBLA FILNAM, FIL;

PARM1: CPYBLA MBRNAM,MBR;

CMPBLA(B) READY, '1' / EQ(SKIP);

CPYBWP CONTEXT, QTEMP@;

CRTS USRSPC@, CRTSTMPLT@;

SETSPPFP USRSPC,USRSPC@;

CPYBLA READY, '1';

SKIP: CPYNV RECNUM, 1;

MORE: CALLX QCMDEXC, QCMDOVROL, ᑍ;

CPYNV OFFSET,1;

CALLX CLð6, CLð6OL, ᑍ;

SUBN(S) OFFSET, 1;

ADDN(S) BINOFFSET, OFFSET;

SETSPPO USRSPC, BINOFFSET;

ADDN(S) RECNUM, 2ð;

CALLX QCMDEXC, QCMDDLTOL, ᑍ;

CMPNV(B) OFFSET, 16ðð /EQ(MORE);

CPYBLA PGMNAM, MBR;

SETSPPO USRSPC, ð;

CALLX QPRCRTPG, QPRCRTPGOL, ᑍ;

RTX ᑍ;

PEND;

Updated CL06 Program

Following is the updated CL06 program:

/ᑍ

ᑍ/

Program Name: CLð6

Programming Language: CL

Description: Load a source physical file member into the

ᑍUSRSPC addressed by &BUFFER.

Header Files Included: None

PGM

DCLF

DCL

RCVF

PARM(&BUFFER &OFFSET)

FILE(MISRC)

VAR(&BUFFER) TYPE(ᑍCHAR) LEN(16ðð)

VAR(&OFFSET) TYPE(ᑍDEC) LEN(15 5)

LOOP:

7-26 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

MONMSG

CHGVAR

MSGID(CPFð864 CPF4137) EXEC(GOTO CMDLBL(DONE))

VAR(%SST(&BUFFER &OFFSET 8ð)) VALUE(&SRCDTA)

VAR(&OFFSET) VALUE(&OFFSET + 8ð)

COND(&OFFSET ᑍGT 16ðð) THEN(GOTO CMDLBL(DONE))

CMDLBL(LOOP)

GOTO

DONE:

ENDPGM

Creating the MICRTPG2 Program

To create the MICRTPG2 program, use:

DLTOVR MISRC

CALL CLð3 (MISRC MICRTPG2)

After the successful creation of MICRTPG2, you can create any new MI programs

by entering the following, where SourceFileName is an optional parameter:

CALL MICRTPG2 (MemberName SourceFileName)

Handling Exceptions in the MICRTPG2 Program

Some exceptions that are not being handled by the MICRTPG2 program may

occur. For example, if you used MICRTPG2 to compile MICRTPG2 two times in

succession, the exception MCH1401 occurs. This occurs because the most recent

activation of the MICRTPG2 program has its own static storage and is not aware of

the earlier instances of MICRTPG2 creating the space named MICRTPG2 in

QTEMP.

To correct this problem do the following:

1. Define an exception description that passes control to an internal exception

handler:

DCL EXCM DUPERROR EXCID(H'ðEð1') INT(M14ð1) IMD;

2. Define the internal entry point:

ENTRY M14ð1 INT;

3. Define related data elements for the M1401 exception:

/ᑍ Exception description template for RETEXCPD ᑍ/

DCL DD EXCPDBUF CHAR(2ðð) BDRY(16);

DCL DD BYTPRV BIN(4) DEF(EXCPDBUF) POS(1) INIT(2ðð);

DCL DD BYTAVL BIN(4) DEF(EXCPDBUF) POS(5);

DCL DD EXCPID CHAR(2) DEF(EXCPDBUF) POS(9);

DCL DD CMPLEN BIN(2) DEF(EXCPDBUF) POS(11);

DCL DD CMPDTA CHAR(32) DEF(EXCPDBUF) POS(13);

DCL DD MSGKEY CHAR(4) DEF(EXCPDBUF) POS(45);

DCL DD EXCDTA CHAR(5ð) DEF(EXCPDBUF) POS(49);

DCL SYSPTR EXC_OBJ@ DEF(EXCDTA) POS(1);

DCL DD EXC_OBJ CHAR(32) DEF(EXCDTA) POS(17);

DCL PTR INV_PTR DEF(EXCPDBUF) POS(97);

DCL DD ᑍ CHAR(87) DEF(EXCPDBUF) POS(113);

DCL SPCPTR EXCPDBUF@ INIT(EXCPDBUF);

/ᑍ Template for RTNEXCP

ᑍ/

DCL DD RTNTMPLT CHAR(19) BDRY(16);

Chapter 7. Machine Interface Programming 7-27

Download from Www.Somanuals.com. All Manuals Search And Download.

DCL PTR INV_PTR2 DEF(RTNTMPLT) POS(1);

DCL DD ᑍ CHAR(1) DEF(RTNTMPLT) POS(17) INIT(X'ðð');

DCL DD ACTION CHAR(2) DEF(RTNTMPLT) POS(18);

DCL SPCPTR RTNTMPLT@ INIT(RTNTMPLT);

4. Retrieve the exception data associated with the MCH1401 exception:

RETEXCPD EXCPDBUF@, X'ð1';

5. Compare the exception data object identifier to the space identifier you create.

If they are the same, branch to label SAME:

CMPBLA(B) EXC_OBJ, OBJID / EQ(SAME);

a. If the exception data object identifier and the space identifier are not the

same, the program is truly in an unexpected error condition and the excep-

tion description needs to be disabled:

MODEXCPD DUPERROR, X'2ððð', X'ð1';

Retry the failing instruction. As the exception description is disabled, the

exception is sent to the caller of the program:

CPYBLA ACTION, X'ðððð';

B E14ð1;

b. If the exception data object identifier and the space identifier are the same,

the static storage must have been effectively reset. The program reassigns

USRSPC@ by using the returned system pointer in the exception data and

continues with the next instruction following the failed CRTS:

SAME: CPYBWP USRSPC@, EXC_OBJ@;

CPYBLA ACTION, X'ð1ðð';

E14ð1: CPYBWP INV_PTR2, INV_PTR;

RTNEXCP RTNTMPLT@;

PEND;

MICRTPG2 Complete Program (Enhanced)—MI Code Example

In its consolidated state, this is the new MICRTPG2 program:

/ᑍ

ᑍ/

Program Name: MICRTPG2

Programming Language: MI

Description: Enhanced version of MI program MICRTPG2,

which provides for exception handling.

Header Files Included: None

/ᑍ Entry point and associated parameters

ᑍ/

ENTRY ᑍ (ᑍENTRY) EXT;

DCL SPCPTR FIL@ PARM;

DCL SPCPTR MBR@ PARM;

DCL OL ᑍENTRY (MBR@, FIL@) PARM EXT MIN(1);

DCL DD FIL CHAR(1ð) BAS(FIL@);

7-28 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

DCL DD MBR CHAR(1ð) BAS(MBR@);

DCL DD NUM_PARMS BIN( 4);

/ᑍ Control field for first time initialization ᑍ/

DCL DD READY CHAR( 1) INIT("ð");

/ᑍ Binary offset into the space

ᑍ/

DCL DD BINOFFSET BIN(4) AUTO INIT(ð);

DCL SPCPTR BINOFFSET@ AUTO INIT(BINOFFSET);

/ᑍ Pointers for accessing the space

DCL SPCPTR USRSPC;

DCL SYSPTR USRSPC@;

/ᑍ QCMDEXC and associated CL commands

DCL SYSPTR QCMDEXC INIT("QCMDEXC", CTX("QSYS"), TYPE(PGM));

DCL DD CLOVRCMD CHAR(65);

DCL DD OVRSTR CHAR(39) DEF(CLOVRCMD) POS(1)

INIT("OVRDBF MISRC 123456789ð MBR(123456789ð)");

DCL DD OVRSTR2 CHAR(26) DEF(CLOVRCMD) POS(4ð)

INIT(" POSITION(ᑍRRN 123456789ð)");

DCL DD FILNAM CHAR(1ð) DEF(CLOVRCMD) POS(14);

DCL DD MBRNAM CHAR(1ð) DEF(CLOVRCMD) POS(29);

DCL DD RECNUM ZND(1ð,ð) DEF(CLOVRCMD) POS(55);

DCL SPCPTR CLOVRCMD@ INIT(CLOVRCMD);

DCL DD CLOVRLNG PKD(15,5) INIT(P'65');

DCL SPCPTR CLOVRLNG@ INIT(CLOVRLNG);

DCL OL QCMDOVROL (CLOVRCMD@, CLOVRLNG@) ARG;

DCL DD CLDLTCMD CHAR(12) INIT("DLTOVR MISRC");

DCL SPCPTR CLDLTCMD@ INIT(CLDLTCMD);

DCL DD CLDLTLNG PKD(15,5) INIT(P'12');

DCL SPCPTR CLDLTLNG@ INIT(CLDLTLNG);

DCL OL QCMDDLTOL (CLDLTCMD@, CLDLTLNG@) ARG;

/ᑍ CLð6 and associated parameters

ᑍ/

DCL SYSPTR CLð6 INIT("CLð6", TYPE(PGM));

DCL DD OFFSET PKD(15,5);

DCL SPCPTR OFFSET@ INIT(OFFSET);

DCL OL CLð6OL (USRSPC, OFFSET@) ARG;

/ᑍ Access QTEMP address

ᑍ/

DCL SYSPTR QTEMP@ BASPCO

POS(65);

/ᑍ Template for CRTS MI instruction

ᑍ/

DCL DD CRTSTMPLT CHAR(16ð) BDRY(16);

DCL DD TMPLTSPEC CHAR(8) DEF(CRTSTMPLT) POS(1);

DCL DD TMPLTSIZE BIN(4) DEF(TMPLTSPEC) POS(1) INIT(16ð);

DCL DD TMPLTBA BIN(4) DEF(TMPLTSPEC) POS(5) INIT(ð);

DCL DD OBJID CHAR(32) DEF(CRTSTMPLT) POS(9);

DCL DD SPCTYPE CHAR(1) DEF(OBJID) POS(1) INIT(X'19');

DCL DD SPCSUBTYPE CHAR(1) DEF(OBJID) POS(2) INIT(X'EF');

Chapter 7. Machine Interface Programming 7-29

Download from Www.Somanuals.com. All Manuals Search And Download.

DCL DD SPCNAME CHAR(3ð) DEF(OBJID) POS(3) INIT("MICRTPG2");

DCL DD OBJCRTOPT CHAR(4) DEF(CRTSTMPLT) POS(41) INIT(X'6ðð2ðððð');

DCL DD OBJRCVOPTS CHAR(4) DEF(CRTSTMPLT) POS(45);

DCL DD ᑍ CHAR(2) DEF(OBJRCVOPTS) POS(1) INIT(X'ðððð');

DCL DD ASP CHAR(2) DEF(OBJRCVOPTS) POS(3) INIT(X'ðððð');

DCL DD SPCSIZ BIN(4) DEF(CRTSTMPLT) POS(49) INIT(1);

DCL DD INTSPCVAL CHAR(1) DEF(CRTSTMPLT) POS(53) INIT(X'ðð');

DCL DD PERFCLASS CHAR(4) DEF(CRTSTMPLT) POS(54) INIT(X'ðððððððð');

DCL DD ᑍ CHAR(1) DEF(CRTSTMPLT) POS(58) INIT(X'ðð');

DCL DD PUBAUT CHAR(2) DEF(CRTSTMPLT) POS(59) INIT(X'ðððð');

DCL DD TMPLTEXTN BIN(4) DEF(CRTSTMPLT) POS(61) INIT(96);

DCL SYSPTR CONTEXT DEF(CRTSTMPLT) POS(65);

DCL SYSPTR ACCESSGRP DEF(CRTSTMPLT) POS(81);

DCL SYSPTR USRPRF DEF(CRTSTMPLT) POS(97);

DCL DD MAXSPCSIZ BIN(4) DEF(CRTSTMPLT) POS(113) INIT(ð);

DCL DD DOMAIN CHAR(2) DEF(CRTSTMPLT) POS(117) INIT(X'ððð1');

DCL DD ᑍ CHAR(42) DEF(CRTSTMPLT) POS(119) INIT((42)X'ðð');

DCL SPCPTR CRTSTMPLT@ INIT(CRTSTMPLT);

/ᑍ QPRCRTPG and associated parameters

ᑍ/

DCL DD PGM CHAR(2ð);

DCL DD PGMNAM CHAR(1ð) DEF(PGM) POS(1);

DCL DD PGMLIBNAM CHAR(1ð) DEF(PGM) POS(11) INIT("ᑍCURLIB ");

DCL SPCPTR PGM@ INIT(PGM);

DCL DD PGMTXT CHAR(5ð) INIT(" ");

DCL SPCPTR PGMTXT@ INIT(PGMTXT);

DCL DD PGMSRCF CHAR(2ð) INIT("ᑍNONE");

DCL SPCPTR PGMSRCF@ INIT(PGMSRCF);

DCL DD PGMSRCM CHAR(1ð) INIT(" ");

DCL SPCPTR PGMSRCM@ INIT(PGMSRCM);

DCL DD PGMSRCCHG CHAR(13) INIT(" ");

DCL SPCPTR PGMSRCCHG@ INIT(PGMSRCCHG);

DCL DD PRTFNAM CHAR(2ð) INIT("QSYSPRT ᑍLIBL

DCL SPCPTR PRTFNAM@ INIT(PRTFNAM);

DCL DD PRTSTRPAG BIN(4) INIT(1);

");

DCL SPCPTR PRTSTRPAG@ INIT(PRTSTRPAG);

DCL DD PGMPUBAUT CHAR(1ð) INIT("ᑍALL

DCL SPCPTR PGMPUBAUT@ INIT(PGMPUBAUT);

");

DCL DD PGMOPTS(16) CHAR(11) INIT((1)"ᑍLIST", ᑍ(2)(1)"ᑍREPLACE",

ᑍ(3)(1)"ᑍXREF");

DCL SPCPTR PGMOPTS@ INIT(PGMOPTS);

DCL DD NUMOPTS BIN(4) INIT(3);

DCL SPCPTR NUMOPTS@ INIT(NUMOPTS);

DCL OL QPRCRTPGOL (USRSPC, BINOFFSET@, PGM@, PGMTXT@, PGMSRCF@,

PGMSRCM@, PGMSRCCHG@, PRTFNAM@, PRTSTRPAG@,

PGMPUBAUT@, PGMOPTS@, NUMOPTS@) ARG;

DCL SYSPTR QPRCRTPG INIT("QPRCRTPG", CTX("QSYS"), TYPE(PGM));

/ᑍ Exception Description Monitor for MCH14ð1

DCL EXCM DUPERROR EXCID(H'ðEð1') INT(M14ð1) IMD;

/ᑍ Start of instruction stream

ᑍ/

STPLLEN NUM_PARMS;

CMPNV(B) NUM_PARMS, 2 / EQ(PARM2);

CPYBLAP FILNAM, 'MISRC', ' ';

7-30 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

B PARM1;

PARM2: CPYBLA FILNAM, FIL;

PARM1: CPYBLA MBRNAM,MBR;

CMPBLA(B) READY, '1' / EQ(SKIP);

CPYBWP CONTEXT, QTEMP@;

CRTS USRSPC@, CRTSTMPLT@;

SETSPPFP USRSPC,USRSPC@;

CPYBLA READY, '1';

SKIP: CPYNV RECNUM, 1;

MORE: CALLX QCMDEXC, QCMDOVROL, ᑍ;

CPYNV OFFSET,1;

CALLX CLð6, CLð6OL, ᑍ;

SUBN(S) OFFSET, 1;

ADDN(S) BINOFFSET, OFFSET;

SETSPPO USRSPC, BINOFFSET;

ADDN(S) RECNUM, 2ð;

CALLX QCMDEXC, QCMDDLTOL, ᑍ;

CMPNV(B) OFFSET, 16ðð /EQ(MORE);

CPYBLA PGMNAM, MBR;

SETSPPO USRSPC, ð;

CALLX QPRCRTPG, QPRCRTPGOL, ᑍ;

RTX ᑍ;

/ᑍ Entry point for internal exception handler

ENTRY M14ð1 INT;

ᑍ/

/ᑍ Exception description template for RETEXCPD ᑍ/

DCL DD EXCPDBUF CHAR(2ðð) BDRY(16);

DCL DD BYTPRV BIN(4) DEF(EXCPDBUF) POS(1) INIT(2ðð);

DCL DD BYTAVL BIN(4) DEF(EXCPDBUF) POS(5);

DCL DD EXCPID CHAR(2) DEF(EXCPDBUF) POS(9);

DCL DD CMPLEN BIN(2) DEF(EXCPDBUF) POS(11);

DCL DD CMPDTA CHAR(32) DEF(EXCPDBUF) POS(13);

DCL DD MSGKEY CHAR(4) DEF(EXCPDBUF) POS(45);

DCL DD EXCDTA CHAR(5ð) DEF(EXCPDBUF) POS(49);

DCL SYSPTR EXC_OBJ@ DEF(EXCDTA) POS(1);

DCL DD EXC_OBJ CHAR(32) DEF(EXCDTA) POS(17);

DCL PTR INV_PTR DEF(EXCPDBUF) POS(97);

DCL DD ᑍ CHAR(87) DCF(EXCPDBUF) POS(113);

DCL SPCPTR EXCPDBUF@ INIT(EXCPDBUF);

/ᑍ Template for RTNEXCP

ᑍ/

DCL DD RTNTMPLT CHAR(19) BDRY(16);

DCL PTR INV_PTR2 DEF(RTNTMPLT) POS(1);

DCL DD ᑍ CHAR(1) DEF(RTNTMPLT) POS(17) INIT(X'ðð');

DCL DD ACTION CHAR(2) DEF(RTNTMPLT) POS(18);

DCL SPCPTR RTNTMPLT@ INIT(RTNTMPLT);

/ᑍ Start of internal handler

ᑍ/

RETEXCPD EXCPDBUF@, X'ð1';

CMPBLA(B) EXC_OBJ, OBJID / EQ(SAME);

MODEXCPD DUPERROR, X'2ððð', X'ð1';

CPYBLA ACTION, X'ðððð';

Chapter 7. Machine Interface Programming 7-31

Download from Www.Somanuals.com. All Manuals Search And Download.

B E14ð1;

SAME: CPYBWP USRSPC@, EXC_OBJ@;

CPYBLA ACTION, X'ð1ðð';

E14ð1: CPYBWP INV_PTR2, INV_PTR;

RTNEXCP RTNTMPLT@;

PEND;

MI Common Programming Techniques—Examples

With the completion of the MICRTPG2 program, the following example MI program

demonstrates some additional programming techniques:

/ᑍ

ᑍ/

Program Name: MISC1

Programming Language: MI

Description: This program materializes the objects found

within the QTEMP library (context). For each ᑍ/

object found, a message is sent to the

interactive user message queue showing the

name of the object and the object's type and

subtype.

ᑍ/

Several new MI instructions are used by this

program:

1. Materialize Context (MATCTX)

2. Modify Automatic Storage (MODASA)

3. Divide (DIV)

4. Convert Hex to Character (CVTHC)

5. Override Program Attributes (OVRPGATR)

Header Files Included: None

/ᑍ Entry point

ᑍ/

ENTRY ᑍ EXT;

/ᑍ Declare layout of Process Communications Object (PCO)

/ᑍ The PCO is a control area that is unique to each job on the

ᑍ/

/ᑍ system. Within the PCO, there are two data elements that can ᑍ/

/ᑍ be used. The first is a space pointer to the system entry

/ᑍ point table (SEPT), the second is the address of the QTEMP

ᑍ/

/ᑍ library. The use of any other data element in the PCO is NOT ᑍ/

/ᑍ supported.

ᑍ/

DCL DD PCO CHAR(8ð) BASPCO;

DCL SPCPTR SEPT@

DCL SYSPTR QTEMP@

DEF(PCO)

POS( 1);

POS(65);

7-32 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

/ᑍ The SEPT is an array of system pointers that address IBM

ᑍ/

/ᑍ programs in QSYS. Within this array of pointers, some of the ᑍ/

/ᑍ offsets represent fixed (upward compatible) assignments. All ᑍ/

/ᑍ OS/4ðð APIs, for instance, are fixed at certain offsets within ᑍ/

/ᑍ the SEPT and you can call these APIs directly via the SEPT.

/ᑍ Calling APIs in this way avoids having to resolve to the API

/ᑍ (that is, performance is improved) and prevents someone from

/ᑍ placing their version of the API earlier in the library list

/ᑍ than the IBM-supplied API (that is, avoids counterfeits).

ᑍ/

/ᑍ All APIs, and their offsets, can be found in the source member ᑍ/

/ᑍ QLIEPTI of file H in the optionally installed QSYSINC library. ᑍ/

/ᑍ You should only use the SEPT for those programs identified in ᑍ/

/ᑍ member QLIEPTI. The use of any other SEPT offsets is NOT

/ᑍ supported.

ᑍ/

/ᑍ Because the offset values in member QLIEPTI are oriented to the ᑍ/

/ᑍ C language, they are assuming a base of ð. Because MI arrays ᑍ/

/ᑍ use a default base of 1, we will declare the SEPT array with

/ᑍ an explicit base of ð. Because the array can grow over time

/ᑍ (and we don't necessarily want to have to change the upper

ᑍ/

/ᑍ bound every release), we'll just define the array as having 2 ᑍ/

/ᑍ elements and use the OVRPGATR instruction later in the program ᑍ/

/ᑍ to instruct the translator to ignore the array bounds when

/ᑍ referring to the array. For example, later we will use

ᑍ/

/ᑍ SEPT(4267) to call the Send Nonprogram Message (QMHSNDM) API. ᑍ/

DCL SYSPTR SEPT(ð:1) BAS(SEPT@); /ᑍ use Base ð to match QLIEPTI ᑍ/

/ᑍ Declare template for Materialize Context (MATCTX)

DCL DD MATCTXOPTS CHAR(44);

ᑍ/

DCL DD MATCTXCTL

CHAR( 2) DEF(MATCTXOPTS) POS( 1) INIT(X'ð5ðð');

DCL DD MATCTXSELCTL CHAR(42) DEF(MATCTXOPTS) POS( 3);

/ᑍ Declare Small Receiver for initial MATCTX

DCL DD S_RECEIVER CHAR(8) BDRY(16);

DCL DD S_BYTPRV

DCL DD S_BYTAVL

BIN( 4) DEF(S_RECEIVER) POS( 1) INIT(8);

BIN( 4) DEF(S_RECEIVER) POS( 5);

DCL SPCPTR S_RECEIVER@ INIT(S_RECEIVER);

/ᑍ Declare Large Receiver Layout for second MATCTX

ᑍ/

DCL DD L_RECEIVER

DCL DD L_BYTPRV

DCL DD L_BYTAVL

DCL DD L_CONTEXT

CHAR(129) BAS(L_RECEIVER@);

BIN( 4) DEF(L_RECEIVER) POS( 1);

BIN( 4) DEF(L_RECEIVER) POS( 5);

CHAR(32) DEF(L_RECEIVER) POS( 9);

DCL DD L_OBJ_TYPE CHAR( 1) DEF(L_CONTEXT) POS( 1);

DCL DD L_OBJ_STYPE CHAR( 1) DEF(L_CONTEXT) POS( 2);

DCL DD L_OBJ_NAME CHAR(3ð) DEF(L_CONTEXT) POS( 3);

DCL DD L_CTX_OPTS CHAR( 4) DEF(L_RECEIVER) POS(41);

DCL DD L_RCV_OPTS CHAR( 4) DEF(L_RECEIVER) POS(45);

DCL DD L_SPC_SIZ

BIN( 4) DEF(L_RECEIVER) POS(49);

DCL DD L_SPC_IVAL CHAR( 1) DEF(L_RECEIVER) POS(53);

DCL DD L_PERF_CLS CHAR( 4) DEF(L_RECEIVER) POS(54);

DCL DD ᑍ

CHAR( 7) DEF(L_RECEIVER) POS(58);

CHAR(16) DEF(L_RECEIVER) POS(65);

DCL SYSPTR L_ACC_GROUP;

Chapter 7. Machine Interface Programming 7-33

Download from Www.Somanuals.com. All Manuals Search And Download.

DCL DD L_EXT_ATTR CHAR( 1) DEF(L_RECEIVER) POS(81);

DCL DD ᑍ CHAR( 7) DEF(L_RECEIVER) POS(82);

DCL DD L_TIMESTAMP CHAR( 8) DEF(L_RECEIVER) POS(89);

DCL DD L_ENTRY CHAR(32) DEF(L_RECEIVER) POS(97);

/ᑍ Individual object entry layout

ᑍ/

DCL DD OBJ_ENTRY

CHAR(32) BAS(OBJ_ENTRY@);

DCL DD OBJ_INFO_X CHAR( 2) DEF(OBJ_ENTRY) POS( 1);

DCL DD OBJ_TYPE_X CHAR( 1) DEF(OBJ_INFO_X) POS( 1);

DCL DD OBJ_STYPE_X CHAR( 1) DEF(OBJ_INFO_X) POS( 2);

DCL DD OBJ_NAME

CHAR(3ð) DEF(OBJ_ENTRY) POS( 3);

/ᑍ Define basing pointers:

ᑍ/

DCL SPCPTR L_RECEIVER@;

DCL SPCPTR OBJ_ENTRY@;

/ᑍ Define various working variables

DCL DD SIZE

BIN( 4);

BIN( 4)

/ᑍ number of objects materialized ᑍ/

DCL DD NUM_DONE

/ᑍ number of objects processed

ᑍ/

AUTO INIT(ð);

/ᑍ Define needed parameters for QMHSNDM API

ᑍ/

DCL DD MSG_ID

DCL SPCPTR MSG_ID@ INIT(MSG_ID);

DCL DD MSG_FILE CHAR(2ð) INIT("

DCL SPCPTR MSG_FILE@ INIT(MSG_FILE);

CHAR (7) INIT("

");

DCL DD MSG_TEXT

DCL DD ᑍ

CHAR(57);

CHAR( 8) DEF(MSG_TEXT) POS( 1)

INIT("OBJECT: ");

DCL DD OBJ_NAME_T CHAR(3ð) DEF(MSG_TEXT) POS( 9);

DCL DD ᑍ

CHAR(15) DEF(MSG_TEXT) POS(39)

INIT(" TYPE/SUBTYPE: ");

DCL DD OBJ_INFO_C CHAR( 4) DEF(MSG_TEXT) POS(54);

DCL DD OBJ_TYPE_C CHAR( 2) DEF(OBJ_INFO_C) POS( 1);

DCL DD OBJ_STYPE_C CHAR( 2) DEF(OBJ_INFO_C) POS( 3);

DCL SPCPTR MSG_TEXT@ INIT(MSG_TEXT);

DCL DD MSG_SIZE

BIN( 4) INIT(57);

DCL SPCPTR MSG_SIZE@ INIT(MSG_SIZE);

DCL DD MSG_TYPE

CHAR(1ð) INIT("ᑍINFO

");

DCL SPCPTR MSG_TYPE@ INIT(MSG_TYPE);

DCL DD MSG_QS

CHAR(2ð) INIT("ᑍREQUESTER

");

DCL SPCPTR MSG_QS@ INIT(MSG_QS);

DCL DD MSG_QSN

BIN( 4) INIT(1);

DCL SPCPTR MSG_QSN@ INIT(MSG_QSN);

DCL DD REPLY_Q CHAR(2ð) INIT("

DCL SPCPTR REPLY_Q@ INIT(REPLY_Q);

DCL DD MSG_KEY CHAR( 4);

DCL SPCPTR MSG_KEY@ INIT(MSG_KEY);

DCL DD ERR_COD BIN( 4) INIT(ð);

DCL SPCPTR ERR_COD@ INIT(ERR_COD);

DCL OL QMHSNDMOL (MSG_ID@, MSG_FILE@, MSG_TEXT@, MSG_SIZE@,

MSG_TYPE@, MSG_QS@, MSG_QSN@, REPLY_Q@,

MSG_KEY@, ERR_COD@) ARG;

/ᑍ Start the instruction stream

ᑍ/

7-34 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

/ᑍ Materialize the amount of storage needed to store object info ᑍ/

MATCTX S_RECEIVER@, QTEMP@, MATCTXOPTS;

/ᑍ If no objects are in the library, then exit

CMPNV(B) S_BYTAVL, 96 / EQ(DONE);

ᑍ/

/ᑍ Allocate the necessary storage (we could also have used CRTS

to allocate the storage and a SPCPTR to the space for the

large receiver variable)

ᑍ/

MODASA

/ᑍ Set the bytes provided field to indicate the allocated storage ᑍ/

CPYNV L_BYTPRV, S_BYTAVL;

/ᑍ Materialize the objects within the library

L_RECEIVER@, S_BYTAVL;

ᑍ/

MATCTX

L_RECEIVER@, QTEMP@, MATCTXOPTS;

/ᑍ Calculate how many objects were returned:

ᑍ/

/ᑍ 1. Find the lower of bytes provided and bytes available

/ᑍ

(L_BYTPRV and L_BYTAVL) as the number of objects could have ᑍ/

changed since the first materialize

ᑍ/

/ᑍ 2. Subtract the size of the fixed MATCTX header (96)

/ᑍ 3. Divide the remainder by the size of each entry returned

CMPNV(B) L_BYTPRV, L_BYTAVL / HI(ITS_AVL);

CPYNV

SIZE, L_BYTPRV;

CONTINUE;

ITS_AVL:

CPYNV

SIZE, L_BYTAVL;

CONTINUE: SUBN(SB) SIZE, 96 / ZER(DONE);

DIV

SIZE, SIZE, 32;

/ᑍ Address the first object returned

ᑍ/

SETSPP

OBJ_ENTRY@, L_ENTRY;

/ᑍ Loop through all materialized entries

/ᑍ Convert the hex object type and subtype to character form

CVTHC

/ᑍ Copy the object name to the message variable

CPYBLA OBJ_NAME_T, OBJ_NAME;

OBJ_INFO_C, OBJ_INFO_X;

/ᑍ Unconstrain the array bounds (at compile time)

OVRPGATR 1,3;

/ᑍ Send a message to caller's msg queue containing the object info ᑍ/

Chapter 7. Machine Interface Programming 7-35

Download from Www.Somanuals.com. All Manuals Search And Download.

CALLX

SEPT(4267), QMHSNDMOL, ᑍ;

/ᑍ resume normal array constraint

OVRPGATR 1,4;

ᑍ/

/ᑍ and move on to the next entry

ADDN(S)

ADDSPP

NUM_DONE, 1;

OBJ_ENTRY@, OBJ_ENTRY@, 32;

CMPNV(B) NUM_DONE, SIZE / LO(MORE);

/ᑍ When all entries are processed, end the program.

/ᑍ

/ᑍ Note that this program may not actually display all objects

/ᑍ in QTEMP. If L_BYTAVL is greater than L_BYTPRV, additional

/ᑍ objects were inserted into QTEMP between the time of the

/ᑍ "small" MATCTX and the "large" MATCTX. The processing of these ᑍ/

/ᑍ additional objects is not addressed in this program and is

/ᑍ the responsibility of the user of this program.

/ᑍ

ᑍ/

DONE:

RTX

PEND;

ᑍ;

AS/400 Program Storage

On AS/400 systems, two steps are needed to run a program: program activation

and program invocation. Program activation is the process of allocating and ini-

tializing static storage for the program. Program invocation is the process of allo-

cating and initializing automatic storage.

Program Activation and Static Storage: Program activation can be done explic-

itly through the Activate Program (ACTPG) instruction or implicitly by using a call

external (CALLX) instruction when the called program has not been previously acti-

vated. Program activation typically occurs only once within a job or process.

Program activation is not reset by an RTX instruction within the called program (the

program is still considered to be in an activated state). This means that all static

storage on subsequent calls (CALLXs) to the program are found in a last-used

state, not in a reinitialized state. If a programmer wants to reinitialize the static

storage associated with a program activation, this can be accomplished through the

deactivate program (DEACTPG) instruction so that the next call (CALLX or ACTPG)

causes a new activation of the program.

Program Invocation and Automatic Storage: Program invocation, on the other

hand, occurs every time a program is called with a CALLX instruction. Automatic

storage is reinitialized if a discrete INIT value was specified on the declare (DCL)

statement. (If the INIT was allowed to be the default, then whether or not initializa-

tion occurs for the field is determined by an option of the QPRCRTPG API when

the program was created.) If you have not already done so, review all of the option

template values available on the QPRCRTPG API before developing your MI appli-

cations.

7-36 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Chapter 8. Use of OS/400 APIs

This chapter discusses the various groups of OS/400 APIs and how they may be of

use to you. Some APIs are discussed as a group, similar to the parts in the

System API Reference, while others are discussed individually.

The API discussions in this chapter are presented in the same order as in the

System API Reference.

Backup and Recovery APIs

Use of the backup and recovery APIs is described as follows:

Ÿ Operational-Assistant Backup APIs

The APIs for Operational Assistant backup have been provided to give the

users an interface into the Operational-Assistant backup setup functions without

having to go through the normal displays. One possible use of these APIs

would be to change the way the backup runs from one week to the next. For

example, the user could write a CL program that could run on those weeks in

which holidays occur to change the backup options to skip the backup for a

certain day. This CL program could be submitted to run the week of a holiday

to change the backup options to skip the backup on the holiday, and it could be

submitted to run again after that week to set the options back to normal. The

APIs could also be used to retrieve backup history about certain libraries,

folders, and so forth, in order to better tailor the backups to get the most effi-

cient backups.

Ÿ Retrieve Device Capabilities (QTARDCAP) API

This API is useful for a tape management system. The API returns information

about what capabilities your tape devices support.

Ÿ Save Object List (QSRSAVO) API

This API is useful to get a level of granularity from your save operations that

you cannot get by using the Save Object (SAVOBJ) command. The API allows

you to associate specific object names with specific object types instead of

saving the cross-product of all object names and object types entered on the

command.

Ÿ List Save File (QSRLSAVF) API

This API lists the contents of a save file into a user space. This is primarily for

those who develop backup and recovery applications.

Client Support APIs

The client support APIs include the client software management and configuration

APIs and exit programs.

The client software management and configuration section provides APIs to add,

remove, refresh, and update client information on the AS/400 database with the

information stored at the client. The client software management database formats

are affected by these APIs. For information about these formats, see the chapter

about client inventory management in the Simple Network Management Protocol

(SNMP) Support book, SC41-5412. The exit programs notify you when these API

functions have been completed.

 Copyright IBM Corp. 1997

8-1

Download from Www.Somanuals.com. All Manuals Search And Download.

With the exception of the Get Client Handle API, which is available only through the

Integrated Language Environment (ILE), the client software management and con-

figuration APIs are available as both the original program model (OPM) and ILE

APIs.

Ÿ Add Client (QZCAADDC, QzcaAddClient) API

To manage a client one must keep track of all clients on the network. This API

provides a convenient way of keeping track of clients. By calling this API, a

client is added to the database. If a client is SNMP-enabled and is set up in

such a way so as to send traps to the managing AS/400, the client is automat-

ically added to the AS/400 database. This API provides a way to add clients

that may not be SNMP-enabled.

Ÿ Remove Client (QZCARMVC, QzcaRemoveClient) API

This API provides a way to remove a client from the database for a client that

is no longer required to be managed.

Ÿ Refresh Client (QZCAREFC, QzcaRefreshClientInfo) API

If a client is SNMP-enabled, this API makes an attempt to get hardware and

software information from this client. Hardware information is retrieved from the

host resource management information base (MIB), and software information is

retrieved from both the Desktop Management Interface (DMI) and the host

resource MIB.

This information is also retrieved automatically when traps are received on the

managing AS/400 from its clients. Therefore, this API provides a way to force

a “refresh” of client information to keep information current.

Ÿ Update Client Information (QZCAUPDC, QzcaUpdateClientInfo) API

This API provides a way to update a few fields that are not updated with the

Refresh Client API.

Ÿ Get Client Handle (QzcaGetClientHandle) API

This API returns a handle, which is unique for every client known to AS/400.

As mentioned earlier, the interface to this API is only provided through a

service program.

Communications APIs

The user-defined communications APIs were created to provide users with the

ability to develop their own high-level communications protocol with as little system

interference as possible. While the system manages the lower-level protocol, the

user develops the upper layers of a protocol in any high-level programming lan-

guage supported by the AS/400. Several lower-level protocols are supported

including X.25, Ethernet Version 2, IEEE Ethernet, token ring, and fiber distributed

data interface (FDDI) (the selection of which is chosen by the user).

The APIs provide the ability to enable a link (that is, line, controller, and device),

disable a link, establish inbound routing information by setting service access points

(that is, filters), transmit and receive data, set timers, and query line descriptions.

The user-defined communications APIs are used primarily by users who have com-

munications needs not normally associated with the other existing communications

protocols, namely TCP/IP, SNA, or OSI. Applications that have been developed

8-2 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

using these APIs range from dedicated point-to-point file transfer to local-area-

network client/server applications.

OptiConnect APIs

The OptiConnect APIs are used to move user data between two or more AS/400

systems that are connected by the OptiConnect fiber-optic bus. The OptiConnect

APIs require that the OptiConnect hardware and software products have been

installed on all of the systems that will be used for communications. A maximum of

32KB (where KB equals 1024 bytes) of data may be transferred in a single send or

receive function.

Note: To use these APIs, you need the OptiConnect for OS/400 feature.

The OptiConnect APIs provide the following functions:

Ÿ Open and close an OptiConnect path

Ÿ Open and close an OptiConnect stream

Ÿ Send and receive a control message on an OptiConnect stream

Ÿ Send and receive a request or a message over an OptiConnect path

Ÿ Wait for a message on an OptiConnect stream

Configuration APIs

The configuration APIs can be used for the following functions:

Ÿ Change Configuration Description (QDCCCFGD) API

This API allows a user to modify the values of parameters on existing AS/400

configuration descriptions. The primary purpose of this API is to allow support

of new parameters or values as required, with their addition to the appropriate

CL configuration command deferred to a later time. A primary user of this level

of information would be user applications using new configuration capabilities

not yet available through CL commands.

Ÿ List Configuration Descriptions (QDCLCFGD) API

This API returns a list of configuration descriptions, based on a user-specified

set of criteria.

Ÿ Retrieve Configuration Status (QDCRCFGS) API

This API returns the current operational status of a specific configuration

description on an AS/400.

Several APIs also provide feedback of information for any controller description,

device description, and line description on an AS/400. The primary user of these

APIs would be user applications performing system or network management func-

tions on an AS/400. Separate formats are provided for each type of controller,

device, and line.

Debugger APIs

The debugger APIs can be used for program debugging on the AS/400 system.

The APIs are divided into separate sets of APIs, as follows:

Ÿ Integrated Language Environment (ILE) APIs

– Source debugger APIs

– Create view APIs

– Dump Module Variable API

Chapter 8. Use of OS/400 APIs 8-3

Download from Www.Somanuals.com. All Manuals Search And Download.

Ÿ Original program model (OPM) APIs

– Retrieve Program Variable API

You can use these sets of source debugger APIs independently of each other or

together as needed. The source debugger APIs can be used to write debuggers

for the AS/400 system. The users of these APIs include:

Ÿ The source debugger that is shipped with the OS/400 licensed program. A

source debugger is a tool for debugging Integrated Language Environment

(ILE) programs by displaying a representation of their source code.

Ÿ Any other debugger that IBM or a business partner writes.

Debugger functions are designed to help you write and maintain your applications.

You can run your programs in a special testing environment while closely observing

and controlling the processing of these programs in the testing environment. You

can write a debugger application that interacts with the debugger APIs, or you can

use the debugger provided with the AS/400 system.

All debugger APIs must be called within the job in which the Start Debug

(STRDBG) command is issued. The same program can be used at the same time

in another job without being affected by the debugger functions set up.

To enable source-level debugging of ILE programs, view information must be

stored with the compiled program. The ILE compilers use the create view APIs to

create view information. This information is then available to source-level debugger

applications through the source debugger APIs.

Dynamic Screen Manager APIs

The Dynamic Screen Manager (DSM) APIs are a set of screen I/O interfaces that

provide a dynamic way to create and manage screens for the Integrated Language

Environment (ILE) high-level languages. Because the DSM interfaces are bindable,

they are accessible to ILE programs only.

The DSM APIs provide an alternative to the existing way of defining screen appear-

ance outside a program by coding in data description specifications (DDS) or user

interface manager (UIM), for example. Instead, programmers can use a series of

calls to DSM within their programs to dynamically specify and control screen

appearance for their applications. Unlike static definition methods, the DSM inter-

faces provide the flexibility needed for those applications requiring more dynamic

screen control. The DSM support provided varies from low-level interfaces for

direct screen manipulation to windowing support.

The DSM APIs fall into the following functional groups:

Ÿ Low-level services

The low-level services APIs provide a direct interface to the 5250 data stream

commands. These APIs are used to query and manipulate the state of the

screen; to create, query, and manipulate input and command buffers used to

interact with the screen; and to define fields and write data to the screen.

Ÿ Window services

The window services APIs are used to create, delete, move, and resize

windows, and to manage multiple windows during a session.

8-4 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Ÿ Session services

The session services APIs provide a general scrolling interface that can be

used to create, query, and manipulate sessions, and to perform input and

output operations to sessions.

Edit Function APIs

The edit function APIs are used to create and use edit masks. An edit mask is a

byte string that tells the edit machine instruction or the Edit (QECEDT) API how to

format a numeric value into a readable character string.

An edit mask can format a numeric value so that languages that cannot directly use

machine instructions can now take advantage of this function. The edit mask was

previously defined by the Edit Code (EDTCDE) and Edit Word (EDTWRD)

keywords in DDS.

An edit code is a standard description of how a number should be formatted.

There are many standard edit codes defined by the system. Users can define

several edit codes the way they want with the use of the Create Edit Description

(CRTEDTD) command.

An edit word is a user-defined description of how a number should be formatted.

An edit word is usually used when one of the standard edit codes or user-defined

edit codes is not sufficient for a particular situation.

The Convert Edit Code (QECCVTEC) API converts an edit code specification into

an edit mask, and the Convert Edit Word (QECCVTEW) API converts an edit word

specification into an edit mask. The resulting edit mask along with the value to be

formatted are then passed to the Edit (QECEDT) API, which transforms the

numeric from its internal format to a character form for displaying.

File APIs

File APIs provide complete and specific information about a file on a local or

remote system. The file APIs include list, query, retrieve, and Structured Query

Language (SQL) APIs. The list APIs generate lists of the following:

Ÿ Database file members

Ÿ How files and members are related to a specified database file

Ÿ Fields within a specified file record format name

Ÿ Record formats contained within a specified file

The Query (QQQQRY) API is useful for querying requests whereby you want a

direct interface to OS/400 Query. The advantage of using the Query API is that

you are not limited by the function of any particular product interface. Also, you

can provide your own user interface and not be impeded by the extra code path

associated with an extra layer such as SQL. It is currently used only by more

expert programmers.

The Retrieve Display File (QDFRTVFD) API can be used to get complete and spe-

cific information about a display file. All the information that was in the data

description specifications (DDS) is returned in the output of the QDFRTVFD API.

By using the API, you can get specific field information for the display file.

Chapter 8. Use of OS/400 APIs 8-5

Download from Www.Somanuals.com. All Manuals Search And Download.

The Retrieve File Override Information (QDMRTVFO) API retrieves the name of the

file that will be referenced after file overrides have been applied to the file specified.

A user program can retrieve the actual name of the file that will be used when the

specified file is referenced.

SQL-related APIs process SQL extended dynamic statements in an SQL package

object and call the DB2 SQL for OS/400 parser to check the syntax of an SQL

statement.

Hardware Resource APIs

The hardware resource APIs allow you to work with hardware resources. A hard-

ware resource is an addressable piece of hardware on the system. A hardware

resource is known to the system by its resource name. A resource entry is the

reference to the hardware resource in the hardware resource information, which

can be thought of as a list of the hardware resources on the system.

The hardware resource APIs offer a more convenient means of accessing hardware

resource information than its output file alternative. The output file may contain a

great amount of information that is not needed by your application. The APIs,

however, are a means of getting specific bits of information. For example, assume

an application handles licensing of AS/400 information, and the application needs to

know the type number of the system processor card. This type number represents

the feature code of the system. To get this information previously, the application

created an output file through a CL program, read each record of the file until it

found the system processor card record, and then read the type field of this record.

With the APIs, the type field can be returned directly.

Hierarchical File System (HFS) APIs

The HFS APIs provide applications with a single, consistent interface to the file

systems registered with the hierarchical file system on your AS/400 system. The

APIs automatically support the document library services (QDLS) file system and

the optical file system (QOPT), and they can support user-written file systems also.

The HFS APIs allow you to work with nonrelational data stored in objects, such as

directories and files in existing file systems. Using these APIs, you can perform

such tasks as creating and deleting directories and files, reading from and writing to

files, and changing the directory entry attributes of files and directories.

High-Level Language APIs

The high-level language part consists of the Application Development Manager

APIs and the COBOL APIs.

Application Development Manager APIs

The Application Development Manager APIs allow a control language (CL)

command such as the Build Part (BLDPART) command to determine, for example,

the includes and external references that were used by certain processors (com-

pilers or preprocessors) when processing a source member.

In terms of Application Development Manager, a part can be either a source

member or an object, such as a file.

If you have an application that can use the information provided by the APIs, you

can call these APIs from any high-level programming language. The Application

8-6 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Development Manager feature does not need to be installed on your system for you

to use these APIs.

The Application Development Manager APIs are:

Ÿ Get Space Status

Ÿ Read Build Information

Ÿ Set Space Status

Ÿ Write Build Information

The Get and Set Status APIs are used to query and initialize the build information

space that is to contain the Application Development Manager information. The

Write and Read Build Information APIs are used to write or read records of build

information to and from the space.

COBOL APIs

These APIs let you control run units and error handling.

Integrated Language Environment (ILE) CEE APIs

The Integrated Language Environment (ILE) architecture on the OS/400 operating

system provides a set of bindable APIs known as ILE CEE APIs. In some cases

they provide additional function beyond that provided by a specific high-level lan-

guage. For example, not all high-level languages (HLL) offer intrinsic means to

manipulate dynamic storage. In these cases, you can supplement an HLL function

by using appropriate ILE CEE APIs. If your HLL provides the same function as a

particular ILE CEE API, use the HLL-specific one.

The ILE CEE APIs are useful for mixed-language applications because they are

HLL independent. For example, if you use only condition management ILE CEE

APIs with a mixed-language application, you will have uniform condition handling

semantics for that application. This uniformity can make condition management

easier than when using multiple HLL-specific condition handling models.

The ILE CEE APIs provide a wide-range of functions including:

Activation group and control flow management

Storage management

Condition management

Message services

Source debugger

Date and time manipulation

Math functions

Call management

Operational descriptor access

Naming Conventions of the ILE CEE APIs

Most ILE CEE APIs are available to any HLL that ILE supports. Naming con-

ventions of the ILE CEE APIs are as follows:

Ÿ Bindable API names starting with CEE are intended to be consistent across the

IBM SAA systems.

Ÿ Bindable API names starting with CEE4 are specific to AS/400.

Chapter 8. Use of OS/400 APIs 8-7

Download from Www.Somanuals.com. All Manuals Search And Download.

Journal and Commit APIs

This section includes the journal and commitment control APIs.

Journal APIs

The journal APIs allow you to:

Ÿ Obtain information about some of the journal’s attributes or the journal

receiver’s attributes

Ÿ Obtain journal information based on the journal identifier

Ÿ Send an entry to specified journal

Commitment Control APIs

The commitment control APIs allow you to:

Ÿ Add and remove your own resources to be used during AS/400 system commit

or rollback processing

Ÿ Retrieve information about the commitment control environment

Ÿ Change commitment control options

Ÿ Put a commitment definition into rollback-required state

Message Handling APIs

On the AS/400, communications between programs, between jobs, between users,

and between users and programs occurs through messages. The message han-

dling APIs allow your application to work with these messages. The APIs consist of

the following groups of functions:

Ÿ Send different types of messages to users and programs

This would be done to communicate the status of an action that is about to

occur or one that has been completed. You can also ask a question and wait

for a response to it.

Ÿ Receive a message from a message queue

This would be done to determine what action occurred, for example, to deter-

mine whether a function completed successfully (your program can continue) or

failed.

Ÿ Handle errors that occur

This is done to allow your application to tolerate errors that occur. For

example, you can move and resend messages to another program for appro-

priate action. Or perhaps you expected the error, and you can just remove the

message and continue.

Ÿ Return message or message queue information

This is done to find attributes (for example, current delivery mode or severity) of

a message queue or to return one or more messages on a message queue.

Ÿ Return message description or message file information

This is done to find attributes of a message file or to return the actual

description of a message in a message file.

Detailed information about these concepts and functions can be found in the CL

Programming book, SC41-5721.

8-8 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

National Language Support APIs

These APIs provide the capability to retrieve cultural values, to convert sort

sequence to different CCSIDs, to convert and truncate character strings, and to

work with data that uses CCSIDs.

National Language Support APIs

This set of APIs gives you the capability to work with language IDs, sort sequence

tables, and single- or double-byte character string data. The sort API allows a sort

using a national language sorting sequence.

This set also includes an API that converts all characters to either uppercase or

lowercase.

National Language Data Conversion APIs

This set of APIs provides the capability to convert character data from one CCSID

to another.

Character Data Representation Architecture (CDRA) APIs

These APIs are part of the Character Data Representation Architecture that allows

access to the system CCSID support.

Network Management APIs

Network management APIs give you the capability to manage one or more nodes

from another node. The network management section consists of the following

groups of APIs:

Ÿ Advanced Peer-to-Peer Networking (APPN) topology

Ÿ SNA/Management Services Transport

Ÿ Alert

Ÿ Node list

Ÿ Registered filter

Ÿ Change request management

Advanced Peer-to-Peer Networking (APPN) Topology Information

APIs

APPN topology information APIs allow an application to obtain information about

the current APPN topology, and to register and deregister for information about

ongoing updates to the topology. The specific types of topology updates that an

application may register to receiver follow:

Ÿ Network network node (*NN) updates

Ÿ Network virtual node (*VN) updates

Ÿ Local end node (*EN) updates

Ÿ Local virtual node (*VN) updates

APPN network topology identifies the following in an APPN subnetwork. (An APPN

subnetwork consists of nodes having a common network ID and the links con-

necting those nodes.)

Ÿ All network nodes and virtual nodes in the subnetwork

Ÿ Transmission groups interconnecting network nodes and virtual nodes in the

subnetwork

Ÿ Transmission groups from network nodes in the subnetwork to network nodes

in adjacent subnetworks

Chapter 8. Use of OS/400 APIs 8-9

Download from Www.Somanuals.com. All Manuals Search And Download.

The APPN local topology for an APPN node consists of the following:

Ÿ The local node

Ÿ Adjacent nodes (network nodes, end nodes, or virtual nodes to which the local

node has a direct connection)

Ÿ Transmission groups from the local node to adjacent nodes

Both end nodes and network nodes can report local topology updates; however,

network topology updates can be reported only on a network node system.

SNA/Management Services Transport (SNA/MS Transport) APIs

Systems Network Architecture Management Services Transport (SNA/MS Trans-

port) functions are used to support the sending and receiving of management ser-

vices data between systems in an SNA network. The network can include AS/400

systems, Operating System/2 and NetView licensed programs, and other platforms

that support the SNA/MS architecture.

The SNA/MS functions provided on the AS/400 system include:

Ÿ The transport of network management data in APPN networks

Ÿ The maintenance of node relationships for network management

The APIs allow a network management application running on one system to send

data to and receive data from a network management application running on

another system in an APPN network. The APIs are a callable interface that allow

the application to be notified about asynchronous events, such as incoming data,

by way of a notification placed on a data queue.

Some examples of IBM applications that use SNA/MS Transport APIs are:

Ÿ Alerts

Ÿ Problem reporting

Ÿ Remote problem analysis

Ÿ Program temporary fix (PTF) ordering

In large networks, the number of sessions needed to support the various network

management applications could become burdensome without session concen-

tration. SNA/MS Transport APIs reduce the number of SNA LU 6.2 sessions that

would normally be used to transmit data. This support multiplexes or transmits all

of the network management data from all the applications in a network node

domain (network node and attached end nodes) on a single session to applications

in another domain.

This means that data transmitted from an end node is always sent to its network

node server first. Then, the SNA/MS Transport support on the network node server

routes the data to its proper destination.

Alert APIs

The alert APIs let your application create alerts, notify the OS/400 alert manager of

alerts that need to be handled, and allow you to retrieve alerts and alert data. The

generate and send APIs differ from ordinary AS/400 alert processing in that they let

your application create an alert at any time without sending an alertable message

to an alertable message queue. (An alertable message queue is a message queue

that has been created or changed with the allow alerts (ALWALR) parameter speci-

8-10 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

fied as yes.) The retrieve API allows your application, in conjunction with alert fil-

tering, to perform user-defined actions based on the contents of the alert.

Node List API

A node list is either or both of the following:

Ÿ A list of SNA nodes (network ID and control point name)

Ÿ Internet protocol nodes (internet address or host name)

You can use node lists for grouping systems by any criteria that you may need for

your own applications. For example, the entries you put in a node list could be for

systems at a certain hardware level. The List Node List Entries (QFVLSTNL) API

is used to get the entries from the node list for use in your applications.

Registered Filter APIs

A filter is a function you can use to assign events into groups and to specify

actions to take for each group. The registered filter APIs allow a product to register

a filter with the operating system. The product can receive notification of events

recorded in a data queue by using the Send to Data Queue (SNDDTAQ) action of

the Work with Filter Action Entry (WRKFTRACNE) command.

A user filter is the filter defined by the network attributes for alert filtering and by the

system value for problem log filtering. A user filter and a registered filter differ in

their function and their notification record. There can only be one user filter active

at one time for each type of filter, but there can be multiple registered filters active

at one time. All actions are active for a user filter, but only the SNDDTAQ action is

active for a registered filter.

A product can use registered filter APIs for the following purposes:

Ÿ To register multiple filters at the same time for each event type (alert or

problem log)

Ÿ To deregister a filter when notifications from that filter are no longer necessary

Ÿ To retrieve all the filters that are registered

The event notification record for a registered filter differs from notification records

for other types of filters. The registered notification contains a common header for

all events, as well as specific information based on the type of event. The common

header includes the name of the notification, a function type, a format, the filter

name and library, the group name, and a timestamp. The specific information for

the problem log includes the problem ID, the last event logged, and the timestamp

for the last event.

Change Request Management APIs

This group of APIs can be used to add, remove, and list activities and to retrieve

change request descriptions.

Object APIs

The object APIs consist of the following groups.

Chapter 8. Use of OS/400 APIs 8-11

Download from Www.Somanuals.com. All Manuals Search And Download.

Data Queue APIs

Data queues are a type of system object that you can create, to which one high-

level language (HLL) program can send data, and from which another HLL program

can receive data. The receiving program can be waiting for the data, or can

receive the data later.

The advantages of using data queues are:

Ÿ Using data queues frees a job from performing some work. If the job is an

interactive job, the data queue APIs can provide better response time and

decrease the size of the interactive program and its process activation group

(PAG). This, in turn, can help overall system performance. For example, if

several work station users enter a transaction that involves updating and

adding to several files, the system can perform better if the interactive jobs

submit the request for the transaction to a single batch processing job.

Ÿ Data queues are a fast means of asynchronous communication between two

jobs. Using a data queue to send and receive data requires less system

resource than using database files, message queues, or data areas to send

and receive data.

Ÿ You can send to, receive from, and retrieve a description of a data queue in

any HLL program. This is done by calling the Send to a Data Queue

(QSNDDTAQ), Receive from Data Queue (QRCVDTAQ), Retrieve Data Queue

Message (QMHRDQM), Clear Data Queue (QCLRDTAQ), and Retrieve Data

Queue Description (QMHQRDQD) APIs.

Ÿ When receiving data from a data queue, you can set a time-out such that the

job waits until an entry arrives on the data queue. This is different from using

the EOFDLY parameter on the Override Database File (OVRDBF) command,

which causes the job to be activated whenever the delay time ends.

Ÿ More than one job can receive data from the same data queue. This is an

advantage in certain applications where the number of entries to be processed

is greater than one job can handle within the desired performance restraints.

For example, if several printers are available to print orders, several interactive

jobs could send requests to a single data queue. A separate job for each

printer could receive data from the data queue in first-in-first-out (FIFO), last-in-

first-out (LIFO), or keyed-queue order.

Ÿ Data queues have the ability to attach a sender ID to each message being

placed on the queue. The sender ID, an attribute of the data queue that is

established when the queue is created, contains the qualified job name and

current user profile.

Comparisons with Using Database Files as Queues: The following describes

the differences between using data queues and database files:

Ÿ Data queues have been improved to communicate between active programs,

not to store large volumes of data or large numbers of entries. For these pur-

poses, use database files as queues.

Ÿ Data queues should not be used for long-term storage or indefinite retention of

data. For this purpose, you should use database files.

Ÿ When using data queues, you should include abnormal end procedures in your

programs to recover any entries not yet completely processed before the

system is ended.

8-12 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Ÿ It is good practice to periodically (such as once a day) delete and re-create a

data queue at a safe point. Performance can be affected if too many entries

exist without being removed. Re-creating the data queue periodically will return

the data queue to its optimal size.

Similarities to Message Queues: Data queues are similar to message queues, in

that programs can send data to a queue and that data can be received later by

another program. However, more than one program can have a receive operation

pending on a data queue at the same time, while only one program can have a

receive operation pending on a message queue at the same time. (Only one

program receives an entry from a data queue, even if more than one program is

waiting.) Entries on a data queue are handled in either first-in first-out,

last-in-first-out, or keyed-queue order. When an entry is received, it is removed

from the queue.

User Queue APIs

The user queue APIs let you create and delete user queues. User queues are

permanent objects with an object type of *USRQ. They provide a way for one or

more processes to communicate asynchronously.

You can use user queues to:

Ÿ Communicate between two processes asynchronously

Ÿ Store data in arrival sequence for later use

Ÿ Contain keyed messages

Ÿ Create a batch machine

Ÿ Permit better performance than the data queue interface

You can save and restore user queues. However, you can only save or restore its

definition. You cannot save or restore the messages in it. You cannot restore a

user queue if a user queue with the same name already exists in the library. You

must provide programs to use this object type to enqueue and dequeue messages.

User Index APIs

The user index APIs allow you to:

Ÿ Create and delete user indexes

Ÿ Add, retrieve, and remove user index entries

Ÿ Retrieve the attributes of a user index

A user index is an object that allows search functions for data in the index and

automatically sorts data based on the value of the data. User indexes are perma-

nent objects in the user domain or in the system domain. They have an object type

of *USRIDX and a maximum size of 4 gigabytes (4 294 967 296 bytes). They

help streamline table searching, cross-referencing, and ordering of data. In

general, if your table is longer than 1000 entries, an index performs faster than a

user-sorted table.

You can use user indexes to:

Ÿ Provide search functions

Ÿ Do faster insert operations than in a database file

Ÿ Do faster retrieve operations than in a database file

Ÿ Create an index by name, such as a telephone directory

Ÿ Use order entry programs

Ÿ Look up abbreviations in an index

Chapter 8. Use of OS/400 APIs 8-13

Download from Www.Somanuals.com. All Manuals Search And Download.

Ÿ Sort data automatically based on the hexadecimal value of a key

For more information about user index considerations, refer to “User Index

Considerations” on page 2-30. User index entries cannot contain a pointer. You

can save and restore all the data in an index. You can also save and restore user

indexes to another system.

User Space APIs

You can use these APIs to:

Ÿ Create and delete user spaces

Ÿ Change and retrieve the contents of user spaces

Ÿ Change and retrieve information about user spaces

User spaces are objects that consist of a collection of bytes used for storing user-

defined information. They are permanent objects that are located in either the

system domain or the user domain. They have an object type of *USRSPC and a

maximum size of 16MB. You can save and restore user spaces to other systems.

However, if the user spaces contain pointers, you cannot restore the pointers even

if you want to restore them to the same system.

You can use the user space APIs to:

Ÿ Create user spaces to be used by list APIs to generate lists of data.

Ÿ Store pointers.

Ÿ Store large amounts of data. You can create a user space as large as 16MB.

You cannot create a data area larger than 2000 bytes.

Ÿ Save information in user space objects, and save and restore the object with

the information in it using CL commands.

Ÿ Pass data from job to job or from system to system.

Object APIs

Use of the object APIs is described as follows:

Ÿ Change Library List (QLICHGLL) API

This API provides the only way to change the product libraries in the library list.

The only other way to change the product libraries is using the Create

Command (CRTCMD) or the Create Menu (CRTMNU) command. You can

also use this API to change the current library and the libraries in the user part

of the library list similar to the Change Library List (CHGLIBL) command.

Ÿ Change Object Description (QLICOBJD) API

Unlike the Change Object Description (CHGOBJD) command, this can be used

on all external object types. This API supports changing more parts of the

object descriptive information than are supported using the CHGOBJD

command.

Ÿ Convert Type (QLICVTTP) API

This API is the only supported way to convert a symbolic type to hexadecimal

format and vice versa.

Ÿ List Objects (QUSLOBJ) API

This API returns information similar to the Display Object Description

(DSPOBJD) command. An advantage over the DSPOBJD command is that

you can perform authority checking on the objects and libraries. You can get a

8-14 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

list of objects with only a certain status, which you cannot do with the

DSPOBJD command.

Ÿ Rename Object (QLIRNMO) API

This API combines the functions of the Rename Object (RNMOBJ) and the

Move Object (MOVOBJ) commands. The API allows you to rename and move

in one step, and replace the existing target.

Ÿ Retrieve Library Description (QLIRLIBD) API

This API returns the number of objects in a library and the library size. Cur-

rently, the only other function that does this is the Display Library (DSPLIB)

command with OUTPUT(*PRINT). Without this API, the user would have to

generate a list of objects, using the Display Object Description (DSPOBJD)

command, to an output file (or use the QUSLOBJ API), and then count the

number of objects and total the size of the objects (and include the size of the

*LIB object itself).

Ÿ Retrieve Object Description (QUSROBJD) API

This API returns the same information as the Retrieve Object Description

(RTVOBJD) command.

Office APIs

Descriptions of the office APIs follow:

Ÿ Display Directory Panels (QOKDSPDP) API

This API can be called to change the system distribution directory interactively

without using the OfficeVision administration interface.

Ÿ Display Directory X.400 Panels (QOKDSPX4) API

This API adds an X.400 O/R name if one does not exist for a user. Also, the

ability to display the O/R name is given. This API is for interactive use only

and is useful if you want to add an X.400 O/R name to the directory interac-

tively or to display an X.400 O/R name interactively.

Ÿ Search System Directory (QOKSCHD) API

This API gives the ability to search any fields in the system distribution directory

and return specified fields for each user that matches the search criteria. It

also is used to query the actual fields that exist in the system distribution direc-

tory. It is most useful when the system distribution directory is used as a

repository for information about users, and can be used in a program to query

this information.

Other office APIs check spelling, and work with the document handling and docu-

ment conversion exit programs, which are discussed under “Office Exit Programs”

on page 8-16.

AnyMail/400 Mail Server Framework APIs

These APIs are used by those who are writing support for specific electronic mail

(E-mail) server functions on the AS/400. An E-mail framework (the mail server

framework or MSF), part of AnyMail/400, was added at Version 3 Release 1.

One API allows programs to create E-mail-related messages (MSF messages) that

are then processed as part of this framework. The framework has a series of exit

points that allow someone to plug in their own programs that are called when the

Chapter 8. Use of OS/400 APIs 8-15

Download from Www.Somanuals.com. All Manuals Search And Download.

MSF framework processes its messages. These exit programs perform E-mail-

related functions and are passed information about the MSF message. These exit

programs can use two other APIs to retrieve or change part of the MSF message.

The remaining APIs are used to configure information to the MSF framework that it

uses to tag and identify the parts of an MSF message. There are APIs to add,

remove, and list these MSF-data-type definitions as part of MSF's configuration.

SNADS File Server APIs

You would use these APIs if you were dealing with AnyMail/400 mail server frame-

work (MSF) messages that contained SNADS attachments. You would use the file

server object read API if the MSF message was originated by OfficeVision or object

distribution. You would use the create and write APIs if the MSF message was

destined for an OfficeVision user or an object distribution user, or if you want to

temporarily store attachments.

Office Exit Programs

Descriptions of the office exit programs follow:

Ÿ Directory Search exit program

This exit program is provided for those who want the ability to search other files

that contain user information. For example, when in OfficeVision and a user is

on the Search System Directory display, if this exit program is provided, the

F10 key is provided to call this exit program and as a result return the user ID

and address.

Ÿ Directory Supplier exit program

This exit program is provided for system distribution directory shadowing. It

provides the ability to prevent add, change, and delete operations of select data

from being supplied to a collector system. The advantages this provides is

additional security to allow other systems on the network to see only the data

you want them to see. It also gives you a way to provide partial replication

through shadowing.

Ÿ Directory Verification exit program

This exit program is provided to verify data that is being added, changed, and

deleted in the system distribution directory. It is called for when data is directly

being changed on the system and also when data is being changed through

shadowing. This gives you the ability to verify that data is valid for specific

fields (like telephone number format). It also gives you the added security of

ensuring that the systems changing your data are authorized to do so. You

could also use this exit program to provide partial replication for data that has

already been sent from the other systems.

Ÿ Document Conversion exit program

This exit program allows other document conversion programs to be called

when a request is made for the OfficeVision program to process a document

that is an unsupported type.

Ÿ Document Handling exit program

This exit program allows other editors and applications to be called from the

OfficeVision word processing and print functions.

Ÿ User Application Administration exit program

8-16 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

This exit program passes control to the application enabler where a registered

alternate administration program will be called.

Operational Assistant APIs

Most functions on the AS/400 Operational Assistant menu can be accessed individ-

ually by calling APIs found in the QSYS library. The Operational Assistant APIs

allow you to incorporate Operational Assistant functions into your application

menus.

For information about the Operational-Assistant backup APIs, see “Backup and

Recovery APIs” on page 8-1.

You can also tailor some of the Operational Assistant functions to your needs by

using Operational Assistant exit programs.

Performance Collector APIs

The performance collector APIs allow applications to be developed that provide

real-time performance monitoring capabilities. As with all APIs, this can be done

without the overhead of databases or spooled files, and through a hardened inter-

face. This is in contrast to the performance monitor, which collects much more

information and retrieves its data much less frequently to database files. That is, in

real-time, you have more control over collecting just the type of data you are inter-

ested in.

Print APIs

The print APIs consist of the following:

Ÿ Print APIs

Ÿ Spooled file APIs

Ÿ Exit programs

Print APIs

Print APIs can obtain information about or perform printing activities on the AS/400

system. Print APIs can:

Ÿ Retrieve output queue information such as status and number of entries on the

queue.

Ÿ Retrieve information about specific printer writers.

Ÿ Transform data streams from one type to another.

The following discussion pertains to specific print APIs.

The AFP to ASCII Transform (QWPZTAFP) API converts an Advanced Function

Printing data stream (AFPDS) into an ASCII printer data stream. The ASCII printer

data streams supported are the printer control language Hewlett Packard**

LaserJet**, Personal Printer Data Stream level 3 and 4 (IBM 4019, 4029), and

PostScript** data stream. The API can be useful to anyone who wants to print AFP

documents to lower-cost ASCII printers.

The Host Print Transform (QWPZHPTR) API converts an AFP data stream or an

SNA-character-string (SCS) data stream to an ASCII data stream. The Host Print

Transform API can be used as an alternative to printer emulation in the following

situations to transform AFPDS and SCS data streams to ASCII data streams:

Chapter 8. Use of OS/400 APIs 8-17

Download from Www.Somanuals.com. All Manuals Search And Download.

Ÿ Twinaxial ASCII printing

Ÿ LAN ASCII printing

Ÿ TCP/IP printing through the Send TCP/IP Spooled File command (known as

LPR or line printer requester in UNIX TCP/IP)

The API provides a programming interface to the same transform.

The QWPZHPTR API goes along with another function, the Print Driver exit

program. This exit program allows you to create your own print driver program.

For example, the system provides a print driver to communicate to LAN-attached

printers through the LexLink protocol. This print driver uses the host print transform

to convert the SNA-character-string spooled files or AFP spooled files to ASCII

before sending them to the printer.

With the QWPZHPTR API, you can write your own print driver (maybe to communi-

cate over a protocol other than LexLink), but still use the system-provided transform

(host print transform).

Spooled File APIs

Spooled file APIs obtain specific information about spooled files. For example,

spooled file APIs can:

Ÿ Return a list of spooled files based on given selection criteria, such as a user

or an output queue.

Ÿ Provide functions to access a specific spooled file from which the API can

return the attributes and data of a spooled file or create a duplicate of a specific

spooled file.

Spooled file APIs are useful in writing applications to clean up, save, and restore

spooled files.

Problem Management APIs

The problem management APIs offer you the ability to write problem management

solutions, improve serviceability, and manage your own applications. Problem

management APIs deal directly with how the AS/400 handles problems today.

Today, the problem log provides most of the operations necessary for problem

management in a network environment. These APIs have several capabilities:

Filtering

A filter categorizes problem log entries into groups and performs operations on

them accordingly.

The problem log applies the currently active filter to a problem log entry whenever a

problem entry is created, changed, or deleted using system-provided interfaces.

The operations supported allow you to send application notification to a user data

queue and assign the problem to a user. Your application can receive these notifi-

cations from the data queue using existing APIs.

8-18 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Working with a Problem

Problem analysis is the process of finding the cause of a problem and identifying

why the system is not working. Often this process identifies equipment or data

communications functions as the source of the problem. The Work with Problem

(QPDWRKPB) API allows you to perform problem analysis on local machine-

detected problems in the problem log. The Work with Problem (QPDWRKPB) API

prepares the problem in the problem log for reporting; it does not report the

problem automatically.

Problem Log Entry APIs

The following set of problem management APIs are for designing problem log appli-

cations.

Ÿ Add Problem Log Entry (QsxAddProblemLogEntry)

Ÿ Change Problem Log Entry (QsxChangeProblemLogEntry)

Ÿ Create Problem Log Entry (QsxCreateProblemLogEntry)

Ÿ Delete Problem Log Entry (QsxDeleteProblemLogEntry)

Ÿ End Problem Log Services (QsxEndProblemLogServices)

Ÿ Retrieve Problem Log Entry (QsxRetrieveProblemLogEntry)

Ÿ Start Problem Log Services (QsxStartProblemLogServices)

Error Reporting APIs

The following set of problem management APIs log software problems.

Ÿ Log Software Error (QPDLOGER) reports a software problem and collects data

needed for its resolution.

Ÿ Report Software Error (QpdReportSoftwareError) logs problems in the problem

log and sends it to a service provider.

Program and CL Command APIs

You can use these APIs to do the following:

Ÿ Create programs

Ÿ List program or service program information

Ÿ Retrieve program or service program information

Ÿ Activate service programs

Ÿ Manipulate entries in the associated space of a program

Ÿ Handle compiler preprocessor-related tasks

Ÿ Resolve a pointer to an export

Ÿ Scan a string of characters for a pattern

Ÿ Execute a CL command or run a command from within an HLL or CL program

You can use the Create Program (QPRCRTPG) API to write your own assembler

or compiler. When the assembler or compiler has created the machine interface

template, this API is used to create the program from it.

Registration Facility APIs

The registration facility is a service that provides storage and retrieval operations

for OS/400 and non-OS/400 exit points and exit programs. An exit point is a spe-

cific point in a system function or program where control may be passed to one or

more specified exit programs. An exit program is a program to which control is

passed from an exit point. This registration facility repository allows multiple

programs to associate with a given system function or application function.

Chapter 8. Use of OS/400 APIs 8-19

Download from Www.Somanuals.com. All Manuals Search And Download.

The registration facility APIs provide the capability to:

Ÿ Register and deregister exit points with the registration facility

Ÿ Add and remove exit programs to and from the repository

Ÿ Retrieve exit point and exit program information from the repository

Ÿ Designate the order in which exit programs should be called

An exit point can call one program, a fixed number of programs, or all programs

associated with an exit point. The exit program number associated with each exit

program should be used to determine the sequence in which the exit programs are

run.

An exit point can be registered multiple times with the same exit point name;

however, the combination of the exit point name and the exit point format name

must be unique. Each exit program will be associated with a specific exit point and

exit point format. The exit point format name can be used to indicate that a change

occurred to the interface of the exit point. For example, this unique name (exit

point and format) could be the result of a parameter change, version change, exit

program data definition, and so forth. This unique name will facilitate having dif-

ferent exit programs run from different versions of a product for the same exit point

name.

Security APIs

The OS/400 security APIs allow you to:

Ÿ Perform many of the security functions through a program interface. You can

use APIs instead of CL commands.

Ÿ Combine many individual jobs into a single server or overhead job without com-

promising system security.

Network Security APIs

The OS/400 network security APIs provide a means that automatically logs you on

to a server when you request a NetWare** function (for example, file or print). You

can create authentication entries for each NetWare Directory Services** (NDS**)

tree or NetWare 3.x server to which you are authorized. The entry identifies the

tree or server, your name on that server, and (optionally) your password. When

you request a NetWare function, the system attempts to start a connection to the

server by using this data.

Note: To use these APIs, you need the Enhanced NetWare Integration for OS/400

feature.

Software Product APIs

The software products APIs were created to provide the user with the ability to

package and manage their product in a manner similar to the way IBM licensed

programs are managed. OS/400 commands along with these APIs allow you to

work with and create program temporary fixes (PTFs), to package and distribute

products, and to manage software licenses.

For more details on managing a product, see the System Manager Use book,

SC41-5321. The System Manager for AS/400 licensed program can be used to

facilitate managing your products.

8-20 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

The CD-ROM premastering APIs could be used if you currently produce distributed

systems license option (DSLO) distribution tapes at a central site. If you would now

like to distribute on CD-ROM rather than tape, you would use the CD-ROM pre-

mastering APIs.

You would use the Handle CD-ROM Premastering State (QlpHandleCdState or

QLPCDRST) API to place your job into a CD-ROM premastering state. While in

this state, any save operations performed will have information about the tape file

sizes stored away for future use in generating the QDSETMAP file. In the case of

a SAVSYS or option 40 (Create Distribution Tape) on the Work with Licensed Pro-

grams menu, special files are saved to tape so that the CD-ROM volumes

produced can be used for installation.

When the save operations have been performed, you would then use the Generate

CD-ROM Premastering Information (QlpGenerateCdPremasteringInfo or

QLPCDINF) API. This API is used to analyze the tape file size information stored

away during the previous API and produce a byte-stream file that contains informa-

tion about which CD-ROM volumes these files will reside on. Information is also

returned into a user space that is useful in producing a mastering control file that

may be necessary when having the CD-ROMs mastered.

UNIX-Type APIs

The UNIX-type APIs are intended for experienced UNIX programmers who want to

do either of the following:

Ÿ Create new application programs that run on the AS/400

Ÿ Create an AS/400 version of existing application programs that run on other

UNIX-based systems

The UNIX-type APIs consist of the following groups.

Environment Variable APIs

Environment variables are character strings of the form name=value that are

stored in an environment space outside of the program. The strings are stored in a

temporary space associated with the job.

Environment variables can be set using the putenv() or Qp0zPutEnv() function.

They can be retrieved using the getenv() or Qp0zGetEnv() function. The putenv()

and getenv() functions are designed to meet the X/Open** single UNIX specifica-

tion (formerly Spec 1170). The Qp0zPutEnv() and Qp0zGetEnv() functions are

AS/400 extensions to the industry-standard APIs. They provide the additional

capability to store or retrieve a coded character set identifier (CCSID) associated

with the string.

After environment variables are set, they exist for the duration of the job. There is

no way to remove an environment variable. However, the value can be set to

NULL by using a subsequent call to putenv() or Qp0zPutEnv() and specifying a

value of NULL.

The OS/400 support for environment variables does differ from the usual behavior

of environment variables on UNIX systems:

Ÿ There is no default set of environment variables provided when a job starts.

On the AS/400, the environ array, which points to the environment variable

Chapter 8. Use of OS/400 APIs 8-21

Download from Www.Somanuals.com. All Manuals Search And Download.

strings, is NULL (not initialized) until environment variables are associated with

the job.

Ÿ On a UNIX system, the exec() function creates a new process and extends the

environment variables of the original process to the new process. Although the

AS/400 has no exec() function, environment variables are extended to a new

job created using the Submit Job (SBMJOB) command, provided the first job

has environment variables.

To help alleviate these differences, OS/400 provides several nonstandard interfaces

that can be used to establish a default set of environment variables.

Ÿ The Add Environment Variable (ADDENVVAR) CL command can be used to

set an environment variable for a job. Further, a CL program can be written

using the ADDENVVAR command that sets several environment variables for a

job. Alternatively, the putenv() or Qp0zPutEnv() function can be used in a

similar manner in a C program.

Ÿ Other environment variable CL commands, Change Environment Variable

(CHGENVVAR) and Work with Environment Variables (WRKENVVAR), or C

functions can be used to change or retrieve environment variables for a job.

Integrated File System APIs

The integrated file system is a part of OS/400 that supports stream input/output and

storage management similar to personal computer and UNIX operating systems.

The stream file support is designed for efficient use in client/server applications.

Stream files are particularly well suited for storing strings of data such as the text of

documents, images, audio, and video.

The integrated file system provides a hierarchical directory structure that supports

UNIX-based open system standards, such as POSIX** and XPG. This file and

directory structure provides the users of PC operating systems with a familiar envi-

ronment. The integrated file system takes better advantage of the graphical user

interface.

In addition to providing a common interface for users and application to access

stream files, the integrated file system also provides access to database files, docu-

ments and other objects stored on the AS/400.

The integrated file system APIs can perform operations on directories, files, and

related objects in the file systems accessed through the integrated file system inter-

face. For more information about the integrated file system, see the Integrated File

System Introduction book, SC41-5711.

Interprocess Communication APIs

Interprocess communication (IPC) on the AS/400 is made up of three services:

message queues, semaphores, and shared memory. The basic purpose of these

services is to provide OS/400 processes with a way to communicate with each

other through a set of standardized APIs. These C-language functions are based

on the definitions in the X/Open single UNIX specification (formerly Spec 1170).

Message queues provide a form of message passing in which any process (given

that it has the necessary permissions) can read a message from or write a

message to any message queue on the system. There are no requirements that a

process be waiting to receive a message from a queue before another process

8-22 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

sends one, or that a message exist on the queue before a process requests to

receive one.

A semaphore is a synchronization mechanism similar to a mutex or a machine

interface (MI) lock. It can be used to control access to shared resources, or used

to notify other processes of the availability of resources.

Processes can communicate directly with one another by sharing parts of their

memory space and then reading and writing the data stored in the shared

memory. Synchronization of shared memory is the responsibility of the application

program. Semaphores can be used to synchronize shared memory use across

processes. Mutexes or condition variables can be used to synchronize shared

memory use across threads.

Although each IPC service provides a specific type of interprocess communication,

the three services share many similarities. Each service defines a mechanism

through which its communications take place. For message queues, that mech-

anism is a message queue; for semaphores, it is a semaphore set; and for shared

memory, it is a shared memory segment. These mechanisms are identified by a

unique positive integer, called, respectively, a message queue identifier (msqid), a

semaphore identifier (semid), and a shared memory identifier (shmid).

Associated with each identifier is a data structure that contains state information for

the IPC mechanism, as well as ownership and permissions information. This struc-

ture is similar to a file permissions structure, and is initialized by the process that

creates the IPC mechanism. It is then checked by all subsequent IPC operations

to determine if the requesting process has the required permissions to perform the

operation.

To get an identifier, a process must either create a new IPC mechanism or access

an existing mechanism. This is done through the msgget(), semget(), and

shmget() functions. Each get operation takes as input a key parameter and

returns an identifier. Each get operation also takes a flag parameter. This flag

parameter contains the IPC permissions for the mechanism as well as bits that

determine whether or not a new mechanism is created.

When a message queue, semaphore set, or shared memory segment is created,

the process that creates it determines how it can be accessed. Subsequent IPC

operations do a permission test for the calling process before allowing the process

to perform the requested operation.

Signal APIs

An X/Open** specification defines a signal¹as “a mechanism by which a process

may be notified of, or affected by, an event occurring in the system.” The term

signal is also used to refer to the event itself.

A signal is said to be generated when the event that causes the signal first occurs.

Examples of such events include the following:

Ÿ System-detected errors

Ÿ Timer expiration

X/Open CAE Specification System Interface Definitions Issue 4, Number 2, Glossary, page 27. X/Open Company Ltd., United

Kingdom, 1994.

Chapter 8. Use of OS/400 APIs 8-23

Download from Www.Somanuals.com. All Manuals Search And Download.

Ÿ Terminal (work station) activity

Ÿ Calling an API such as the X/Open kill() function, the American National

Standard C raise() function, or the ILE CEESGL (signal a condition) function.

The signal action vector is a list of signal-handling actions for each defined signal.

The signal action vector is maintained separately for each process and is inherited

from the parent process. The signal action vector specifies the signal-handling

actions for both synchronously and asynchronously generated signals.

A signal is said to be delivered to a process when the specified signal-handling

action for the signal is taken.

The following describes some of the support provided by OS/400 signal manage-

ment. The set of defined signals is determined by the system. The system speci-

fies the attributes for each defined signal. These attributes consist of a signal

number, the initial signal action, and the signal default action. The system also

specifies an initial signal blocking mask. The set of defined signals, the signal attri-

butes, and signal blocking mask are referred to as signal controls.

A signal can be generated or delivered only to a process that has expressed an

interest in signals. An error condition results under the following conditions:

Ÿ An attempt is made to generate a signal when the system signal controls have

not been initialized.

Ÿ An attempt is made to generate a signal for a process that has not been

enabled for signals.

A process can express an interest in signals by calling the Qp0sEnableSignals()

API. In addition, calling particular signal APIs implicitly enables the process for

signals.

If the process has not been enabled for signals, the process signal controls are set

from signal controls established by the system during IPL (the system signal con-

trols). An error condition results if an attempt is made to enable signals for the

process before the system signal controls have been initialized.

Once the process signal controls have been initialized, the user is permitted to

change the signal controls for the process.

The attributes for each defined signal are stored in an object called a signal

monitor. The system supports a maximum of 63 signal monitors for each process.

The process signal action vector is a list of signal monitors, one for each defined

signal. The signal monitor contains, but is not limited to, the following information:

Ÿ Signal action

Ÿ Signal default action

Ÿ Signal options

The signal action defines the action to be taken by the system when a process

receives an unblocked signal. The user can change the signal action for a process

signal monitor.

The signal default action field defines the action to be taken by the system when

the signal action is set to handle using signal default action. The signal default

action for a signal monitor is set in the system signal controls and cannot be

changed for a process signal monitor.

8-24 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

The signal options specify an additional set of attributes for the signal monitor.

The primary use of these options is to specify an additional set of actions to be

taken by the system when a signal-catching function is called.

A signal is generated by sending a request to a signal monitor.

The process to receive the signal is identified by a process ID. The process ID is

used to indicate whether the signal should be sent to an individual process or to a

group of processes (known as a process group). The process ID is used to locate

an entry in the system-managed process table. A process table entry contains the

following information relating to the process:

Ÿ Parent process ID

Ÿ Process group ID

Ÿ Status information

The parent process is the logical creator of the process. A process group repre-

sents a collection of processes that are bound together for some common purpose.

The process sending a signal must have the appropriate authority to the receiving

process.

The OS/400 support for signals does differ from the usual behavior of signals on

UNIX systems.

For additional information about signal concepts, OS/400 management support, and

how signals differ on OS/400 from UNIX systems, see the “Signal Concepts” topic

in the book System API Reference.

Simple Network Management Protocol (SNMP) APIs

The Simple Network Management Protocol (SNMP) APIs comprise the SNMP sub-

agent APIs and the SNMP manager APIs.

SNMP Subagent APIs: The SNMP subagent APIs can be used to dynamically

extend the management information base (MIB) that the system SNMP agent is

aware of. The MIB is extended without any change to the SNMP agent itself while

the AS/400 is running. Dynamically added MIB subtrees (as supported and defined

by a program known as a subagent) provide this capability. You may now extend

the remote and automated system management capabilities of the AS/400 within

the SNMP framework. So, for example, you could define an SNMP MIB group for

your RPG and SQL application.

The Distributed Protocol Interface (DPI) is an extension to SNMP agents. DPI

permits users to dynamically add, delete, or replace management variables in the

local MIB without requiring recompilation of the SNMP agent.

SNMP Manager APIs: SNMP managing applications typically use APIs to estab-

lish communication with local or remote SNMP agents, and then call other APIs to

retrieve or modify MIB objects managed by those agents. The OS/400 SNMP

manager APIs accomplish both of these tasks within the same API. Three

manager APIs are provided to perform the SNMP GET, GETNEXT, and SET oper-

ations. In general, all three APIs are blocked, that is, once the application calls

these APIs, the API constructs a proper SNMP message, delivers it to the proper

SNMP agent, waits, decodes the response from the agent, and delivers the infor-

mation to the application. No processing occurs in the application until the API

Chapter 8. Use of OS/400 APIs 8-25

Download from Www.Somanuals.com. All Manuals Search And Download.

delivers this information or times out. The communications mechanism between

the manager APIs and agents uses the User Datagram Protocol (UDP). Therefore,

both systems need to support UDP.

Sockets APIs

Sockets provides an API for applications that require program-to-program commu-

nications. This interface is based on and compatible with Berkeley Software Distri-

butions 4.3. Using sockets, server and client processes can be on the same

system or on different systems.

The types of sockets follow:

Ÿ Stream sockets, which are connection oriented

Ÿ Datagrams, which are connectionless

Ÿ Raw sockets, which provide direct access to low-layer protocols

Ÿ Sequenced-packet sockets, which are connection oriented

Figure 8-1 shows a typical application flow when the sockets APIs are used.

SERVER

CLIENT

┌──────────────────┐

│

socket()

│

socket()

│

└────────┬─────────┘

┌──────────────────┐

│

bind()

│

bind()

│

└────────┬─────────┘

│

┌──────────────────┐

│

listen()

│

└────────┬─────────┘

│

┌──────────────────┐

│

connect()

│

└────────┬─────────┘

│

┌──────────────────┐

│

accept()

│

└────────┬─────────┘

│

┌──────────────────┐

│

send

receive

├───────────5│

│ %──────────┤

receive

send

│

└────────┬─────────┘

┌──────────────────┐

│

close()

│

close()

│

└──────────────────┘

Figure 8-1. Simplified Sequence of Events for a Sockets Program Example

For more information about sockets, see the Sockets Programming book,

SC41-5422.

8-26 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Process-Related APIs

The process-related APIs perform process-related or other general operations.

Using these APIs, a process can get the process ID of itself, its parent process, or

the process group. A process can also check the status for itself, its child pro-

cesses, or the process group.

For information on APIs to create processes (for example, spawn() and spawnp()),

see the System API Reference book.

User Interface APIs

The user interface manager (UIM) APIs are a set of programs that allow the user

the ability to use panel groups and create applications that function in the same

way. This means using the same standards for function key descriptions, and so

forth, as the system panels.

The UIM APIs are used in combination with variables, lists, and panel definitions in

a panel group object.

When you design an application program that manipulates the user interface, you

can use all UIM panel groups, data description specifications (DDS) display files

with UIM help, or DDS display files with help in folders. The following shows the

advantages of using UIM versus DDS.

UIM Advantages

The advantages of using UIM over DDS follow:

Ÿ Uses the same standards as the AS/400

There is no need to redefine standards because the applications would work

the same way as the system panels. UIM formats the panel for you based on

what you want displayed.

Ÿ Processes more efficiently from a list panel

– UIM has the ability to process commands from a list panel. There is no

need to call a program to issue the command.

– UIM has the ability to prompt in the same manner as the AS/400.

– You can specify a program for UIM to call after the option is selected.

– Confirmation panels are built into the system.

– UIM provides more efficient list entry access and update processing.

Ÿ Works better with languages that efficiently process structures

Each type of UIM exit program requires a different set of parameters, thus

making it difficult to have one program that processes all the exit program func-

tions.

Ÿ Provides for more modular programming techniques

One program can process all incomplete list exit program calls, one can open

all applications, and so forth.

Ÿ Has the ability to condition menu options

Ÿ Formats and handles scrolling of large areas with no user program intervention

Examples are data, list, information, menu, and function key areas.

Chapter 8. Use of OS/400 APIs 8-27

Download from Www.Somanuals.com. All Manuals Search And Download.

DDS Advantages

The advantages of using DDS over UIM follow:

Ÿ Provides more flexibility in screen design

The user defines in what row and column a field should appear.

Ÿ Provides initial formatting with Screen Design Aid (SDA)

Ÿ Has the ability to use UIM help or help in folders

Ÿ Has the ability to take advantage of graphical operations windows

Ÿ Does subfile processing

Ÿ Uses edit code (EDTCDE), edit word (EDTWRD), and user-defined editing

Ÿ Is faster for smaller applications

DDS requires less initial setup (that is, the display file may be opened automat-

ically by an HLL program).

Ÿ Can also imbed HyperText Markup Language (HTML) tags into the data stream

that is sent out

Virtual Terminal APIs

The virtual terminal APIs allow your AS/400 application programs to interact with

AS/400 application programs that are performing work station input and output

(I/O).

A virtual terminal is a device that does not have hardware associated with it. It

forms a connection between your application and AS/400 applications, representing

a physical work station (possibly on a remote system). The OS/400 licensed

program manages the virtual terminal, which directs work station I/O performed by

an AS/400 application to the virtual terminal. The virtual terminal APIs allow

another AS/400 application, called a server program, to work with the data associ-

ated with the virtual terminal.

In a distributed systems environment, the requesting program is called a client; the

answering program is called a server. The client and server programs may reside

on the same AS/400 system or may be distributed between two different systems.

The server program generally runs on behalf of (or in conjunction with) the client

program. Together, the server program and the client program allow a work station

to be supported as if the work station were connected locally.

Work Management APIs

This group of APIs helps you to better manage the work on your system. The APIs

let you keep track of the jobs and the things associated with those jobs. Also,

some of the APIs allow you to adjust the performance characteristics.

Work Station Support APIs

The work station support APIs allow you to control the type-ahead characteristics of

a work station and to retrieve information about the last output operation to the

requester device for the specified interactive job.

Type-ahead, also called keyboard buffering, lets the user type data faster than it

can be sent to the system. Attention key buffering determines how to process

the action of pressing an Attention key. If attention key buffering is on, the Atten-

8-28 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

tion key is treated as any other key. If attention key buffering is not on, pressing

the Attention key results in sending the information to the system even when other

work station input is inhibited.

Miscellaneous APIs

The miscellaneous part of the System API Reference includes the following miscel-

laneous APIs plus the process open list APIs.

Miscellaneous APIs

The miscellaneous APIs include the following:

Ÿ Convert Date and Time Format (QWCCVTDT) API

This API allows you to convert date and time formats from one format to

another format.

Ÿ Remove All Bookmarks from a Course (QEARMVBM) API

This API allows you to remove the bookmarks from a Tutorial System Support

course.

Ÿ Retrieve Data (QPARTVDA) API

This API retrieves up to 1KB of user data, which was passed to this system

with the Start Pass-through (QPASTRPT) API.

Ÿ Start Pass-Through (QPASTRPT) API

This API starts a 5250 pass-through session and optionally passes up to 1KB

of user data from the source system to the target system. This data can be

accessed on the target system with the Retrieve Data (QPARTVDA) API.

Process Open List APIs

These AS/400 list APIs can improve perceived performance when they create lists.

The APIs create and make available to the caller a partial listing of the total set of

files, messages, or objects. This list is immediately available to be acted upon,

while the remainder of the list is being created. The user does not have to wait for

the entire list to be created. Following is a description of the APIs and how they

work together.

The process open list APIs are used to access the data returned by the following

AS/400 APIs:

Ÿ Open List of Job Log Messages (QGYOLJBL)

Ÿ Open List of Messages (QGYOLMSG)

Ÿ Open List of Objects (QGYOLOBJ)

Ÿ Open List of Objects to be Backed Up (QEZOLBKL)

Ÿ Open List of Printers (QGYRPRTL)

Ÿ Open List of Spooled Files (QGYOLSPL)

The APIs in the previous list are located in their respective sections in the System

API Reference book; that is, backup and recovery APIs, message handling APIs,

object APIs, and print APIs.

Each of these APIs builds a list of the appropriate type and returns the number of

records requested by the caller of the API. Also returned from the list building

program is a request handle associated with that particular list. This request

handle can be used on subsequent calls to the Get List Entry (QGYGTLE) API to

Chapter 8. Use of OS/400 APIs 8-29

Download from Www.Somanuals.com. All Manuals Search And Download.

get more records from the list. The request handle is valid until the Close List

(QGYCLST) API is used to close the list.

The request handle is also used as input to the following APIs when you need to

find a specific entry in the list:

Ÿ Find Entry Number in List (QGYFNDE) API, which returns the number of the

entry in a list of information for a given key value. This API can be used with

lists that have been created by either the QGYOLOBJ or QGYOLSPL API.

Ÿ Find Entry Number in Message List (QGYFNDME) API, which returns the

number of the entry in the list of message information for a given key value.

This API can be used with lists that have been created by either the

QGYOLMSG or QGYOLJBL API.

Ÿ Find Field Numbers in List (QGYFNDF) API, which returns the number of the

entry in a list of information and the value of that entry whenever the value of

that field changes.

8-30 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Chapter 9. Common API Programming Errors

This chapter contains information identified as common programming errors

encountered when using APIs within application programs. The chapter design

provides two program examples for each common error. The first program

example is incorrectly coded and is followed by the correctly coded example. If you

encounter errors or problems while working with APIs, these examples may provide

ideas or solutions.

Note: Do not assume that an API will do things other than what the System API

Reference mentions. If the manual does not say specifically that it is

allowed, it probably is not.

Figure 9-1 identifies common API programming errors and refers you to examples

that show you how to avoid the errors.

Figure 9-1. Common Programming Errors

Task

Location of Example

Using the error code param-

eter

Page 9-2

Defining data structures

Page 9-5

Page 9-10

Page 9-14

Defining receiver variables

Defining list entry format

lengths

Using null pointers with OPM

APIs

Page 9-18

Defining byte alignment

Using offsets in user space

Coding for new function

Page 9-22

Page 9-27

Page 9-36

 Copyright IBM Corp. 1997

9-1

Download from Www.Somanuals.com. All Manuals Search And Download.

Using the Error Code Parameter

The error code parameter provides a way for you to determine if the API encoun-

tered any errors.

The examples in this topic present a program used for creating a user space.

Using the Error Code Parameter—Example of Incorrect Coding

The common error shown in the following example is the use of the error code

structure to indicate to the API not to send exception messages for errors found.

Additionally, the example does not examine the error code structure to determine if

the API call was successful or not. To demonstrate the improper use of the error

code structure, an incorrect value is used on the replace parameter of the

QUSCRTUS API. The replace parameter is a required parameter. The coded

error (*XXXXXXX) is shown at location .2/ in the incorrect and correct coding

(pages 9-3 and 9-4, respectively).

Both the incorrect and correct coding (.1/ on page 9-3 and .1/ on page 9-3) show

the program monitoring for any error from the call to the API. However, the

program does not examine the bytes available field after calling the QUSCRTUS

API.

Because of the error on the replace parameter, the requested user space is not

created. The calling program, however, is not aware of this (shown at .3/ on page

9-3).

ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

ᑍ

ᑍProgram Name: PGM1

ᑍ

ᑍProgram Language: RPG

ᑍ

ᑍDescription: This sample program illustrates the incorrect

ᑍ

way of using the error code parameter.

ᑍHeader Files Included: QUSEC - Error Code Parameter

ᑍ

ᑍAPIs Used: QUSCRTUS - Create User Space

ᑍ

ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

ᑍ BRING IN THE ERROR STRUCTURE FROM QSYSINC

I/COPY QSYSINC/QRPGSRC,QUSEC

ᑍᑍ

ISPCNAM

I I

'SPCNAME '

'PAM

1 1ð SPC

11 2ð LIB

ᑍᑍ OTHER ASSORTED VARIABLES

I I

2ððð

B 1 4ðSIZ

B 5 8ðSTART

9 9 INTVAL

I I

ᑍ

X'ðð'

ᑍ Initialize the bytes provided field (QUSBNDB) of the error code

ᑍ structure. Languages such as RPG and CL tend to initialize the bytes

ᑍ provided field to blanks, which when passed to an API is viewed as a

ᑍ very large (and incorrect) binary value. If you receive CPF3CF1 when

9-2 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

ᑍ calling an API, the bytes provided field should be the first field

ᑍ you examine as part of problem determination.

Z-ADD16

QUSBNB

.1/

ᑍ

ᑍ CREATE THE SPACE TO HOLD THE DATA

CALL 'QUSCRTUS'

PARM

SPCNAM

PARM 'EXT_ATTR'EXTATR 1ð

PARM

SIZ

INTVAL

PARM

PARM 'ᑍALL

'PUBAUT 1ð

PARM 'NO TEXT 'TXTDSC 5ð

PARM 'ᑍXXXXXXX'REPLAC 1ð

PARM

.2/

QUSBN

ᑍᑍ Program does not check the error code parameter .3/

ᑍᑍ

SETON

Using the Error Code Parameter—Example of Correct Coding

You can add code to help you discover what errors may be in a program. In the

following example program, code has been added to monitor error information

passed back in the error code parameter (QUSBN). This code is shown at .4/ on

page 9-4. The code at .4/ has been added to check the error code parameter for

any messages and to display the exception identifier to the user if any errors are

found. The incorrectly coded program does no checking for the error code param-

eter (shown at .3/ on page 9-3).

ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

ᑍ

ᑍProgram Name: PGM2

ᑍ

ᑍProgram Language: RPG

ᑍ

ᑍDescription: This sample program illustrates the correct

ᑍ

way of using the error code parameter.

ᑍHeader Files Included: QUSEC - Error Code Parameter

ᑍ

ᑍAPIs Used: QUSCRTUS - Create User Space

ᑍ

ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

ᑍ BRING IN THE ERROR STRUCTURE FROM QSYSINC

I/COPY QSYSINC/QRPGSRC,QUSEC

ᑍᑍ

ISPCNAM

I I

'SPCNAME '

'QTEMP

1 1ð SPC

11 2ð LIB

ᑍᑍ OTHER ASSORTED VARIABLES

I I

ᑍ

2ððð

B 1 4ðSIZ

B 5 8ðSTART

9 9 INTVAL

X'ðð'

Z-ADD16

QUSBNB .1/

ᑍ

Chapter 9. Common API Programming Errors 9-3

Download from Www.Somanuals.com. All Manuals Search And Download.

ᑍ CREATE THE SPACE TO HOLD THE DATA

CALL 'QUSCRTUS'

PARM

PARM 'EXT_ATTR'EXTATR 1ð

PARM

PARM 'ᑍALL

PARM 'NO TEXT 'TXTDSC 5ð

PARM 'ᑍXXXXXXX'REPLAC 1ð

PARM

SPCNAM

SIZ

INTVAL

'PUBAUT 1ð

.2/

QUSBN

ᑍᑍ

ᑍ DISPLAY EXCEPTION IDENTIFIER TO THE USER

QUSBNC

IFGT ᑍZEROS

EXSR DSPERR

END

.4/

ᑍ

SETON

DSPERR BEGSR

DSPLY

ENDSR

QUSBND

9-4 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Defining Data Structures

When a data structure is defined for use with an API, the structure must be built to

receive what the API returns.

The use of IBM-supplied data structures eliminates having to create your own data

structures. For information on IBM-supplied data structures that are contained in

library QSYSINC, see “APIs and the QSYSINC Library” on page 2-28.

Defining a Data Structure—Example of Incorrect Coding

When the program that defines a data structure is run, it does the following:

Ÿ Creates a user space

Ÿ Retrieves a list of active jobs

Ÿ Displays the first part of a job name

Ÿ Deletes the user space that held the data

In this example, the data structure to be used with the QUSLJOB API has been

defined incorrectly. The incorrectly defined variables are JNAME and USRNAM.

The JNAME length is defined as 1 through 12 and the USRNAM length as 13

through 20. This is shown at .5/ on page 9-5. The data displayed (JNAME vari-

able) will be incorrect. The correct coding is shown at .6/ on page 9-7.

ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

ᑍ

ᑍProgram Name: PGM1

ᑍ

ᑍProgram Language: RPG

ᑍ

ᑍDescription: This sample program illustrates the incorrect

ᑍ

way of defining data structures.

ᑍHeader Files Included: QUSEC - Error Code Parameter

ᑍ

QUSGEN - User Space Format for Generic Header

ᑍ

ᑍAPIs Used: QUSCRTUS - Create User Space

ᑍ

QUSLJOB - List Job

QUSRTVUS - Retrieve User Space

QUSDLTUS - Delete User Space

ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

ᑍ THIS PROGRAM WILL CREATE THE NECESSARY SPACE AND THEN CALL

ᑍ THE QUSLJOB API TO GET A LIST OF ALL ACTIVE JOBS ON THE SYSTEM.

ᑍ THE FIRST JOB NAME/USER WILL BE DISPLAYED TO THE USER.

ᑍ

ᑍ BRING IN THE USER SPACE GENERIC HEADER

I/COPY QSYSINC/QRPGSRC,QUSGEN

ᑍ BRING IN THE ERROR STRUCTURE FROM QSYSINC

I/COPY QSYSINC/QRPGSRC,QUSEC

ᑍᑍ JOB NAME STRUCTURE FOR CALLING QUSLJOB

IJOBNAM

I I

'ᑍALL

1 1ð JOB

11 2ð USER

21 26 JOBNUM

I I

'ᑍALL

I I

'ᑍALL '

ᑍᑍ JOBLð1ðð FORMAT RETURNED FROM QUSLJOB API

ᑍᑍ INCORRECTLY CODE THE JNAME/USRNAM LENGTHS

IRECVR

1 12 JNAME

.5/

Chapter 9. Common API Programming Errors 9-5

Download from Www.Somanuals.com. All Manuals Search And Download.

13 2ð USRNAM .5/

21 26 JOBNBR

27 42 JOBID

43 52 JSTAT

53 53 JTYPE

54 54 JSUBT

55 56 RESRV

ᑍᑍ

ISPCNAM

I I

ᑍᑍ OTHER ASSORTED VARIABLES

I I

ᑍ

'SPCNAME '

'QTEMP

1 1ð SPC

11 2ð LIB

2ððð

B 1 4ðSIZ

B 5 8ðSTART

B 9 12ðLENDTA

13 13INTVAL

X'ðð'

ᑍ SET UP TO ACCEPT EXCEPTIONS

Z-ADDᑍZEROS

QUSBNB

ᑍ

ᑍ CREATE THE SPACE TO HOLD THE DATA

CALL 'QUSCRTUS'

PARM

SPCNAM

PARM 'EXT_ATTR'EXTATR 1ð

PARM

SIZ

INTVAL

PARM 'ᑍALL

'PUBAUT 1ð

PARM 'TEXT DSC'TXTDSC 5ð

PARM 'ᑍYES

PARM

'REPLAC 1ð

QUSBN

ᑍ

ᑍ CALL THE API TO LIST THE ACTIVE JOBS

CALL 'QUSLJOB'

PARM

SPCNAM

PARM 'JOBLð1ðð'FORMAT 8

PARM

JOBNAM

PARM 'ᑍACTIVE 'STAT 1ð

PARM QUSBN

ᑍ

ᑍ RETRIEVE THE OFFSET OF THE FIRST LIST ENTRY FROM THE SPACE

Z-ADD1

Z-ADD14ð

CALL 'QUSRTVUS'

PARM

START

LENDTA

SPCNAM

START

LENDTA

QUSBP

QUSBN

PARM

ᑍ

ᑍ RETRIEVE THE FIRST LIST ENTRY

QUSBPQ ADD 1

START

Z-ADD56

LENDTA

CALL 'QUSRTVUS'

PARM

SPCNAM

START

LENDTA

9-6 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

PARM

RECVR

QUSBN

ᑍ

ᑍ DISPLAY THE JOB NAME

DSPLY

JNAME >>> When displayed,JNAME

will look something like

ᑍ

'QCPF

QS'

ᑍ DELETE THE SPACE THAT HELD THE DATA

CALL 'QUSDLTUS'

PARM

SPCNAM

QUSBN

ᑍᑍ

SETON

Defining A Data Structure—Example of Correct Coding

The following program uses a data structure that is supplied from the QSYSINC

library. When you use this data structure, you can prevent errors in data structure

creation from happening. If the data structures change from release to release,

updates to programs do not have to be done. The application program would have

to be updated only if a new field was added to the data structure and you wanted

to use the field. The copying of the QSYSINC data structure is shown at .6/ on

page 9-7.

ᑍ

ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

ᑍ

ᑍProgram Name: PGM2

ᑍ

ᑍProgram Language: RPG

ᑍ

ᑍDescription: This sample program illustrates the correct

ᑍ

way of defining data structures.

ᑍHeader Files Included: QUSEC - Error Code Parameter

ᑍ

QUSGEN - User Space Format for Generic Header

QUSLJOB - List Job API

ᑍAPIs Used: QUSCRTUS - Create User Space

ᑍ

QUSLJOB - List Job

QUSRTVUS - Retrieve User Space

QUSDLTUS - Delete User Space

ᑍ THIS PROGRAM WILL CREATE THE NECESSARY SPACE AND THEN CALL

ᑍ THE QUSLJOB API TO GET A LIST OF ALL ACTIVE JOBS ON THE SYSTEM.

ᑍ THE FIRST JOB NAME/USER WILL BE DISPLAYED TO THE USER.

ᑍ

I/COPY QSYSINC/QRPGSRC,QUSGEN

I/COPY QSYSINC/QRPGSRC,QUSEC

I/COPY QSYSINC/QRPGSRC,QUSLJOB

.6/

ᑍᑍ JOB NAME STRUCTURE FOR CALLING QUSLJOB

IJOBNAM

I I

'ᑍALL

'ᑍALL'

1 1ð JOB

I I

11 2ð USER

21 26 JOBNUM

I I

ᑍᑍ JOBLð1ðð FORMAT RETURNED FROM QUSLJOB API

Chapter 9. Common API Programming Errors 9-7

Download from Www.Somanuals.com. All Manuals Search And Download.

ᑍᑍ

ISPCNAM

I I

'SPCNAME '

'QTEMP

1 1ð SPC

11 2ð LIB

I I

ᑍᑍ OTHER ASSORTED VARIABLES

I I

ᑍ

2ððð

B 1 4ðSIZ

B 5 8ðSTART

B 9 12ðLENDTA

13 13 INTVAL

X'ðð'

ᑍ SET UP TO ACCEPT EXCEPTIONS

Z-ADDᑍZEROS

QUSBNB

ᑍ

ᑍ CREATE THE SPACE TO HOLD THE DATA

CALL 'QUSCRTUS'

PARM

SPCNAM

PARM 'EXT_ATTR'EXTATR 1ð

PARM

SIZ

INTVAL

PARM 'ᑍALL

'PUBAUT 1ð

PARM 'TEXT DSC'TXTDSC 5ð

PARM 'ᑍYES

PARM

'REPLAC 1ð

QUSBN

ᑍ

ᑍ CALL THE API TO LIST THE ACTIVE JOBS

CALL 'QUSLJOB'

PARM

SPCNAM

PARM 'JOBLð1ðð'FORMAT 8

PARM

JOBNAM

PARM 'ᑍACTIVE 'STAT 1ð

PARM QUSBN

ᑍ

ᑍ RETRIEVE THE OFFSET OF THE FIRST LIST ENTRY FROM THE SPACE

Z-ADD1

Z-ADD14ð

CALL 'QUSRTVUS'

PARM

START

LENDTA

SPCNAM

START

LENDTA

QUSBP

QUSBN

PARM

ᑍ

ᑍ RETRIEVE THE FIRST LIST ENTRY

QUSBPQ

ADD 1

Z-ADD56

CALL 'QUSRTVUS'

PARM

START

LENDTA

SPCNAM

START

LENDTA

QUSDD

QUSBN

PARM

ᑍ

ᑍ DISPLAY THE JOB NAME

DSPLY

ᑍ

QUSDDB >>> Correct job name

will now show as

'QCPF

9-8 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

ᑍ DELETE THE SPACE THAT HELD THE DATA

CALL 'QUSDLTUS'

PARM

SPCNAM

QUSBN

ᑍᑍ

SETON

Chapter 9. Common API Programming Errors 9-9

Download from Www.Somanuals.com. All Manuals Search And Download.

Defining Receiver Variables

When defining receiver variables, the most common error is to create them too

small for the amount of data that they are to receive. Both example programs are

coded in RPG and, when run, lists all active jobs on the system.

Defining Receiver Variables—Example of Incorrect Coding

The following example program will fail because the receiver variable has been

defined as 50 bytes (shown at .7/ on page 9-11), but 60 bytes are being requested

to be passed back from the API (shown at .8/ in the incorrect and correct pro-

grams on pages 9-11 and 9-13, respectively). The correct coding is shown at .9/

on page 9-13.

When this happens, other variables are overwritten with unintended data. This

causes the other variables to be incorrect. For example, the first 10 characters of

QUSBN may be written over with these extra characters. On the call to the next

API, the error code parameter may appear to contain meaningless characters that

would cause the next call to an API to fail.

ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

ᑍ

ᑍProgram Name: PGM1

ᑍ

ᑍProgram Language: RPG

ᑍ

ᑍDescription: This sample program illustrates the incorrect

ᑍ

way of defining receiver variables.

ᑍHeader Files Included: QUSEC - Error Code Parameter

ᑍ

QUSLJOB - List Job API

QUSGEN - User Space Format for Generic Header

ᑍAPIs Used: QUSCRTUS - Create User Space

ᑍ

QUSLJOB - List Job

QUSRTVUS - Retrieve User Space

QUSDLTUS - Delete User Space

ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

ᑍ THIS PROGRAM WILL CREATE THE NECESSARY SPACE AND THEN CALL

ᑍ THE QUSLJOB API TO GET A LIST OF ALL ACTIVE JOBS ON THE SYSTEM.

ᑍ BRING IN THE GENERIC USER SPACE HEADER FROM QSYSINC

I/COPY QSYSINC/QRPGSRC,QUSGEN

ᑍ

ᑍ BRING IN THE ERROR STRUCTURE FROM QSYSINC

I/COPY QSYSINC/QRPGSRC,QUSEC

ᑍ

ᑍᑍ JOBLð1ðð FORMAT RETURNED FROM QUSLJOB API

I/COPY QSYSINC/QRPGSRC,QUSLJOB

ᑍ

ᑍᑍ JOB NAME STRUCTURE FOR CALLING QUSLJOB

IJOBNAM

I I

ISPCNAM

I I

'ᑍALL

'ᑍALL'

1 1ð JOB

11 2ð USER

21 26 JOBNUM

'SPCNAME '

'QTEMP

1 1ð SPC

11 2ð LIB

9-10 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

ᑍᑍ OTHER ASSORTED VARIABLES

I I

2ððð

B 1 4ðSIZ

B 5 8ðSTART

B 9 12ðLENDTA

13 13 INTVAL

I I

ᑍ

X'ðð'

ᑍ SET UP TO ACCEPT EXCEPTIONS

Z-ADDᑍZEROS

QUSBNB

ᑍ

ᑍ CREATE THE SPACE TO HOLD THE DATA

CALL 'QUSCRTUS'

PARM

SPCNAM

PARM 'EXT_ATTR'EXTATR 1ð

PARM

SIZ

INTVAL

PARM 'ᑍALL

'PUBAUT 1ð

PARM 'TEXT DSC'TXTDSC 5ð

PARM 'ᑍYES

PARM

'REPLAC 1ð

QUSBN

ᑍ

ᑍ CALL THE API TO LIST THE ACTIVE JOBS

CALL 'QUSLJOB'

PARM

SPCNAM

PARM 'JOBLð1ðð'FORMAT 8

PARM

JOBNAM

PARM 'ᑍACTIVE 'STAT 1ð

PARM QUSBN

ᑍ

ᑍ RETRIEVE THE OFFSET OF THE FIRST LIST ENTRY FROM THE SPACE

Z-ADD1

Z-ADD14ð

CALL 'QUSRTVUS'

PARM

START

LENDTA

SPCNAM

START

LENDTA

QUSBP

QUSBN

PARM

ᑍ

ᑍ RETRIEVE THE LIST ENTRIES

QUSBPQ

ADD 1

START

LENDTA

ᑍ

Z-ADD6ð

.8/

Z-ADD1

DOWLEQUSBPS

CALL 'QUSRTVUS'

PARM

9ð

SPCNAM

START

LENDTA

RECVR 5ð .7/

QUSBN

PARM

ᑍ

DSPLY

QUSBN

ADD QUSBPT

ADD 1

END

START

Chapter 9. Common API Programming Errors 9-11

Download from Www.Somanuals.com. All Manuals Search And Download.

ᑍ DELETE THE SPACE THAT HELD THE DATA

CALL 'QUSDLTUS'

PARM

SPCNAM

QUSBN

ᑍ

SETON

Defining Receiver Variables—Example of Correct Coding

The following example program defines a larger receiver variable: 60 bytes. This

is shown at position .9/ on page 9-13. This increase in the receiver variable allows

up to 60 bytes of data to be received.

ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

ᑍ

ᑍProgram Name: PGM2

ᑍ

ᑍProgram Language: RPG

ᑍ

ᑍDescription: This sample program illustrates the correct

ᑍ

way of defining receiver variables.

ᑍHeader Files Included: QUSEC - Error Code Parameter

ᑍ

QUSLJOB - List Job API

QUSGEN - User Space Format for Generic Header

ᑍAPIs Used: QUSCRTUS - Create User Space

ᑍ

QUSLJOB - List Job

QUSRTVUS - Retrieve User Space

QUSDLTUS - Delete User Space

ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

ᑍ

ᑍ BRING IN THE ERROR STRUCTURE FROM QSYSINC

I/COPY QSYSINC/QRPGSRC,QUSEC

ᑍ BRING IN THE GENERIC USER SPACE HEADER FROM QSYSINC

I/COPY QSYSINC/QRPGSRC,QUSGEN

ᑍ

ᑍᑍ JOBLð1ðð FORMAT RETURNED FROM QUSLJOB API

I/COPY QSYSINC/QRPGSRC,QUSLJOB

ᑍ

ᑍᑍ JOB NAME STRUCTURE FOR CALLING QUSLJOB

IJOBNAM

I I

'ᑍALL

'ᑍALL'

1 1ð JOB

11 2ð USER

21 26 JOBNUM

I I

ISPCNAM

I I

'SPCNAME '

'QTEMP

1 1ð SPC

11 2ð LIB

I I

ᑍᑍ OTHER ASSORTED VARIABLES

I I

2ððð

B 1 4ðSIZ

B 5 8ðSTART

B 9 12ðLENDTA

13 13 INTVAL

I I

ᑍ

X'ðð'

ᑍ SET UP TO ACCEPT EXCEPTIONS

Z-ADDᑍZEROS

QUSBNB

ᑍ

9-12 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

ᑍ CREATE THE SPACE TO HOLD THE DATA

CALL 'QUSCRTUS'

PARM

PARM 'EXT_ATTR'EXTATR 1ð

PARM

SPCNAM

SIZ

INTVAL

PARM

PARM 'ᑍALL

'PUBAUT 1ð

PARM 'TEXT DSC'TXTDSC 5ð

PARM 'ᑍYES

PARM

'REPLAC 1ð

QUSBN

ᑍ

ᑍ CALL THE API TO LIST THE ACTIVE JOBS

CALL 'QUSLJOB'

PARM

SPCNAM

PARM 'JOBLð1ðð'FORMAT 8

PARM

JOBNAM

PARM 'ᑍACTIVE 'STAT 1ð

PARM QUSBN

ᑍ

ᑍ RETRIEVE THE OFFSET OF THE FIRST LIST ENTRY FROM THE SPACE

Z-ADD1

Z-ADD14ð

CALL 'QUSRTVUS'

PARM

START

LENDTA

SPCNAM

START

LENDTA

QUSBP

QUSBN

PARM

ᑍ

ᑍ RETRIEVE LIST ENTRIES

QUSBPQ

ADD 1

START

LENDTA

ᑍ

Z-ADD6ð

.8/

Z-ADD1

DOWLEQUSBPS

CALL 'QUSRTVUS'

PARM

9ð

SPCNAM

START

LENDTA

RECVR 6ð .9/

QUSBN

PARM

ᑍ

MOVELRECVR

ADD QUSBPT

ADD 1

QUSDD

START

END

ᑍ DELETE THE SPACE THAT HELD THE DATA

CALL 'QUSDLTUS'

PARM

SPCNAM

QUSBN

ᑍ

SETON

Chapter 9. Common API Programming Errors 9-13

Download from Www.Somanuals.com. All Manuals Search And Download.

Defining List Entry Format Lengths

The example programs in this topic show how to code flexibility into your program

as it works its way through the formats used by an API.

Defining List Entry Format Lengths—Example of Incorrect Coding

A common error, or trap, when working with list entry format lengths is to hard code

the format length into your program. The format length is used by the program to

advance to the next list entry in the user space. From release to release, the

length of the format may change. Therefore, when the format length changes, your

program can be susceptible to being pointed to an incorrect position in the user

space and nonsense data placed in the receiver variable.

The program has the length of the list entry format hard coded. This is shown at

.1ð/ on page 9-16. If your program runs on a Version 2 Release 2 system, that

value would work. However, with Version 2 Release 3, the format size increased

from 52 to 56 bytes. The correct coding is shown at .11/ on page 9-17.

ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

ᑍ

ᑍProgram Name: PGM1

ᑍ

ᑍProgram Language: RPG

ᑍ

ᑍDescription: This sample program illustrates the incorrect

ᑍ

way of using list entry length formats.

ᑍHeader Files Included: QUSEC - Error Code Parameter

ᑍ

QUSLJOB - List Job API

QUSGEN - User Space Format for Generic Header

ᑍAPIs Used: QUSCRTUS - Create User Space

ᑍ

QUSLJOB - List Job

QUSRTVUS - Retrieve User Space

QUSDLTUS - Delete User Space

ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

ᑍ

ᑍ THIS PROGRAM WILL CREATE THE NECESSARY SPACE AND THEN CALL

ᑍ THE QUSLJOB API TO GET A LIST OF ALL ACTIVE JOBS ON THE SYSTEM.

ᑍ THE FIRST JOB NAME/USER WILL BE DISPLAYED TO THE USER.

I/COPY QSYSINC/QRPGSRC,QUSGEN

I/COPY QSYSINC/QRPGSRC,QUSLJOB

ᑍ

ᑍ BRING IN THE ERROR STRUCTURE FROM QSYSINC

I/COPY QSYSINC/QRPGSRC,QUSEC

ᑍ

ᑍᑍ JOB NAME STRUCTURE FOR CALLING QUSLJOB

IJOBNAM

I I

'ᑍALL

'ᑍALL'

1 1ð JOB

11 2ð USER

21 26 JOBNUM

ᑍ FORMAT JOBLð1ðð FOR QUSLJOB API

ᑍ

ᑍᑍ DATA STRUCTURE CONTAINING SPACE NAME/LIB

ISPCNAM

9-14 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

I I

'SPCNAME '

'QTEMP

1 1ð SPC

11 2ð LIB

ᑍᑍ OTHER ASSORTED VARIABLES

I I

2ððð

B 1 4ðSIZ

B 5 8ðSTART

B 9 12ðLENDTA

13 13 INTVAL

I I

ᑍ

X'ðð'

ᑍ SET UP TO ACCEPT EXCEPTIONS

Z-ADDᑍZEROS

QUSBNB

ᑍ

ᑍ CREATE THE SPACE TO HOLD THE DATA

CALL 'QUSCRTUS'

PARM

SPCNAM

PARM 'EXT_ATTR'EXTATR 1ð

PARM

SIZ

INTVAL

PARM 'ᑍALL

'PUBAUT 1ð

PARM 'TEXT DSC'TXTDSC 5ð

PARM 'ᑍYES

PARM

'REPLAC 1ð

QUSBN

ᑍ

ᑍ CALL THE API TO LIST THE ACTIVE JOBS

CALL 'QUSLJOB'

PARM

SPCNAM

PARM 'JOBLð1ðð'FORMAT 8

PARM

JOBNAM

PARM 'ᑍACTIVE 'STAT 1ð

PARM QUSBN

ᑍ

ᑍ RETRIEVE INFORMATION ABOUT THE USER SPACE AND ITS CONTENTS

Z-ADD1

Z-ADD14ð

CALL 'QUSRTVUS'

PARM

START

LENDTA

SPCNAM

START

LENDTA

QUSBP

QUSBN

PARM

ᑍ

ᑍ RETRIEVE LIST ENTRIES

QUSBPQ

ADD 1

START

LENDTA

Z-ADD52

Z-ADD1

DOWLEQUSBPS

CALL 'QUSRTVUS'

PARM

9ð

SPCNAM

START

LENDTA

QUSDD

QUSBN

PARM

ᑍ

ᑍ RETRIEVE THE NEXT LIST ENTRY (SPECIFYING LAST RELEASE'S

ᑍ FORMAT LENGTH AS THE AMOUNT TO BUMP THE POINTER - THIS

ᑍ WILL RESULT IN "GARBAGE" IN THE RECEIVER VARIABLE BECAUSE THE

ᑍ FORMAT IS NOW 56 BYTES LONG)

ᑍ

Chapter 9. Common API Programming Errors 9-15

Download from Www.Somanuals.com. All Manuals Search And Download.

ᑍ DISPLAY THE INFORMATION RETURNED

MOVELQUSDD

RECVR 52

RECVR

START

DSPLY

ADD 52

.1ð/

ADD 1

END

ᑍ

ᑍ DELETE THE SPACE THAT HELD THE DATA

CALL 'QUSDLTUS'

PARM

SPCNAM

QUSBN

ᑍ

SETON

Defining List Entry Format Lengths—Example of Correct Coding

The following program correctly uses the list entry length that is defined in the

space header for the QUSRTVUS API to advance from one entry to the next. This

is shown at .11/ on page 9-17. If you use this value in your program, you will

always have the correct list entry length regardless of the version or release level of

the API.

ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

ᑍ

ᑍProgram Name: PGM2

ᑍ

ᑍProgram Language: RPG

ᑍ

ᑍDescription: This sample program illustrates the correct

ᑍ

way of using list entry length formats.

ᑍHeader Files Included: QUSEC - Error Code Parameter

ᑍ

QUSLJOB - List Job API

QUSGEN - User Space Format for Generic Header

ᑍAPIs Used: QUSCRTUS - Create User Space

ᑍ

QUSLJOB - List Job

QUSRTVUS - Retrieve User Space

QUSDLTUS - Delete User Space

ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

ᑍ

ᑍ THIS PROGRAM WILL CREATE THE NECESSARY SPACE AND THEN CALL

ᑍ THE QUSLJOB API TO GET A LIST OF ALL ACTIVE JOBS ON THE SYSTEM.

ᑍ

I/COPY QSYSINC/QRPGSRC,QUSGEN

I/COPY QSYSINC/QRPGSRC,QUSLJOB

I/COPY QSYSINC/QRPGSRC,QUSEC

ᑍ

ᑍᑍ JOB NAME STRUCTURE FOR CALLING QUSLJOB

IJOBNAM

I I

'ᑍALL

'ᑍALL'

1 1ð JOB

11 2ð USER

21 26 JOBNUM

I I

ᑍ

ᑍᑍ DATA STRUCTURE TO HOLD SPACE NAME

ISPCNAM

I I

'SPCNAME

'QTEMP

1 1ð SPC

11 2ð LIB

ᑍᑍ OTHER ASSORTED VARIABLES

I I

2ððð

4ðSIZ

8ðSTART

9 12ðLENDTA

13 13 INTVAL

I I

ᑍ

X'ðð'

9-16 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

ᑍ SET UP TO ACCEPT EXCEPTIONS

Z-ADDᑍZEROS

QUSBNB

SPCNAM

ᑍ

ᑍ CREATE THE SPACE TO HOLD THE DATA

CALL 'QUSCRTUS'

PARM

PARM 'EXT_ATTR'EXTATR 1ð

PARM

PARM 'ᑍALL

PARM 'TEXT DSC'TXTDSC 5ð

SIZ

INTVAL

'PUBAUT 1ð

PARM 'ᑍYES

PARM

'REPLAC 1ð

QUSBN

ᑍ

ᑍ CALL THE API TO LIST THE ACTIVE JOBS

CALL 'QUSLJOB'

PARM

SPCNAM

PARM 'JOBLð1ðð'FORMAT 8

PARM

PARM 'ᑍACTIVE 'STAT

PARM QUSBN

JOBNAM

1ð

ᑍ

ᑍ RETRIEVE INFORMATION ABOUT THE USER SPACE AND ITS CONTENTS

ᑍ

Z-ADD1

Z-ADD14ð

CALL 'QUSRTVUS'

PARM

START

LENDTA

SPCNAM

START

LENDTA

QUSBP

QUSBN

PARM

ᑍ RETRIEVE THE FIRST LIST ENTRY BASED ON THE LIST ENTRY OFFSET

ᑍ FOUND IN THE SPACE HEADER

QUSBPQ

ADD 1

Z-ADD52

Z-ADD1

DOWLEQUSBPS

CALL 'QUSRTVUS'

PARM

START

LENDTA

9ð

SPCNAM

START

LENDTA

QUSDD

QUSBN

PARM

ᑍ

ᑍ RETRIEVE THE NEXT LIST ENTRY (SPECIFYING LIST ENTRY LENGTH

ᑍ RETRIEVED FROM THE SPACE HEADER)

ADD QUSBPT

START

.11/

ᑍ

ᑍ DISPLAY THE INFORMATION RETURNED

MOVELQUSDD

RECVR 52

RECVR

DSPLY

ADD 1

END

ᑍ

ᑍ DELETE THE SPACE THAT HELD THE DATA

CALL 'QUSDLTUS'

PARM

SPCNAM

QUSBN

ᑍᑍ

SETON

Chapter 9. Common API Programming Errors 9-17

Download from Www.Somanuals.com. All Manuals Search And Download.

Using Null Pointers with OPM APIs

Many programmers, especially those with a C programming background, view

ignored parameters and NULL parameters as being the same. This expectation

can lead to unexpected results when OPM-based APIs are used.

Note: Using NULL with ignored parameters is primarily a consideration with

OPM-based APIs. ILE-based APIs allow you to pass NULL parameters to

indicate omitted parameter values.

Even though the value assigned to a parameter is not used, the parameter itself

must be addressable. When you use NULL for a parameter value, the system con-

ceptually passes an address that can be equated with 0, where 0 indicates that the

parameter cannot be addressed. This lack of addressability often results in a func-

tion check (MCH3601). Additionally, other error messages may also occur.

Using Null Pointers with OPM APIs—Example of Incorrect Coding

The following program has two parameter values coded as NULL. They are the

ignored parameters of the member and record format used in the List Database

Relations (QDBLDBR) API, which is shown at .12/ on page 9-19. The correct

coding is shown at .13/ on page 9-21.

When the program is called, a machine function check of MCH3601 is reported

because the address of the required parameters member and record format are

specified as NULL.

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ

ᑍ/

/ᑍProgram Name: PGM1

/ᑍ

/ᑍProgram Language: ILE C

/ᑍ

/ᑍDescription: This sample program illustrates the incorrect ᑍ/

/ᑍ

use of ignored and null parameters.

ᑍ/

/ᑍHeader Files Included: <stdio.h>

/ᑍ

<qusec.h>

<qusgen.h>

<qdbldbr.h>

<quscrtus.h>

<qusptrus.h>

<qliept.h>

/ᑍAPIs Used: QUSCRTUS - Create User Space

/ᑍ

QDBLDBR - List Database Relations

QUSPTRUS - Retrieve Pointer to User Space

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

#include <stdio.h>

#include <qusec.h>

#include <qusgen.h>

#include <qdbldbr.h>

#include <quscrtus.h>

#include <qusptrus.h>

#include <qliept.h>

main()

{

9-18 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ initialize program data elements

ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

char initial_value = ðxðð;

char text_description[5ð] =

"test of QDBLDBR API

char qualified_usrspc_name[2ð] = "GETLDBR QTEMP

Qus_EC_t error_code;

Qus_Generic_Header_ð1ðð_t ᑍheader_ptr;

error_code.Bytes_Provided = ð;

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ Create the user space to hold API results ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

QUSCRTUS(qualified_usrspc_name, "SPACE

", 1,

&initial_value, "ᑍALL

"ᑍYES

", text_description,

");

", &error_code, "ᑍUSER

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ Get list of file dependencies in current library

/ᑍ

/ᑍ Note that in this API call NULL pointers are being

/ᑍ used for the "ignored" parameters Member and

/ᑍ Record_Format. This convention is not valid as the

/ᑍ parameters must address a valid storage address.

/ᑍ The value

/ᑍ assigned to a storage location is not important, the

/ᑍ passing of a valid storage location is.

/ᑍ

ᑍ/

/ᑍ The next statement will cause a MCH36ð1

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

QDBLDBR(qualified_usrspc_name, "DBRLð1ðð", "ᑍALL

ᑍCURLIB ",

NULL, NULL, &error_code); .12/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ Get pointer to user space which contains dependencies ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

QUSPTRUS(qualified_usrspc_name, &header_ptr, &error_code);

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ and display number of entries generated

ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

printf("The number of entries returned is %d\n",

header_ptr->Number_List_Entries);

}

Using Null Pointers with OPM APIs—Example of Correct Coding

The following program specifies that blanks be used as the values for both the

member and record format parameters. This coding is shown at .13/ on page 9-21

in the example program. By using blanks, the storage or address location of those

parameters is identified and passed when needed.

Chapter 9. Common API Programming Errors 9-19

Download from Www.Somanuals.com. All Manuals Search And Download.

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ

ᑍ/

/ᑍProgram Name: PGM2

/ᑍ

/ᑍProgram Language: ILE C

/ᑍ

/ᑍDescription: This sample program illustrates the correct

/ᑍ

use of ignored and null parameters.

/ᑍHeader Files Included: <stdio.h>

/ᑍ

<qusec.h>

<qusgen.h>

<qdbldbr.h>

<quscrtus.h>

<qusptrus.h>

<qliept.h>

/ᑍAPIs Used: QUSCRTUS - Create User Space

/ᑍ

QDBLDBR - List Database Relations

QUSPTRUS - Retrieve Pointer to User Space

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

#include <stdio.h>

#include <qusec.h>

#include <qusgen.h>

#include <qdbldbr.h>

#include <quscrtus.h>

#include <qusptrus.h>

#include <qliept.h>

main()

{

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ initialize program data elements

ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

char initial_value = ðxðð;

char text_description[5ð] =

"test of QDBLDBR API

char qualified_usrspc_name[2ð] = "GETLDBR QTEMP

Qus_EC_t error_code;

Qus_Generic_Header_ð1ðð_t ᑍheader_ptr;

error_code.Bytes_Provided = ð;

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ Create the user space to hold API results ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

QUSCRTUS(qualified_usrspc_name, "SPACE

", 1,

&initial_value, "ᑍALL

"ᑍYES

", text_description,

");

", &error_code, "ᑍUSER

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ Get list of file dependencies in current library

/ᑍ

ᑍ/

/ᑍ Note that in this API call, blank characters are being ᑍ/

/ᑍ used for the "ignored" parameters Member and

/ᑍ Record_Format. While the value is ignored, a valid

/ᑍ parameter storage location must still be passed

ᑍ/

9-20 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

QDBLDBR(qualified_usrspc_name, "DBRLð1ðð", "ᑍALL

" ", " ", &error_code); .13/

ᑍCURLIB ",

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ Get pointer to user space which contains dependencies ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

QUSPTRUS(qualified_usrspc_name, &header_ptr, &error_code);

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ and display number of entries generated

ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

printf("The number of entries returned is %d\n",

header_ptr->Number_List_Entries);

}

Chapter 9. Common API Programming Errors 9-21

Download from Www.Somanuals.com. All Manuals Search And Download.

Defining Byte Alignment

Correct byte alignment ensures that data used with an API is correct. Byte align-

ment is also essential when APIs are used to retrieve and then print or display

data. When byte alignment is off, it causes the API to read the data at some point

other than at the beginning of a record.

Defining Byte Alignment—Example of Incorrect Coding

This program illustrates byte alignment while defining a structure. This is shown at

.14/ on page 9-23. Four-byte alignment is required when using this program.

Variable-length records must begin on a 4-byte boundary. As shown at .14/, the

variable-length record CCSID_rec is not beginning on a 4-byte boundary. When

the API accesses the CCSID_rec record, 4-byte alignment is forced by padding the

first 3 bytes of the CCSID_rec between the replace field and the start of the

CCSID_rec record. .15/ on page 9-24 shows that the variable-length record is

not 4-byte aligned (the value is 13, which is not divisible by 4). The correct coding

is shown at .17/ on page 9-26.

Note: Not all APIs require a 4-byte boundary. ILE APIs, such as

QusAddExitProgram, do.

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ ᑍ/

/ᑍ

ᑍ/

/ᑍProgram Name: PGM1

/ᑍ

/ᑍProgram Language: ILE C

/ᑍ

/ᑍDescription:

This program illustrates improper byte

alignment when using variable length

records.

/ᑍ

/ᑍHeader Files Included: <stdio.h>

/ᑍ

<signal.h>

<string.h>

<stdlib.h>

<qusrgfa1.h>

<qusec.h>

/ᑍ

<qliept.h>

/ᑍ

/ᑍ APIs Used:

/ᑍ

QusAddExitProgram

- Add an exit program

/ᑍ

Includes

ᑍ/

#include <stdio.h>

#include <signal.h>

#include <string.h>

#include <stdlib.h>

#include <qusrgfa1.h>

#include <qusec.h>

#include <qliept.h>

/ᑍ

Structures

ᑍ/

9-22 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

/ᑍ

ᑍ/

typedef struct {

/ᑍ Error code

ᑍ/

Qus_EC_t ec_fields;

char

exception_data[1ðð];

} error_code_struct;

typedef struct {

/ᑍ Exit program attribute keysᑍ/

int

num_rec;

Qus_Vlen_Rec_4_t replace_rec;

char

replace;

Qus_Vlen_Rec_4_t CCSID_rec;

int CCSID;

.14/

Qus_Vlen_Rec_4_t desc_rec;

char

desc[5ð];

} addep_attributes;

/ᑍ

ᑍ/

main

int main()

{

error_code_struct error_code;

addep_attributes attrib_keys;

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ Initialize the error code parameter.

ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

error_code.ec_fields.Bytes_Provided=sizeof(error_code_struct);

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ Set the total number of exit program attributes that we are

ᑍ/

/ᑍ specifying on the call. We will let the API take the default ᑍ/

/ᑍ for the attributes that we are not specifying. ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

attrib_keys.num_rec=3;

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ Set the values for the three attributes that we will be

/ᑍ specifying:

ᑍ/

/ᑍ

Replace exit program

= 1

(CHAR(1) field)

(BIN(4) field)

Exit program data CCSID = 37

Exit program description='THIS IS A TEST EXIT PROGRAM' ᑍ/

(CHAR(5ð) field)

ᑍ/

/ᑍ The structure for the exit program attributes defined above is ᑍ/

/ᑍ as follows:

/ᑍ

ᑍ/

/ᑍ

typedef struct {

int

Qus_Vlen_Rec_4_t replace_rec;

char replace;

Qus_Vlen_Rec_4_t CCSID_rec;

int CCSID;

num_rec;

Qus_Vlen_Rec_4_t desc_rec;

char

desc[5ð];

} addep_attributes;

Chapter 9. Common API Programming Errors 9-23

Download from Www.Somanuals.com. All Manuals Search And Download.

/ᑍ

ᑍ/

/ᑍ and the Qus_Vlen_Rec_4_t structure is defined in

/ᑍ qus.h (included by qusrgfa1) as:

/ᑍ

typedef _Packed struct Qus_Vlen_Rec_4 {

int Length_Vlen_Record;

int Control_Key;

int Length_Data;

ᑍᑍchar Data[];-> this field is supplied by

the user

} Qus_Vlen_Rec_4_t;

/ᑍ This structure is mapped in bytes as follows:

/ᑍ

{

BIN(4) - num_rec

BIN(4) - length variable length record for replace key ᑍ/

BIN(4) - replace key

BIN(4) - length replace data

CHAR(1) - replace data

ᑍ/

BIN(4) - length variable length record for CCSID key ᑍ/

BIN(4) - CCSID key

BIN(4) - length CCSID data

BIN(4) - CCSID data

ᑍ/

BIN(4) - length variable length record for description ᑍ/

key

ᑍ/

BIN(4) - description key

BIN(4) - length description key

CHAR(5ð) - description data

}

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

attrib_keys.replace_rec.Length_Vlen_Record=13;

attrib_keys.replace_rec.Control_Key=4;

attrib_keys.replace_rec.Length_Data=1;

attrib_keys.replace='1';

.15/

attrib_keys.CCSID_rec.Length_Vlen_Record=16;

attrib_keys.CCSID_rec.Control_Key=3;

attrib_keys.CCSID_rec.Length_Data=4;

attrib_keys.CCSID=37;

attrib_keys.desc_rec.Length_Vlen_Record=39;

attrib_keys.desc_rec.Control_Key=2;

attrib_keys.desc_rec.Length_Data=27;

memcpy(&attrib_keys.desc,

"THIS IS A TEST EXIT PROGRAM",27);

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ Call the API to add the exit program.

ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

QusAddExitProgram("EXAMPLE_EXIT_POINT ",

"EXMPð1ðð",

"EXAMPLEPGMEXAMPLELIB",

"EXAMPLE EXIT PROGRAM DATA",

25,

&attrib_keys,

&error_code);

9-24 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

if (error_code.ec_fields.Bytes_Available != ð)

{

printf("ATTEMPT TO ADD AN EXIT PROGRAM FAILED WITH EXCEPTION:%.7s",

error_code.ec_fields.Exception_Id);

exit(1);

}

} /ᑍ end program ᑍ/

Defining Byte Alignment—Example of Correct Coding

The following example program shows a CHAR(3) bytes reserved field being added

to the structure to maintain 4-byte alignment (shown at .16/ on page 9-25). This

corresponds to .14/ on page 9-23 in the incorrect coding example. The 3 reserved

bytes are included in the length of the replace variable-length record. .17/ on

page 9-26 shows the variable-length record is now 4-byte aligned (record length of

16 is divisible by 4). This corresponds to .15/ on page 9-24 in the incorrect coding

example.

/ᑍ

ᑍ/

/ᑍProgram Name: PGM2

/ᑍ

/ᑍProgram Language: ILE C

/ᑍ

/ᑍDescription:

This program illustrates proper byte

alignment when using variable length

records.

/ᑍ

/ᑍHeader Files Included: <stdio.h>

/ᑍ

<signal.h>

<string.h>

<stdlib.h>

<qusrgfa1.h>

<qusec.h>

/ᑍ

<qliept.h>

/ᑍ

/ᑍ APIs Used:

QusAddExitProgram

- Add an exit program

/ᑍ

Includes

ᑍ/

#include <stdio.h>

#include <signal.h>

#include <string.h>

#include <stdlib.h>

#include <qusrgfa1.h>

#include <qusec.h>

#include <qliept.h>

/ᑍ

Structures

ᑍ/

typedef struct {

/ᑍ Error code

ᑍ/

Qus_EC_t ec_fields;

char

exception_data[1ðð];

} error_code_struct;

typedef struct {

/ᑍ Exit program attribute keysᑍ/

int

num_rec;

Qus_Vlen_Rec_4_t replace_rec;

char

replace;

Reserved[3];

.16/

Chapter 9. Common API Programming Errors 9-25

Download from Www.Somanuals.com. All Manuals Search And Download.

Qus_Vlen_Rec_4_t CCSID_rec;

int CCSID;

Qus_Vlen_Rec_4_t desc_rec;

char

desc[1ðð];

} addep_attributes;

/ᑍ

ᑍ/

main

int main()

{

error_code_struct error_code;

addep_attributes attrib_keys;

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ Initialize the error code parameter.

ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

error_code.ec_fields.Bytes_Provided=sizeof(error_code_struct);

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ Set the total number of exit program attributes that we are

ᑍ/

/ᑍ specifying on the call. We will let the API take the default ᑍ/

/ᑍ for the attributes that we are not specifying. ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

attrib_keys.num_rec=3;

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ Set the values for the three attributes that we will be

/ᑍ specifying:

ᑍ/

/ᑍ

Replace exit program

= 1

(CHAR(1) field)

(BIN(4) field)

Exit program description='THIS IS A TEST EXIT PROGRAM'

(CHAR(5ð) field)

Exit program data CCSID = 37

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

attrib_keys.replace_rec.Length_Vlen_Record=16;

attrib_keys.replace_rec.Control_Key=4;

attrib_keys.replace_rec.Length_Data=1;

attrib_keys.replace='1';

.17/

attrib_keys.CCSID_rec.Length_Vlen_Record=16;

attrib_keys.CCSID_rec.Control_Key=3;

attrib_keys.CCSID_rec.Length_Data=4;

attrib_keys.CCSID=37;

attrib_keys.desc_rec.Length_Vlen_Record=39;

attrib_keys.desc_rec.Control_Key=2;

attrib_keys.desc_rec.Length_Data=27;

memcpy(&attrib_keys.desc,"THIS IS A TEST EXIT PROGRAM",27);

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ Call the API to add the exit program.

ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

QusAddExitProgram("EXAMPLE_EXIT_POINT ",

"EXMPð1ðð",

"EXAMPLEPGMEXAMPLELIB",

"EXAMPLE EXIT PROGRAM DATA",

25,

&attrib_keys,

&error_code);

if (error_code.ec_fields.Bytes_Available != ð)

{

printf("ATTEMPT TO ADD AN EXIT PROGRAM FAILED WITH EXCEPTION: %.7s",

error_code.ec_fields.Exception_Id);

exit(1);

}

} /ᑍ end program ᑍ/

9-26 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Using Offsets in a User Space

An offset indicates where in a structure that specific information should start. When

offsets are correctly used, programs can extract specific pieces of data from a

structure and perform actions on that data.

Incorrectly working with offsets can produce errors by API users when coding in a

base 1 language such as RPG and COBOL. One way to determine the base of a

language is how a programmer specifies the first element of an array. In a base 0

language, the first element is number 0. In base 1 languages, the first element is

number 1.

The example programs in the following topics are coded using RPG. RPG is a

base 1 language while the APIs produce information using a base of 0. To com-

pensate for APIs producing information at base 0, the API user must add 1 to all

decimal and hexadecimal offsets to formats that are contained in the System API

Reference book.

Using Offsets in a User Space—Example of Incorrect Coding

The point for beginning to read a user space is shown at .18/ on page 9-30. The

data is read and placed into a user space. However, the data in the user space is

incorrect because the starting position to start was off by 1. This program started

to retrieve the data one character (or position) too soon. The correct coding is

shown at .19/ on page 9-34.

Iᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Iᑍ

IᑍProgram Name: APIUG1

Iᑍ

IᑍProgramming Language: RPG

Iᑍ

IᑍDescription: This sample program illustrates the incorrect

Iᑍ

way of using the offset in a user space.

IᑍHeader Files Included: QUSGEN - Generic Header of a User Space

Iᑍ

QUSEC - Error Code Parameter

(Copied into Program)

QUSLOBJ - List Objects API

IᑍAPIs Used: QUSCRTUS - Create User Space

Iᑍ

QUSLOBJ - List Objects

QUSRTVUS - Retrieve User Space

QUSDLTUS - Delete User Space

Iᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Iᑍ

Iᑍ Generic Header of a User Space Include

Iᑍ

I/COPY QSYSINC/QRPGSRC,QUSGEN

Iᑍ

Iᑍ Error Code Parameter Include for the APIs

Iᑍ

Iᑍ The following QUSEC include is copied into this program

Iᑍ so that the variable length field can be defined as a

Iᑍ fixed length.

Chapter 9. Common API Programming Errors 9-27

Download from Www.Somanuals.com. All Manuals Search And Download.

Iᑍ

Iᑍᑍᑍ START HEADER FILE SPECIFICATIONS ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Iᑍ

IᑍHeader File Name: H/QUSEC

Iᑍ

IᑍDescriptive Name: Error Code Parameter.

Iᑍ

Iᑍ5763-SS1 (C) Copyright IBM Corp. 1994,1994

IᑍUS Government Users Restricted Rights -

IᑍUse, duplication or disclosure restricted

Iᑍby GSA ADP Schedule Contract with IBM Corp.

Iᑍ

IᑍLicensed Materials-Property of IBM

Iᑍ

IᑍDescription: Include header file for the error code parameter.

Iᑍ

IᑍHeader Files Included: None.

Iᑍ

IᑍMacros List: None.

Iᑍ

IᑍStructure List: Qus_EC_t

Iᑍ

IᑍFunction Prototype List: None.

Iᑍ

IᑍChange Activity:

Iᑍ

IᑍCFD List:

Iᑍ

IᑍFLAG REASON

LEVEL DATE PGMR

CHANGE DESCRIPTION

Iᑍ---- ------------ ----- ------ --------- ----------------------

Iᑍ$Að= D2862ððð

Iᑍ

3D1ð 9312ð1 DPOHLSON: New Include

IᑍEnd CFD List.

Iᑍ

IᑍAdditional notes about the Change Activity

IᑍEnd Change Activity.

Iᑍᑍᑍ END HEADER FILE SPECIFICATIONS ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Iᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

IᑍRecord structure for Error Code Parameter

Iᑍᑍᑍᑍ

ᑍᑍᑍ

IᑍNOTE: The following type definition only defines the corrected

Iᑍ portion of the format. Varying length field Exception

Iᑍ Data will not be defined here.

Iᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

IQUSBN

Iᑍ

Qus EC

B 1 4ðQUSBNB

Bytes Provided

B 5 8ðQUSBNC

Bytes Available

9 15 QUSBND

Exception Id

16 16 QUSBNF

Reserved

17 17 QUSBNG

Iᑍ

9-28 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Iᑍ

Varying length

17 1ðð QUSBNG

Iᑍ

Iᑍ List Objects API Include

Iᑍ

I/COPY QSYSINC/QRPGSRC,QUSLOBJ

Iᑍ

Iᑍ Qualified User Space Data Structure

Iᑍ

IUSERSP

I I

'APIUG1

'QGPL

1 1ð USRSPC

11 2ð SPCLIB

I I

iᑍ Qualified Object Name Data Structure

IOBJECT

I I

Iᑍ

'ᑍALL

'QGPL

1 1ð OBJNAM

11 2ð OBJLIB

Iᑍ Miscellaneous Data Structure

Iᑍ

Iᑍ Set up parameters for the Create User Space API

I I

'TESTUSRSPC'

X'ðð'

1 1ð EXTATR

11 11 INTVAL

12 12 RSVD1

256

'ᑍUSE

B 13 16ðINTSIZ

17 26 PUBAUT

27 76 TEXT

'TEXT DESCRIPTION -

'FOR USER SPACE -

'CALLED APIUG1 '

I I

'ᑍYES

77 87 REPLAC

Iᑍ Set up parameters for the List Objects API

I I

'OBJLð1ðð'

'ᑍALL

88 95 FORMAT

96 1ð5 OBJTYP

1ð6 1ð8 RSVD2

Iᑍ Set up parameters for the Retrieve User Space API

I I

192

B 1ð9 112ðSTRPOS

B 113 116ðLENDTA

B 117 12ððCOUNT

Cᑍ

Cᑍ Create a user space called APIUG1 in library QGPL.

Cᑍ

Z-ADD1ðð

CALL 'QUSCRTUS'

PARM

QUSBNB

USERSP

EXTATR

INTSIZ

INTVAL

PUBAUT

TEXT

PARM

REPLAC

QUSBN

PARM

Cᑍ See if any errors were returned in the error code parameter.

Cᑍ

EXSR ERRCOD

Cᑍ Get a list of all objects in the QGPL library.

Cᑍ

CALL 'QUSLOBJ'

PARM

USERSP

Chapter 9. Common API Programming Errors 9-29

Download from Www.Somanuals.com. All Manuals Search And Download.

PARM

FORMAT

OBJECT

OBJTYP

QUSBN

Cᑍ See if any errors were returned in the error code parameter.

Cᑍ

EXSR ERRCOD

Cᑍ Look at the generic header.

Cᑍ The generic header contains information

Cᑍ about the list data section that is needed when processing

Cᑍ the entries.

Cᑍ

CALL 'QUSRTVUS'

PARM

USERSP

STRPOS

LENDTA

QUSBP

QUSBN

Cᑍ See if any errors were returned in the error code parameter.

Cᑍ

EXSR ERRCOD

Cᑍ Check the information status field, QUSBPJ, to see if

Cᑍ the API was able to return all the information.

Cᑍ Possible values are:

Cᑍ C -- Complete and accurate

Cᑍ P -- Partial but accurate

Cᑍ I -- Incomplete

Cᑍ

QUSBPJ

IFEQ 'C'

OREQ 'P'

Cᑍ

Cᑍ Check to see if any entries were put into the user space.

Cᑍ

QUSBPS

IFGT ð

Z-ADD1

COUNT

STRPOS .18/

LENDTA

Z-ADDQUSBPQ

Z-ADD3ð

Cᑍ Walk through all the entries in the user space.

COUNT

DOWLEQUSBPS

CALL 'QUSRTVUS'

PARM

USERSP

STRPOS

LENDTA

QUSDM

PARM

QUSBN

Cᑍ See if any errors were returned in the error code parameter.

EXSR ERRCOD

Cᑍ

Cᑍ Process the objects.

Cᑍ

ADD 1

COUNT

STRPOS

ADD QUSBPT

ENDDO

ENDIF

Cᑍ

Cᑍ Information in the user space is not accurate

Cᑍ

9-30 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Cᑍ

ENDIF

Cᑍ Delete the user space called APIUG1 in library QGPL.

Cᑍ

CALL 'QUSDLTUS'

PARM

USERSP

QUSBN

Cᑍ See if any errors were returned in the error code parameter.

Cᑍ

EXSR ERRCOD

SETON

RETRN

Cᑍ End of MAINLINE

Cᑍ

Cᑍ Subroutine to handle errors returned in the error code

Cᑍ parameter.

Cᑍ

ERRCOD

QUSBNC

BEGSR

IFGT ð

Cᑍ

Cᑍ Process errors returned from the API.

Cᑍ

END

ENDSR

Using Offsets in a User Space—Example of Correct Coding

The following example program has code in it that compensates for the API offset

convention of that starts at 0. The code adds 1 to the starting position (STRPOS)

offset. This is shown at .19/ on page 9-34.

Iᑍ

IᑍProgram Name: APIUG2

Iᑍ

IᑍProgramming Language: RPG

Iᑍ

IᑍDescription: This sample program illustrates the correct

Iᑍ

way of using offsets in user space.

IᑍHeader Files Included: QUSGEN - Generic Header of a User Space

Iᑍ

QUSEC - Error Code Parameter

(Copied into Program)

QUSLOBJ - List Objects API

IᑍAPIs Used: QUSCRTUS - Create User Space

Iᑍ

QUSLOBJ - List Objects

QUSRTVUS - Retrieve User Space

QUSDLTUS - Delete User Space

Iᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Iᑍ

Iᑍ Generic Header of a User Space Include

Iᑍ

I/COPY QSYSINC/QRPGSRC,QUSGEN

Iᑍ

Iᑍ Error Code Parameter Include for the APIs

Iᑍ

Chapter 9. Common API Programming Errors 9-31

Download from Www.Somanuals.com. All Manuals Search And Download.

Iᑍ The following QUSEC include is copied into this program

Iᑍ so that the variable length field can be defined as a

Iᑍ fixed length.

Iᑍ

Iᑍᑍᑍ START HEADER FILE SPECIFICATIONS ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Iᑍ

IᑍHeader File Name: H/QUSEC

Iᑍ

IᑍDescriptive Name: Error Code Parameter.

Iᑍ

Iᑍ5763-SS1 (C) Copyright IBM Corp. 1994,1994

IᑍUS Government Users Restricted Rights -

IᑍUse, duplication or disclosure restricted

Iᑍby GSA ADP Schedule Contract with IBM Corp.

Iᑍ

IᑍLicensed Materials-Property of IBM

Iᑍ

IᑍDescription: Include header file for the error code parameter.

Iᑍ

IᑍHeader Files Included: None.

Iᑍ

IᑍMacros List: None.

Iᑍ

IᑍStructure List: Qus_EC_t

Iᑍ

IᑍFunction Prototype List: None.

Iᑍ

IᑍChange Activity:

Iᑍ

IᑍCFD List:

Iᑍ

IᑍFLAG REASON

LEVEL DATE PGMR

CHANGE DESCRIPTION

Iᑍ---- ------------ ----- ------ --------- ----------------------

Iᑍ$Að= D2862ððð

Iᑍ

3D1ð 9312ð1 DPOHLSON: New Include

IᑍEnd CFD List.

Iᑍ

IᑍAdditional notes about the Change Activity

IᑍEnd Change Activity.

Iᑍᑍᑍ END HEADER FILE SPECIFICATIONS ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Iᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

IᑍRecord structure for Error Code Parameter

Iᑍᑍᑍᑍ

ᑍᑍᑍ

IᑍNOTE: The following type definition only defines the corrected

Iᑍ portion of the format. Varying length field Exception

Iᑍ Data will not be defined here.

Iᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

IQUSBN

Iᑍ

Qus EC

B 1 4ðQUSBNB

Iᑍ

Bytes Provided

B 5 8ðQUSBNC

Bytes Available

9 15 QUSBND

Exception Id

16 16 QUSBNF

9-32 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Iᑍ

Reserved

17 17 QUSBNG

Iᑍ

Varying length

17 1ðð QUSBNG

Iᑍ

Iᑍ List Objects API Include

Iᑍ

I/COPY QSYSINC/QRPGSRC,QUSLOBJ

Iᑍ

Iᑍ Qualified User Space Data Structure

Iᑍ

IUSERSP

I I

'APIUG1

'QGPL

1 1ð USRSPC

11 2ð SPCLIB

I I

iᑍ Qualified Object Name Data Structure

IOBJECT

I I

Iᑍ

'ᑍALL

'QGPL

1 1ð OBJNAM

11 2ð OBJLIB

Iᑍ Miscellaneous Data Structure

Iᑍ

Iᑍ Set up parameters for the Create User Space API

I I

'TESTUSRSPC'

X'ðð'

1 1ð EXTATR

11 11 INTVAL

12 12 RSVD1

256

'ᑍUSE

B 13 16ðINTSIZ

17 26 PUBAUT

27 76 TEXT

'TEXT DESCRIPTION -

'FOR USER SPACE -

'CALLED APIUG2 '

I I

'ᑍYES

77 87 REPLAC

Iᑍ Set up parameters for the List Objects API

I I

'OBJLð1ðð'

'ᑍALL

88 95 FORMAT

96 1ð5 OBJTYP

1ð6 1ð8 RSVD2

Iᑍ Set up parameters for the Retrieve User Space API

I I

192

B 1ð9 112ðSTRPOS

B 113 116ðLENDTA

B 117 12ððCOUNT

Cᑍ

Cᑍ Create a user space called APIUG1 in library QGPL.

Cᑍ

Z-ADD1ðð

CALL 'QUSCRTUS'

PARM

QUSBNB

USERSP

EXTATR

INTSIZ

INTVAL

PUBAUT

TEXT

PARM

REPLAC

QUSBN

PARM

Cᑍ See if any errors were returned in the error code parameter.

EXSR ERRCOD

Cᑍ

Cᑍ Get a list of all objects in the QGPL library.

Chapter 9. Common API Programming Errors 9-33

Download from Www.Somanuals.com. All Manuals Search And Download.

Cᑍ

CALL 'QUSLOBJ'

PARM

USERSP

FORMAT

OBJECT

OBJTYP

QUSBN

Cᑍ See if any errors were returned in the error code parameter.

Cᑍ

EXSR ERRCOD

Cᑍ Look at the generic header. This contains information

Cᑍ about the list data section that is needed when processing

Cᑍ the entries.

Cᑍ

CALL 'QUSRTVUS'

PARM

USERSP

STRPOS

LENDTA

QUSBP

QUSBN

Cᑍ See if any errors were returned in the error code parameter.

EXSR ERRCOD

Cᑍ

Cᑍ Check the information status field, QUSBPJ, to see if the

Cᑍ API was able to return all the information. Possible values

Cᑍ are: C -- Complete and accurate

Cᑍ

P -- Partial but accurate

I -- Incomplete.

QUSBPJ

IFEQ 'C'

OREQ 'P'

Cᑍ

Cᑍ Check to see if any entries were put into the user space.

Cᑍ

QUSBPS

IFGT ð

Z-ADD1

COUNT

Cᑍ Because RPG is Base 1, the offset must be increased by one.

Cᑍ

QUSBPQ

ADD 1

Z-ADD3ð

STRPOS

LENDTA

.19/

Cᑍ Walk through all the entries in the user space.

COUNT

DOWLEQUSBPS

CALL 'QUSRTVUS'

PARM

USERSP

STRPOS

LENDTA

QUSDM

PARM

QUSBN

Cᑍ See if any errors were returned in the error code parameter.

EXSR ERRCOD

Cᑍ

Cᑍ Process the objects.

Cᑍ

ADD 1

COUNT

STRPOS

ADD QUSBPT

ENDDO

9-34 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Cᑍ

ENDIF

Cᑍ Information in the user space is not accurate.

Cᑍ

ENDIF

Cᑍ

Cᑍ Delete the user space called APIUG1 in library QGPL.

Cᑍ

CALL 'QUSDLTUS'

PARM

USERSP

QUSBN

Cᑍ See if any errors were returned in the error code parameter.

Cᑍ

EXSR ERRCOD

SETON

RETRN

Cᑍ End of MAINLINE

Cᑍ

Cᑍ Subroutine to handle errors returned in the error code

Cᑍ parameter.

Cᑍ

ERRCOD

QUSBNC

BEGSR

IFGT ð

Cᑍ

Cᑍ Process errors returned from the API.

Cᑍ

END

ENDSR

Chapter 9. Common API Programming Errors 9-35

Download from Www.Somanuals.com. All Manuals Search And Download.

Coding for New Function

New function from IBM can cause programs to fail if the programs do not allow for

the handling of a new function.

The example programs in the following topics create a list of all objects that adopt

authority and then process the objects based on their object type. The new func-

tion added is the addition of another object type, *SRVPGM, that can adopt owner

authority.

A general theme of this example is never to assume that the values returned by an

API are static. OS/400 is continually evolving. While the example is based on the

addition of a new object type, this philosophy should be applied to any output of an

API. For example, if an API today can return *YES or *NO, you should discretely

check for these values because *MAYBE might be valid in the future. Similarly, if

your application assumes a particular integer output has a positive nonzero value

(an offset for instance), you should check for a positive nonzero value because

future releases could return a negative value to indicate new function.

Coding for New Function—Example of Incorrect Coding

In this example program, a check is made to determine the object type. This is

shown at .2ð/ on page 9-40. The example program considers only object types of

*SQLPKG or *PGMs. This is because they are the only object types that could

adopt owner authority before Version 2 Release 3. Since that time, a new object

type of *SRVPGM has been introduced. *SRVPGM can adopt owner authority.

Hence, this example program processes *SRVPGM objects as if they were *PGM

objects. The correct coding is shown at .23/ on page 9-47.

Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Dᑍ

DᑍProgram Name: PGM1

Dᑍ

DᑍProgram Language: ILE RPG

Dᑍ

DᑍDescription: This example program demonstrates how a program can

Dᑍ

be "broken" by new functions introduced on the AS/4ðð.

DᑍHeader Files Included: QUSGEN - Generic Header of a User Space

Dᑍ

(Copied Into Program)

Error Code Parameter

(Copied Into Program)

QUSEC -

QSYLOBJP - List Objects API

(Copied Into Program)

DᑍAPIs Used: QUSCRTUS - Create User Space

Dᑍ

QSYLOBJP - List Objects That Adopt Owner Authority

QUSROBJD - Retrieve Object Description

QUSPTRUS - Retrieve Pointer to User Space

Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Dᑍ

Dᑍ This program demonstrates how a program can be "broken" by

Cᑍ new functions introduced on the AS/4ðð.

Dᑍ

9-36 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

D/COPY QSYSINC/QRPGLESRC,QUSEC

Dᑍ

DSPC_NAME

DSPC_SIZE

DSPC_INIT

DLSTPTR

2ð

INZ('ADOPTS

INZ(X'ðð')

QTEMP

9B ð INZ(1)

ᑍ

DSPCPTR

DARR

DRCVVAR

DRCVVARSIZ

BASED(LSTPTR) DIM(32767)

9B ð INZ(%SIZE(RCVVAR))

Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Dᑍ

Dᑍ The following QUSGEN include is copied into this program so

Dᑍ that it can be declared as BASED on SPCPTR (shown at .21/

Dᑍ in the incorrect and correct programs on pages

Dᑍ 9-37 and 9-45, respectively)

Dᑍ

Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Dᑍ

DᑍHeader File Name: H/QUSGEN

Dᑍ

DᑍDescriptive Name: Format structures for User Space for ILE/C

Dᑍ

Dᑍ5763-SS1 (C) Copyright IBM Corp. 1994, 1994

DᑍUS Government Users Restricted Rights -

DᑍUse, duplication or disclosure restricted

Dᑍby GSA ADP Schedule Contract with IBM Corp.

Dᑍ

DᑍDescription: Contains the Generic Record format headers

Dᑍ

for the user space.

DᑍHeader Files Included: none.

Dᑍ

DᑍMacros List: none.

Dᑍ

DᑍStructure List: Qus_Generic_Header_ð1ðð

Dᑍ

Qus_Generic_Header_ð3ðð

DᑍFunction Prototype List: none.

Dᑍ

DᑍChange Activity:

Dᑍ

DᑍCFD List:

Dᑍ

DᑍFLAG REASON

LEVEL DATE PGMR

CHANGE DESCRIPTION

Dᑍ---- ------------ ----- ------ --------- ----------------------

Dᑍ$Að= D2862ððð

DᑍEnd CFD List.

Dᑍ

DᑍAdditional notes about the Change Activity

DᑍEnd Change Activity.

3D1ð 94ð213 LUPA:

New Include

Dᑍᑍᑍ END HEADER FILE SPECIFICATIONS ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

DᑍType Definition for the User Space Generic Header.

Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

DQUSHð1ðð

BASED(SPCPTR)

.21/

Chapter 9. Common API Programming Errors 9-37

Download from Www.Somanuals.com. All Manuals Search And Download.

Dᑍ

D QUSUA

Dᑍ

D QUSSGH

Dᑍ

D QUSSRL

Dᑍ

D QUSFN

Dᑍ

D QUSAU

Dᑍ

D QUSDTC

Dᑍ

D QUSIS

Dᑍ

D QUSSUS

Dᑍ

D QUSOIP

Dᑍ

D QUSSIP

Dᑍ

D QUSOHS

Dᑍ

D QUSSHS

Dᑍ

D QUSOLD

Dᑍ

D QUSSLD

Dᑍ

D QUSNBRLE

Dᑍ

Qus Generic Header ð1ðð

User Area

68B ð

Size Generic Header

Structure Release Level

Format Name

8ð

9ð

API Used

1ð3

Date Time Created

Information Status

Size User Space

Offset Input Parameter

Size Input Parameter

Offset Header Section

Size Header Section

Offset List Data

Size List Data

1ð4

1ð5

1ð9

113

117

121

125

129

133

137

141

145

147

15ð

151

1ð4

1ð8B ð

112B ð

116B ð

12ðB ð

124B ð

128B ð

132B ð

136B ð

14ðB ð

144B ð

146

Number List Entries

Size Each Entry

CCSID List Ent

D QUSSEE

Dᑍ

D QUSSIDLE

Dᑍ

D QUSCID

Dᑍ

D QUSLID

Dᑍ

D QUSSLI

Dᑍ

D QUSERVEDðð

Dᑍ

Country ID

149

Language ID

15ð

Partial List Indicator

192

Reserved

Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Dᑍ

Dᑍ The following QSYLOBJP include is copied into this program so

Dᑍ that it can be declared as BASED on LSTPTR (shown at .22/

Dᑍ in the incorrect and correct coding on

Dᑍ pages 9-39 and 9-46, respectively)

Dᑍ

Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Dᑍᑍᑍ START HEADER FILE SPECIFICATIONS ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Dᑍ

DᑍHeader File Name: H/QSYLOBJP

Dᑍ

DᑍDescriptive Name: List Objects That Adopt Owner Authority.

Dᑍ

9-38 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

DᑍDescription: Include header file for the QSYLOBJP API.

Dᑍ

DᑍHeader Files Included: H/QSYLOBJP

Dᑍ

H/QSY

DᑍMacros List: None.

Dᑍ

DᑍStructure List: OBJPð1ðð

Dᑍ

OBJPð2ðð

Qsy_OBJP_Header

DᑍFunction Prototype List: QSYLOBJP

Dᑍ

DᑍChange Activity:

Dᑍ

DᑍCFD List:

Dᑍ

DᑍFLAG REASON

LEVEL DATE PGMR

CHANGE DESCRIPTION

Dᑍ---- ------------ ----- ------ --------- ----------------------

Dᑍ$Að= D2862ððð

Dᑍ

3D1ð 931222 XZYð432: New Include

DᑍEnd CFD List.

Dᑍ

DᑍAdditional notes about the Change Activity

DᑍEnd Change Activity.

Dᑍᑍᑍ END HEADER FILE SPECIFICATIONS ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

DᑍPrototype for calling Security API QSYLOBJP

Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

D QSYLOBJP

'QSYLOBJP'

Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

DᑍHeader structure for QSYLOBJP

Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

DQSYOBJPH

Dᑍ

D QSYUNðð

Dᑍ

D QSYCVðð

Dᑍ

BASED(LSTPTR)

.22/

Qsy OBJP Header

1ð

User name

3ð

Continuation Value

Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

DᑍRecord structure for OBJPð1ðð format

Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

DQSYð1ððLð2

BASED(LSTPTR) .22/

Qsy OBJPð1ðð List

Dᑍ

D QSYNAMEð5

1ð

2ð

D QSYBRARYð5

Dᑍ

Qualified object name

D QSYOBJT12

3ð

Dᑍ

Object type

Object in use

D QSYOBJIU

Dᑍ

Cᑍ

Cᑍ Start of mainline

Cᑍ

EXSR

INIT

PROCES

DONE

Cᑍ

Chapter 9. Common API Programming Errors 9-39

Download from Www.Somanuals.com. All Manuals Search And Download.

Cᑍ Start of subroutines

Cᑍ

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

PROCES

BEGSR

Cᑍ

Cᑍ This subroutine processes each entry returned by QSYLOBJP

Cᑍ

Cᑍ Do until the list is complete

Cᑍ

MOVE

QUSIS

'C'

LST_STATUS

Cᑍ

LST_STATUS

DOUEQ

Cᑍ If valid information was returned

Cᑍ

QUSIS

IFEQ

OREQ

'C'

'P'

Cᑍ

Cᑍ and list entries were found

Cᑍ

QUSNBRLE

IFGT

Cᑍ

Cᑍ set LSTPTR to the first byte of the user space

Cᑍ

EVAL

LSTPTR = SPCPTR

Cᑍ increment LSTPTR to the first list entry

Cᑍ

EVAL

LSTPTR = %ADDR(ARR(QUSOLD + 1))

Cᑍ and process all of the entries

Cᑍ

IFEQ

QUSNBRLE

'ᑍSQLPKG'

QSYOBJT12

Cᑍ

Cᑍ Process ᑍSQLPKG type

Cᑍ

ELSE

.2ð/

Cᑍ

Cᑍ This 'ELSE' logic is the potential bug in this program. In

Cᑍ releases prior to V2R3 only ᑍSQLPKGs and ᑍPGMs could adopt

Cᑍ owner authority, and this program is assuming that if the

Cᑍ object type is not ᑍSQLPKG then it must be a ᑍPGM. In V2R3

Cᑍ a new type of object (the ᑍSRVPGM) was introduced. As this

Cᑍ program is written, all ᑍSRVPGMs that adopt the owner profile |

Cᑍ will be processed as if they were ᑍPGMs -- this erroneous

↓

Cᑍ processing could definitely cause problems.

Cᑍ

QSYNAMEð5

DSPLY

END

Cᑍ

Cᑍ after each entry, increment LSTPTR to the next entry

Cᑍ

EVAL

END

LSTPTR = %ADDR(ARR(QUSSEE + 1))

END

Cᑍ

Cᑍ When all entries in this user space have been processed, check

9-40 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Cᑍ if more entries exist than can fit in one user space

Cᑍ

QUSIS

IFEQ

'P'

Cᑍ by resetting LSTPTR to the start of the user space

Cᑍ

EVAL

LSTPTR = SPCPTR

Cᑍ and then incrementing LSTPTR to the input parameter header

Cᑍ

EVAL

LSTPTR = %ADDR(ARR(QUSOIP + 1))

Cᑍ

Cᑍ If the continuation handle in the input parameter header is

Cᑍ blank, then set the list status to Complete

Cᑍ

QSYCVðð

IFEQ

MOVE

ELSE

ᑍBLANKS

'C'

LST_STATUS

Cᑍ

Cᑍ Else, call QSYLOBJP reusing the User Space to get more

Cᑍ List entries

Cᑍ

MOVE

EXSR

MOVE

END

QSYCVðð

GETLST

QUSIS

CONTIN_HDL

LST_STATUS

END

ELSE

Cᑍ

Cᑍ And if an unexpected status, log an error (not shown) and exit

Cᑍ

EXSR

END

DONE

END

ENDSR

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Cᑍ

GETLST

BEGSR

Cᑍ Call QSYLOBJP to generate a list

Cᑍ The continuation handle is set by the caller of this subroutine.

Cᑍ

CALL

PARM

QSYLOBJP

SPC_NAME

MBR_LIST

USR_PRF

OBJ_TYPE

CONTIN_HDL

QUSEC

'OBJPð1ðð'

'ᑍCURRENT'

'ᑍALL'

1ð

2ð

Cᑍ

Cᑍ Check for errors on QSYLOBJP

Cᑍ

QUSBAVL

IFGT

MOVEL

EXSR

END

'QSYLOBJP'

APIERR

APINAM

1ð

ENDSR

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

INIT

BEGSR

Chapter 9. Common API Programming Errors 9-41

Download from Www.Somanuals.com. All Manuals Search And Download.

Cᑍ

Cᑍ One-time initialization code for this program

Cᑍ

Cᑍ Set error code structure to not use exceptions

Cᑍ

EVAL

QUSBPRV = %SIZE(QUSEC)

Cᑍ

Cᑍ Check to see if the user space was previously created in

Cᑍ QTEMP. If it was, simply reuse it.

Cᑍ

CALL

PARM

'QUSROBJD'

RCVVAR

RCVVARSIZ

ROBJD_FMT

SPC_NAME

OBJ_TYPE

QUSEC

'OBJDð1ðð'

'ᑍUSRSPC'

1ð

Cᑍ

Cᑍ Check for errors on QUSROBJD

Cᑍ

QUSBAVL

IFGT

Cᑍ If CPF98ð1, then user space was not found

Cᑍ

QUSEI

IFEQ

'CPF98ð1'

Cᑍ So create a user space for the list generated by QSYLOBJP

Cᑍ

CALL

PARM

'QUSCRTUS'

SPC_NAME

'QSYLOBJP ' EXT_ATTR

SPC_SIZE

1ð

SPC_INIT

SPC_AUT

'ᑍALL'

ᑍBLANKS

'ᑍYES'

1ð

5ð

1ð

SPC_TEXT

SPC_REPLAC

QUSEC

'ᑍUSER'

SPC_DOMAIN

1ð

Cᑍ Check for errors on QUSCRTUS

Cᑍ

QUSBAVL

IFGT

MOVEL

EXSR

END

'QUSCRTUS'

APIERR

APINAM

1ð

Cᑍ

Cᑍ Else, an error occurred accessing the user space

Cᑍ

ELSE

MOVEL

EXSR

END

'QUSROBJD'

APIERR

APINAM

1ð

END

Cᑍ

Cᑍ Set QSYLOBJP (using GETLST) to start a new list

Cᑍ

MOVE

EXSR

ᑍBLANKS

GETLST

CONTIN_HDL

9-42 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Cᑍ

Cᑍ Get a resolved pointer to the user space for performance

Cᑍ

CALL

PARM

'QUSPTRUS'

SPC_NAME

SPCPTR

QUSEC

Cᑍ

Cᑍ Check for errors on QUSPTRUS

Cᑍ

QUSBAVL

IFGT

MOVEL

EXSR

END

'QUSPTRUS'

APIERR

APINAM

1ð

ENDSR

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Cᑍ

APIERR

BEGSR

Cᑍ Log any error encountered, and exit the program

Cᑍ

APINAM

DSPLY

EXSR

QUSEI

DONE

ENDSR

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Cᑍ

DONE

BEGSR

Cᑍ Exit the program

Cᑍ

EVAL

RETURN

ENDSR

ᑍINLR = '1'

Coding for New Function—Example of Correct Coding

In the following example program, code has been written that checks for object

types *SRVPGM, *PGM, and *SQLPKG. If an object type is encountered that is

unknown (it does not match *SRVPGM, *PGM, or *SQLPKG), an error is logged

and an exit from the program takes place.

The coding to handle the integration of new function (in this case the new object

type that can adopt owner authority) is shown at .23/ on page 9-47.

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Cᑍ

CᑍProgram Name: PGM2

Cᑍ

CᑍProgram Language: ILE RPG

Cᑍ

CᑍDescription: This example program demonstrates how a program can

Cᑍ

be coded to accept new functions introduced on the AS/4ðð.

CᑍHeader Files Included: QUSGEN - Generic Header of a User Space

Dᑍ

Cᑍ

Dᑍ

Cᑍ

(Copied Into Program)

Error Code Parameter

(Copied Into Program)

QUSEC -

QSYLOBJP - List Objects API

Chapter 9. Common API Programming Errors 9-43

Download from Www.Somanuals.com. All Manuals Search And Download.

Dᑍ

Cᑍ

(Copied Into Program)

CᑍAPIs Used: QUSCRTUS - Create User Space

Cᑍ

QSYLOBJP - List Objects That Adopt Owner Authority

QUSROBJD - Retrieve Object Description

QUSPTRUS - Retrieve Pointer to User Space

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Cᑍ

D/COPY QSYSINC/QRPGLESRC,QUSEC

Dᑍ

DSPC_NAME

DSPC_SIZE

DSPC_INIT

DLSTPTR

2ð

INZ('ADOPTS

INZ(X'ðð')

QTEMP

9B ð INZ(1)

ᑍ

DSPCPTR

DARR

DRCVVAR

DRCVVARSIZ

BASED(LSTPTR) DIM(32767)

9B ð INZ(%SIZE(RCVVAR))

Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Dᑍ

Dᑍ The following QUSGEN include is copied into this program so

Dᑍ that it can be declared as BASED on SPCPTR (shown at .21/

Dᑍ in the incorrect and correct programs on pages

Dᑍ 9-37 and 9-45, respectively)

Dᑍ

Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Dᑍ

Dᑍᑍᑍ START HEADER FILE SPECIFICATIONS ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Dᑍ

DᑍHeader File Name: H/QUSGEN

Dᑍ

DᑍDescriptive Name: Format structures for User Space for ILE/C

Dᑍ

Dᑍ5763-SS1 (C) Copyright IBM Corp. 1994, 1994

DᑍUS Government Users Restricted Rights -

DᑍUse, duplication or disclosure restricted

Dᑍby GSA ADP Schedule Contract with IBM Corp.

Dᑍ

DᑍDescription: Contains the Generic Record format headers

Dᑍ

for the user space.

DᑍHeader Files Included: none.

Dᑍ

DᑍMacros List: none.

Dᑍ

DᑍStructure List: Qus_Generic_Header_ð1ðð

Dᑍ

Qus_Generic_Header_ð3ðð

DᑍFunction Prototype List: none.

Dᑍ

DᑍChange Activity:

Dᑍ

DᑍCFD List:

Dᑍ

9-44 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

DᑍFLAG REASON

LEVEL DATE PGMR

CHANGE DESCRIPTION

Dᑍ---- ------------ ----- ------ --------- ----------------------

Dᑍ$Að= D2862ððð

DᑍEnd CFD List.

Dᑍ

DᑍAdditional notes about the Change Activity

DᑍEnd Change Activity.

3D1ð 94ð213 LUPA:

New Include

Dᑍᑍᑍ END HEADER FILE SPECIFICATIONS ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

DᑍType Definition for the User Space Generic Header.

Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

DQUSHð1ðð

Dᑍ

D QUSUA

Dᑍ

D QUSSGH

Dᑍ

D QUSSRL

Dᑍ

D QUSFN

Dᑍ

D QUSAU

Dᑍ

D QUSDTC

Dᑍ

D QUSIS

Dᑍ

D QUSSUS

Dᑍ

D QUSOIP

Dᑍ

D QUSSIP

Dᑍ

D QUSOHS

Dᑍ

D QUSSHS

Dᑍ

D QUSOLD

Dᑍ

D QUSSLD

Dᑍ

D QUSNBRLE

Dᑍ

BASED(SPCPTR)

.21/

Qus Generic Header ð1ðð

User Area

68B ð

Size Generic Header

Structure Release Level

Format Name

8ð

9ð

API Used

1ð3

Date Time Created

Information Status

Size User Space

Offset Input Parameter

Size Input Parameter

Offset Header Section

Size Header Section

Offset List Data

Size List Data

1ð4

1ð5

1ð9

113

117

121

125

129

133

137

141

145

147

15ð

151

1ð4

1ð8B ð

112B ð

116B ð

12ðB ð

124B ð

128B ð

132B ð

136B ð

14ðB ð

144B ð

146

Number List Entries

Size Each Entry

CCSID List Ent

D QUSSEE

Dᑍ

D QUSSIDLE

Dᑍ

D QUSCID

Dᑍ

D QUSLID

Dᑍ

D QUSSLI

Dᑍ

D QUSERVEDðð

Dᑍ

Country ID

149

Language ID

15ð

Partial List Indicator

192

Reserved

Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Dᑍ

Dᑍ The following QSYLOBJP include is copied into this program so

Chapter 9. Common API Programming Errors 9-45

Download from Www.Somanuals.com. All Manuals Search And Download.

Dᑍ that it can be declared as BASED on LSTPTR (shown at .22/

Dᑍ in the incorrect and correct coding on

Dᑍ pages 9-39 and 9-46,

Dᑍ respectively)

Dᑍ

Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Dᑍᑍᑍ START HEADER FILE SPECIFICATIONS ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Dᑍ

DᑍHeader File Name: H/QSYLOBJP

Dᑍ

DᑍDescriptive Name: List Objects That Adopt Owner Authority.

Dᑍ

DᑍDescription: Include header file for the QSYLOBJP API.

Dᑍ

DᑍHeader Files Included: H/QSYLOBJP

Dᑍ

H/QSY

DᑍMacros List: None.

Dᑍ

DᑍStructure List: OBJPð1ðð

Dᑍ

OBJPð2ðð

Qsy_OBJP_Header

DᑍFunction Prototype List: QSYLOBJP

Dᑍ

DᑍChange Activity:

Dᑍ

DᑍCFD List:

Dᑍ

DᑍFLAG REASON

LEVEL DATE PGMR

CHANGE DESCRIPTION

Dᑍ---- ------------ ----- ------ --------- ----------------------

Dᑍ$Að= D2862ððð

Dᑍ

3D1ð 931222 XZYð432: New Include

DᑍEnd CFD List.

Dᑍ

DᑍAdditional notes about the Change Activity

DᑍEnd Change Activity.

Dᑍᑍᑍ END HEADER FILE SPECIFICATIONS ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

DᑍPrototype for calling Security API QSYLOBJP

Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

D QSYLOBJP

'QSYLOBJP'

Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

DᑍHeader structure for QSYLOBJP

Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

DQSYOBJPH

Dᑍ

D QSYUNðð

Dᑍ

D QSYCVðð

Dᑍ

BASED(LSTPTR)

.22/

Qsy OBJP Header

1ð

User name

3ð

Continuation Value

Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

DᑍRecord structure for OBJPð1ðð format

Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

DQSYð1ððLð2

Dᑍ

D QSYNAMEð5

BASED(LSTPTR)

.22/

Qsy OBJPð1ðð List

1ð

9-46 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

D QSYBRARYð5

2ð

Dᑍ

Qualified object name

D QSYOBJT12

3ð

Dᑍ

Object type

D QSYOBJIU

Dᑍ

Cᑍ

Object in use

Cᑍ Start of mainline

Cᑍ

EXSR

INIT

PROCES

DONE

Cᑍ

Cᑍ Start of subroutines

Cᑍ

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Cᑍ

PROCES

BEGSR

Cᑍ This subroutine processes each entry returned by QSYLOBJP

Cᑍ

Cᑍ Do until the list is complete

Cᑍ

MOVE

QUSIS

LST_STATUS

Cᑍ

LST_STATUS

DOUEQ

'C'

Cᑍ If valid information was returned

Cᑍ

QUSIS

IFEQ

OREQ

'C'

'P'

Cᑍ

Cᑍ and list entries were found

Cᑍ

QUSNBRLE

IFGT

Cᑍ

Cᑍ set LSTPTR to the first byte of the user space

Cᑍ

EVAL

LSTPTR = SPCPTR

Cᑍ increment LSTPTR to the first list entry

Cᑍ

EVAL

LSTPTR = %ADDR(ARR(QUSOLD + 1))

Cᑍ and process all of the entries

Cᑍ

IFEQ

QUSNBRLE

'ᑍSQLPKG'

QSYOBJT12

Cᑍ

Cᑍ Process ᑍSQLPKG type

Cᑍ

.23/

ELSE

Cᑍ

QSYOBJT12

IFEQ

'ᑍPGM'

Cᑍ Process ᑍPGM type

Cᑍ

QSYNAMEð5

DSPLY

ELSE

Chapter 9. Common API Programming Errors 9-47

Download from Www.Somanuals.com. All Manuals Search And Download.

QSYOBJT12

IFEQ

'ᑍSRVPGM'

↓

Cᑍ

Cᑍ Process ᑍSRVPGM type

Cᑍ

ELSE

Cᑍ Unknown type, log an error and exit from program (maybe..)

Cᑍ

EXSR

END

DONE

Cᑍ

Cᑍ after each entry, increment LSTPTR to the next entry

Cᑍ

EVAL

END

LSTPTR = %ADDR(ARR(QUSSEE + 1))

END

Cᑍ

Cᑍ When all entries in this user space have been processed, check

Cᑍ if more entries exist than can fit in one user space

Cᑍ

QUSIS

IFEQ

'P'

Cᑍ by resetting LSTPTR to the start of the user space

Cᑍ

EVAL

LSTPTR = SPCPTR

Cᑍ and then incrementing LSTPTR to the input parameter header

Cᑍ

EVAL

LSTPTR = %ADDR(ARR(QUSOIP + 1))

Cᑍ

Cᑍ If the continuation handle in the input parameter header is

Cᑍ blank, then set the list status to complete.

Cᑍ

QSYCVðð

IFEQ

MOVE

ELSE

ᑍBLANKS

'C'

LST_STATUS

Cᑍ

Cᑍ Else, call QSYLOBJP reusing the user space to get more

Cᑍ list entries

Cᑍ

MOVE

EXSR

MOVE

END

QSYCVðð

GETLST

QUSIS

CONTIN_HDL

LST_STATUS

END

ELSE

Cᑍ

Cᑍ And if an unexpected status, log an error (not shown) and exit

Cᑍ

EXSR

END

DONE

END

ENDSR

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

GETLST

BEGSR

9-48 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Cᑍ

Cᑍ Call QSYLOBJP to generate a list

Cᑍ The continuation handle is set by the caller of this subroutine.

Cᑍ

CALL

PARM

QSYLOBJP

SPC_NAME

MBR_LIST

USR_PRF

OBJ_TYPE

CONTIN_HDL

QUSEC

'OBJPð1ðð'

'ᑍCURRENT'

'ᑍALL'

1ð

2ð

Cᑍ

Cᑍ Check for errors on QSYLOBJP

Cᑍ

QUSBAVL

IFGT

MOVEL

EXSR

END

'QSYLOBJP'

APIERR

APINAM

1ð

ENDSR

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

INIT

BEGSR

Cᑍ

Cᑍ One time initialization code for this program

Cᑍ

Cᑍ Set error code structure to not use exceptions

Cᑍ

EVAL

QUSBPRV = %SIZE(QUSEC)

Cᑍ

Cᑍ Check to see if the user space was previously created in

Cᑍ QTEMP. If it was, simply reuse it.

Cᑍ

CALL

PARM

'QUSROBJD'

RCVVAR

RCVVARSIZ

ROBJD_FMT

SPC_NAME

OBJ_TYPE

QUSEC

'OBJDð1ðð'

'ᑍUSRSPC'

1ð

Cᑍ

Cᑍ Check for errors on QUSROBJD

Cᑍ

QUSBAVL

IFGT

Cᑍ If CPF98ð1, then user space was not found

Cᑍ

QUSEI

IFEQ

'CPF98ð1'

Cᑍ So create a user space for the list generated by QSYLOBJP

Cᑍ

CALL

PARM

'QUSCRTUS'

SPC_NAME

'QSYLOBJP ' EXT_ATTR

SPC_SIZE

1ð

SPC_INIT

'ᑍALL'

ᑍBLANKS

'ᑍYES'

SPC_AUT

SPC_TEXT

SPC_REPLAC

QUSEC

1ð

5ð

1ð

Chapter 9. Common API Programming Errors 9-49

Download from Www.Somanuals.com. All Manuals Search And Download.

PARM

'ᑍUSER'

SPC_DOMAIN

APINAM

1ð

Cᑍ

Cᑍ Check for errors on QUSCRTUS

Cᑍ

QUSBAVL

IFGT

MOVEL

EXSR

END

'QUSCRTUS'

APIERR

Cᑍ

Cᑍ Else, an error occurred accessing the user space

Cᑍ

ELSE

MOVEL

EXSR

END

'QUSROBJD'

APIERR

APINAM

1ð

END

Cᑍ

Cᑍ Set QSYLOBJP (using GETLST) to start a new list

Cᑍ

MOVE

EXSR

ᑍBLANKS

GETLST

CONTIN_HDL

Cᑍ

Cᑍ Get a resolved pointer to the user space for performance

Cᑍ

CALL

PARM

'QUSPTRUS'

SPC_NAME

SPCPTR

QUSEC

Cᑍ

Cᑍ Check for errors on QUSPTRUS

Cᑍ

QUSBAVL

IFGT

MOVEL

EXSR

END

'QUSPTRUS'

APIERR

APINAM

1ð

ENDSR

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Cᑍ

APIERR

BEGSR

Cᑍ Log any error encountered, and exit the program

Cᑍ

APINAM

DSPLY

EXSR

QUSEI

DONE

ENDSR

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Cᑍ

DONE

BEGSR

Cᑍ Exit the program

Cᑍ

EVAL

RETURN

ENDSR

ᑍINLR = '1'

9-50 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Appendix A. Performing Tasks Using APIs—Examples

This appendix contains the following examples of using multiple APIs to perform

tasks:

Ÿ Packaging your own software products

Ÿ Retrieving a file description to a user space

Ÿ Using data queues versus user queues

Packaging Your Own Software Products

You can define, create, distribute, and maintain your own product using APIs. The

following demonstrates how you can use the APIs to package a product similar to

the way IBM packages products.

The example product being packaged in this example is called ABC Product. The

product is made up of one library, ABC, with no options off of this product. ABC

Product consists of the following objects:

Figure A-1. ABC Software Packaging

Number

Object Name

Object Type

Text Description

ABCPGMMRM1

ABCPGMMRM2

ABCPGMMRI1

ABCPGMMRI2

ABCPGM

QCLSRC

ABCDSPF

ABCPF

*PGM

MRM¹preprocessing program

MRM postprocessing program

MRI²preprocessing program

MRI postprocessing program

CPP³for ABC command

Source physical file

Display file

*PGM

*FILE(SRCPF)

*FILE(DSPF)

*FILE(PF)

*MSGF

Physical file

Message file

ABCMSG

Note:

ABC

ABCPNLGRP

ABC0050

ABC0029

ABC0050

*CMD

Command for ABC Product

Panels for ABC

Product definition

Product load for MRI

Product load for MRM

ABC Product

*PNLGRP

*PRDDFN

*PRDLOD

*LIB

ABC

1. Machine readable material

2. Machine readable information

3. Command processing program

To package a product, first you create all of the objects (numbers 1 through 11 and

number 15 in Figure A-1) that will comprise your product. (“CL Program for Cre-

ating Objects and Library for Packaging a Product” on page A-2 shows the code

that creates the objects.) After your objects are created, you do the steps listed in

“Program for Packaging a Product—OPM RPG Example” on page A-3.

 Copyright IBM Corp. 1997

A-1

Download from Www.Somanuals.com. All Manuals Search And Download.

The following figure is an overview of the steps required to create a product. An

explanation is given of the numbers in Figure A-2. The same numbers also appear

in the code.

Product

Definition

Product

Build

Product

Objects

Application

Product

Load

Packaged

Product

RV3W218-1

Figure A-2. Steps for Creating a Software Product

.1/ Create a product definition with information about the licensed program, such

as ID, version, and release.

.2/ Create a product load, which further defines each option of a licensed

program, such as the libraries, folders, and exit programs that comprise the

product.

.3/ Identify all objects associated with the product by changing the product ID,

release level, product option, and load ID in the object description by using

the Change Object Description API.

.4/ Package the product. Verify and store a list of all objects marked for this

product in the product load object.

.5/ Use the Save Licensed Program (SAVLICPGM) command to save the product

to tape.

CL Program for Creating Objects and Library for Packaging a

Product

The following CL program creates objects 1 through 11 and 15 in Figure A-1 on

page A-1.

PGM

/ᑍ Delete library and start from scratch ᑍ/

DLTLIB ABC

/ᑍ MRM Objects ᑍ/

CRTLIB ABC

CRTCLPGM ABC/ABCPGMMRM1 ABCDEV/QCLSRC +

TEXT('MRM Preprocessing Program')

CRTCLPGM ABC/ABCPGMMRM2 ABCDEV/QCLSRC +

TEXT('MRM Postprocessing Program')

CRTCLPGM ABC/ABCPGM

ABCDEV/QCLSRC +

TEXT('CPP for ABC command')

/ᑍ MRI Objects ᑍ/

CRTCLPGM ABC/ABCPGMMRI1 ABCDEV/QCLSRC +

TEXT('MRI Preprocessing Program')

CRTCLPGM ABC/ABCPGMMRI2 ABCDEV/QCLSRC +

TEXT('MRI Postprocessing Program')

CRTSRCPF ABC/QCLSRC TEXT('Source Physical File for ABC Product')

A-2 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

CRTDSPF ABC/ABCDSPF ABCDEV/QDDSSRC +

TEXT('Display File for ABC Product')

CRTPF ABC/ABCPF ABCDEV/QDDSSRC +

TEXT('Physical File for ABC Product')

CRTMSGF ABC/ABCMSG TEXT('Message File')

ADDMSGD ABCððð1 ABC/ABCMSG MSG('ABC Product')

CRTCMD ABC/ABC ABC/ABCPGM ABCDEV/QCMDSRC +

TEXT('Command for ABC Product')

CRTPNLGRP ABC/ABCPNLGRP ABCDEV/QPNLSRC +

TEXT('Panel for ABC Command')

/ᑍ The next program creates the product definitions, product loads, ᑍ/

/ᑍ and gives all the objects associated with the product the correctᑍ/

/ᑍ product information. It packages the product, which enables

/ᑍ you to use the SAVLICPGM, RSTLICPGM, and DLTLICPGM commands.

ᑍ/

CRTRPGPGM ABCDEV/SFTWPRDEX ABCDEV/QRPGSRC

/ᑍ .1/ .2/ .3/ .4/

ᑍ/

CALL ABCDEV/SFTWPRDEX

ENDPGM

Program for Packaging a Product—OPM RPG Example

The following program creates objects 12 through 14 in Figure A-1 on page A-1.

Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Fᑍ

FᑍProgram Name: SFTWPRDEX

Fᑍ

FᑍLanguage: OPM RPG

Fᑍ

FᑍDescriptive Name: Software Product Example

Fᑍ

FᑍDescription: This example contains the steps necessary to

Fᑍ

package your product like IBM products.

FᑍHeader Files Included: QUSEC - Error Code Parameter

Fᑍ

(Copied into Program)

QSZCRTPD - Create Product Definition API

QSZCRTPL - Create Product Load API

QSZPKGPO - Package Product Option API

Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

FQPRINT O F

132

PRINTER

Eᑍ COMPILE TIME ARRAY

OBJ ðð1 15 41

Iᑍ

Iᑍ Error Code Parameter Include for the APIs

Iᑍ

Iᑍ The following QUSEC include has been copied into this program

Iᑍ so that the variable length field can be defined as a fixed

Iᑍ length.

Iᑍᑍᑍ START HEADER FILE SPECIFICATIONS ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Iᑍ

IᑍHeader File Name: H/QUSEC

Iᑍ

IᑍDescriptive Name: Error Code Parameter.

Appendix A. Performing Tasks Using APIs—Examples A-3

Download from Www.Somanuals.com. All Manuals Search And Download.

Iᑍ

Iᑍ5763-SS1 (C) Copyright IBM Corp. 1994,1994

IᑍUS Government Users Restricted Rights -

IᑍUse, duplication or disclosure restricted

Iᑍby GSA ADP Schedule Contract with IBM Corp.

Iᑍ

IᑍLicensed Materials-Property of IBM

Iᑍ

IᑍDescription: Include header file for the error code parameter.

Iᑍ

IᑍHeader Files Included: None.

Iᑍ

IᑍMacros List: None.

Iᑍ

IᑍStructure List: Qus_EC_t

Iᑍ

IᑍFunction Prototype List: None.

Iᑍ

IᑍChange Activity:

Iᑍ

IᑍCFD List:

Iᑍ

IᑍFLAG REASON

LEVEL DATE PGMR

CHANGE DESCRIPTION

Iᑍ---- ------------ ----- ------ --------- ----------------------

Iᑍ$Að= D2862ððð

Iᑍ

3D1ð 9312ð1 DPOHLSON: New Include

IᑍEnd CFD List.

Iᑍ

IᑍAdditional notes about the Change Activity

IᑍEnd Change Activity.

Iᑍᑍᑍ END HEADER FILE SPECIFICATIONS ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Iᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

IᑍRecord structure for error code parameter

Iᑍᑍᑍᑍ

ᑍᑍᑍ

IᑍNOTE: The following type definition only defines the fixed

Iᑍ portion of the format. Varying length field exception

Iᑍ data will not be defined here.

Iᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

IQUSBN

Iᑍ

Qus EC

B 1 4ðQUSBNB

Bytes Provided

B 5 8ðQUSBNC

Bytes Available

9 15 QUSBND

Exception Id

16 16 QUSBNF

Iᑍ

Reserved

17 17 QUSBNG

Varying length

17 1ðð QUSBNG

Iᑍ

Iᑍ Create Product Definition API Include

Iᑍ

I/COPY QSYSINC/QRPGSRC,QSZCRTPD

A-4 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Iᑍ

Iᑍ Create Product Load API Include

Iᑍ

I/COPY QSYSINC/QRPGSRC,QSZCRTPL

Iᑍ

Iᑍ Package Product Option API Include

Iᑍ

I/COPY QSYSINC/QRPGSRC,QSZPKGPO

Iᑍ

I I

Iᑍ

B 1 4ðNUMPOP

B 5 8ðNUMLAN

' 9 28 PDFN

'ABCðð5ð ABC

'ABC Product'

'5ð72535ð1ð

'ᑍNODYNNAM '

29 78 TEXTD

79 92 PHONE

93 1ð2 ALWDYN

1ð3 112 PUBAUT

113 122 POSTM

123 132 PREM

133 142 POSTI

143 152 PREI

'ᑍUSE

'ABCPGMMRM2'

'ABCPGMMRM1'

'ABCPGMMRI2'

'ABCPGMMRI1'

Iᑍ Change Object Information Parameter

ICOBJI

I I

B 1 4ðNUMKEY

B 5 8ðKEY13

B 9 12ðLEN13

13 16 PID13

I I

B 17 2ððKEY12

B 21 24ðLEN12

25 28 LID12

B 29 32ðKEY5

B 33 36ðLEN5

37 49 LP5

Iᑍ

Iᑍ Object Data Structure - Breakdown of fields in Array OBJ

IOBJDS

1 1ð NAME

11 2ð TYP

21 24 PID

25 28 LID

29 41 LP

B 1 4ðRCVLEN

B 5 8ðNUMBK

B 9 12ðNUMBL

B 13 16ðNUMBM

I I

Cᑍ

Cᑍ Beginning of Mainline

Cᑍ

Cᑍ Create Product Definition Object - ABCðð5ð

Cᑍ

EXSR PRDDFN

.1/

Cᑍ Create Product Load Objects - ABCðð5ð (MRM) and ABCðð29 (MRI)

Cᑍ

EXSR PRDLOD

.2/

Appendix A. Performing Tasks Using APIs—Examples A-5

Download from Www.Somanuals.com. All Manuals Search And Download.

Cᑍ

Cᑍ Change Object Description for all objects associated with

Cᑍ the ABC Product.

Cᑍ

EXSR COBJD

.3/

Cᑍ

Cᑍ Package the ABC Product so that all the SAVLICPGM, RSTLIBPGM,

Cᑍ and DLTLICPGM commands work with the product.

Cᑍ

EXSR PKGPO

.4/

Cᑍ Complete; product is ready to ship.

Cᑍ

SETON

RETRN

Cᑍ

Cᑍ End of MAINLINE

Cᑍ

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Cᑍ

Cᑍ Subroutine: PRDDFN

Cᑍ

Cᑍ Descriptive Name: Create product definitions.

Cᑍ

Cᑍ Description: This subroutine creates the product definition

Cᑍ

ABCðð5ð for the ABC Product.

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Cᑍ

PRDDFN

BEGSR

Cᑍ Setup for Product Definition

Cᑍ Fill Product Definition Information Parameter

Z-ADD1ðð

QUSBNB

MOVEL'ðABCABC' QSZBCB

MOVEL'V3R1Mð' QSZBCC

MOVEL'ABCMSG' QSZBCD

MOVEL'ᑍCURRENT'QSZBCF

MOVEL'ᑍCURRENT'QSZBCG

MOVEL'9412ð1' QSZBCH

Product ID

Release Level

Message File

First Copyright

Current Copyright

Release Date

MOVEL'ᑍNO'

QSZBCJ

Allow multiple rel.

Registration ID Value

MOVEL'ᑍPHONE' QSZBCK

MOVELPHONE

QSZBCL

Cᑍ Fill Product Load Parameter

MOVEL'ðððð'

MOVEL'ABCððð1' QSZBDC

MOVELALWDYN

MOVEL'5ðð1'

MOVELᑍBLANKS QSZBDG

QSZBDB

Product Option Number

Message ID

Allow Dynamic Naming

Code Load ID

Reserved

QSZBDD

QSZBDF

Cᑍ Fill Language Load List Parameter

MOVEL'2924

MOVEL'ðððð'

MOVELᑍBLANKS QSZBFD

'QSZBFB

QSZBFC

Language Load ID

Product Option Number

Reserved

Cᑍ

Cᑍ Create the Product Definition for the ABC Product

Cᑍ

A-6 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

MOVEL'QSZCRTPD'API

CALL 'QSZCRTPD'

1ð

PARM

PDFN

Qual. Prod. Defn.

Prod. Defn. Info.

Prod. Option List

# Prod. Options

Lang. Load List

# Lang. Load List

Text Description

Public Authority

Error Code

QSZBC

QSZBD

NUMPOP

QSZBF

NUMLAN

TEXTD

PUBAUT

QUSBN

Cᑍ Check for errors returned in the error code parameter.

EXSR ERRCOD

ENDSR

Cᑍ

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Cᑍ

Cᑍ Subroutine: PRDLOD

Cᑍ

Cᑍ Descriptive Name: Create product loads.

Cᑍ

Cᑍ Description: This subroutine creates the product loads,

Cᑍ

ABCðð5ð and ABCðð29, for the ABC Product.

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Cᑍ

PRDLOD

BEGSR

Cᑍ Setup for Product Load for MRM Objects

Cᑍ Fill Product Load Information Parameter

Cᑍ

MOVEL'ðABCABC' QSZBHB

MOVEL'V3R1Mð' QSZBHC

Product ID

Release Level

MOVEL'ðððð'

QSZBHD

Product Option

Product Load Type

Load ID

Registration ID Type

Registration ID Value

Min. Target Release

Reserved

MOVEL'ᑍCODE' QSZBHF

MOVEL'ᑍCODEDFT'QSZBHG

MOVEL'ᑍPRDDFN' QSZBHH

MOVELᑍBLANKS QSZBHJ

MOVEL'ᑍCURRENT'QSZBCK

MOVELᑍBLANKS QSZBCL

Cᑍ Fill Principal Library Information Parameter

MOVEL'ABC'

MOVELPOSTM

QSZBJB

QSZBJC

QSZBJD

Prin. Dev. Lib. Name

Prin. Prim. Lib. Name

Post-Exit Prog. Name

Cᑍ

Cᑍ Fill Preoperation Exit Programs Parameter

MOVELPREM

MOVEL'ABC'

QSZBLB

QSZBLC

Pre-Exit Prog. Name

Dev. Lib. Name

Cᑍ

Cᑍ Fill Additional Library List Parameter

Cᑍ

None

Cᑍ Fill Folder List Parameter

Cᑍ

None

Cᑍ Create the product load for the ABC Product - MRM Objects

Appendix A. Performing Tasks Using APIs—Examples A-7

Download from Www.Somanuals.com. All Manuals Search And Download.

Cᑍ

MOVEL'QSZCRTPL'API

CALL 'QSZCRTPL'

PARM 'ABCðð5ð' PRDIDN 1ð

Prod. ID Name

PARM

QSZBH

Prod. Defn. Info.

Sec. Lang. Lib

Principal Lib Info

Add. Library List

# Add. Lib. List

Pre-Exit Programs

# Pre-Exit Programs

Folder List

PARM ᑍBLANKS SECLIB 1ð

PARM

PARM ð

PARM

PARM 1

PARM

PARM ð

PARM

PARM 'ᑍUSE'

PARM

QSZBJ

QSZBK

NUMBK

QSZBL

NUMBL

QSZBM

NUMBM

TEXTD

PUBAUT

QUSBN

# Folder List

Text Description

Public Authority

Error Code

Cᑍ Check for errors returned in the error code parameter.

Cᑍ

EXSR ERRCOD

Cᑍ Setup for Product Load for MRI Objects

Cᑍ Fill Product Load Information Parameter

MOVEL'ᑍLNG ' QSZBHF

MOVEL'2924 'QSZBHG

Product Load Type

Load ID

Cᑍ

Cᑍ Fill Principal Library Information Parameter

Cᑍ

MOVELPOSTI

QSZBJD

Post-Exit Prog. Name

Pre-Exit Prog. Name

Cᑍ Fill Preoperation Exit Programs Parameter

Cᑍ

MOVELPREI

QSZBLB

Cᑍ Fill Additional Library List Parameter

Cᑍ

None

Cᑍ Fill Folder List Parameter

Cᑍ

None

Cᑍ Create the product load for the ABC Product - MRI Objects

Cᑍ

MOVEL'QSZCRTPL'API

CALL 'QSZCRTPL'

PARM 'ABCðð29' PRDIDN 1ð

Prod. ID Name

PARM

QSZBH

Prod. Defn. Info.

Sec. Lang. Lib

Principal Lib Info

Add. Library List

# Add. Lib. List

Pre-Exit Programs

# Pre-Exit Programs

Folder List

PARM 'ABC2924 'SECLIB

PARM

PARM ð

PARM

PARM 1

PARM

PARM ð

PARM

PARM 'ᑍUSE'

PARM

QSZBJ

QSZBK

NUMBK

QSZBL

NUMBL

QSZBM

NUMBM

TEXTD

PUBAUT

QUSBN

# Folder List

Text Description

Public Authority

Error Code

Cᑍ Check for errors returned in the error code parameter.

EXSR ERRCOD

ENDSR

Cᑍ

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

A-8 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Cᑍ

Cᑍ Subroutine: COBJD

Cᑍ

Cᑍ Descriptive Name: Change object descriptions for the

Cᑍ ABC Product.

Cᑍ

Cᑍ Description: This subroutine changes the object

Cᑍ

descriptions for all objects that make up the

ABC Product. Currently, 15 objects exist. They

are listed at the end of this program.

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Cᑍ

COBJD

BEGSR

Cᑍ Need to associate all objects with the ABC Product

DO 15

3ð

MOVE OBJ,I

CAT 'ABC'

MOVELLP

OBJDS

NAME

QOBJNM 2ð

LP5

PID13

LID12

TYPE 1ð

MOVELPID

MOVELLID

MOVELTYP

MOVEL'QLICOBJD'API

CALL 'QLICOBJD'

PARM

RTNLIB 1ð

QOBJNM

TYPE

COBJI

QUSBN

Returned Lib. Name

Qual. Object Name

Object Type

Chg'd Object Info.

Error Code

Cᑍ Check for any errors returned in the error code parameter.

EXSR ERRCOD

ENDDO

ENDSR

Cᑍ

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Cᑍ

Cᑍ Subroutine: PKGPO

Cᑍ

Cᑍ Descriptive Name: Package software ABC Product.

Cᑍ

Cᑍ Description: This subroutine packages the ABC Product.

Cᑍ

It makes sure that all objects exist that are

associated with the product.

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Cᑍ

PKGPO

BEGSR

Cᑍ Setup for packing the ABC Product.

Cᑍ Fill Product Option Information Parameter

MOVEL'ðððð'

QSZBRB

Product Option

Product ID

Release Level

MOVEL'ðABCABC' QSZBRC

MOVEL'V3R1Mð' QSZBRD

Appendix A. Performing Tasks Using APIs—Examples A-9

Download from Www.Somanuals.com. All Manuals Search And Download.

MOVEL'ᑍALL

'QSZBRF

Load ID

Reserved

MOVELᑍBLANKS QSZBRG

Cᑍ

Cᑍ Package the ABC Product.

Cᑍ

MOVEL'QSZPKGPO'API

CALL 'QSZPKGPO'

PARM

QSZBR

Prod. Option Info.

Repackage

Allow Object Change

Error Code

PARM 'ᑍYES'

REPKG 4

PARM 'ᑍNO ' ALWCHG 5

PARM

QUSBN

Cᑍ Check for any errors returned in the error code parameter.

EXSR ERRCOD

ENDSR

Cᑍ

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Cᑍ

Cᑍ Subroutine: ERRCOD

Cᑍ

Cᑍ Descriptive Name: Process API errors.

Cᑍ

Cᑍ Description: This subroutine prints a line to a spooled

Cᑍ

file if any errors are returned in the error code

parameter.

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Cᑍ

ERRCOD

QUSBNC

BEGSR

IFNE ð

Cᑍ

Cᑍ Process errors returned from the API.

Cᑍ

EXCPTBADNWS

END

ENDSR

OQPRINT E 1ð6

BADNWS

'Failed in API '

'with error '

API

QUSBND

Oᑍ The information below is for array OBJ.

Oᑍ111 represents the object name.

Oᑍ2222222222 represents the object type.

Oᑍ3333 represents the product option ID.

Oᑍ4444 represents the product option load ID.

Oᑍ5555555555555 represents the licensed program.

Oᑍ1112222222222333344445555555555555

ᑍᑍ

ABCPGMMRM1ᑍPGM

ABCPGMMRM2ᑍPGM

ABCPGMMRI1ᑍPGM

ABCPGMMRI2ᑍPGM

ðððð5ðð1ðABCABCV3R1Mð

ðððð2924ðABCABCV3R1Mð

ðððð5ðð1ðABCABCV3R1Mð

ðððð2924ðABCABCV3R1Mð

ABCPGM

QCLSRC

ᑍPGM

ᑍFILE

ABCDSPF ᑍFILE

A-10 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

ABCPF

ABCMSG

ABC

ᑍFILE

ᑍMSGF

ᑍCMD

ðððð2924ðABCABCV3R1Mð

ABCPNLGRP ᑍPNLGRP ðððð2924ðABCABCV3R1Mð

ABCðð5ð ᑍPRDDFN ðððð5ðð1ðABCABCV3R1Mð

ABCðð5ð ᑍPRDLOD ðððð5ðð1ðABCABCV3R1Mð

ABCðð29 ᑍPRDLOD ðððð2924ðABCABCV3R1Mð

ABC

ᑍLIB

ðððð5ðð1ðABCABCV3R1Mð

Before you can build PTFs for the product, you need to save the product and install

the product by using the Save Licensed Program (SAVLICPGM) and Restore

Licensed Program (RSTLICPGM) commands.

Once the product is built, you can do the following:

Ÿ Build PTFs for the product by using the following APIs:

– Create Program Temporary Fix (QPZCRTFX)

– Retrieve Program Temporary Fix Information (QPZRTVFX)

– Program Temporary Fix Exit Program

Ÿ Use save, restore, or delete license program (SAVLICPGM, RSTLICPGM,

DLTLICPGM) commands on it.

Ÿ Retrieve information about the product by using the Retrieve Product Informa-

tion (QSZRTVPR) API.

Ÿ Check the product to verify the existence of libraries, folders, and objects that

are part of the specified product (Check Product Option (CHKPRDOPT)

command).

Note: For examples of the software product example program in additional lan-

guages, see “Program for Packaging a Product—Examples” on

page B-129.

Retrieving a File Description to a User Space—ILE C Example

The following programming example shows an application that uses a user space

as a receiver variable by retrieving a file description to a user space. This

approach is possible only if you use an HLL that is able to work with pointers. The

application accepts the following parameters:

Ÿ User space name and library

Ÿ File name and library

Ÿ Record format

The following shows the sequence of steps to retrieve a file description to a user

space:

1. The application creates a user space to store the data in, changes the user

space to be automatically extendable, and retrieves a pointer to the user space.

2. The application calls the Retrieve File Description API to retrieve the file defi-

nition template and uses the user space as the receiver variable.

This example uses an automatically extended user space as the receiver variable

on a retrieve API. A user space can return a varying amount of information

depending on the file description being retrieved. The user space is automatically

extended up to 16MB to accommodate the information being retrieved.

Appendix A. Performing Tasks Using APIs—Examples A-11

Download from Www.Somanuals.com. All Manuals Search And Download.

/ᑍ Program Name:

RTVFD

ᑍ/

/ᑍ

/ᑍ Program Language:

ILE C

/ᑍ

/ᑍ Description:

Retrieve a file definition template to a ᑍ/

user space.

/ᑍ

ᑍ/

/ᑍ Header Files Included: <stdlib.h>

/ᑍ

<signal.h>

<string.h>

<stdio.h>

<quscrtus.h>

<quscusat.h>

<qusptrus.h>

<qdbrtvfd.h>

<qusec.h>

/ᑍ

<qus.h>

<qliept.h>

/ᑍ

/ᑍ APIs Used:

QUSCRTUS - Create User Space

/ᑍ

QUSCUSAT - Change User Space Attributes ᑍ/

QUSPTRUS - Retrieve Pointer to User Space ᑍ/

QDBRTVFD - Retrieve File Description

ᑍ/

#include <stdlib.h>

#include <signal.h>

#include <string.h>

#include <stdio.h>

#include <quscrtus.h>

#include <quscusat.h>

#include <qusptrus.h>

#include <qdbrtvfd.h>

#include <qusec.h>

#include <qus.h>

#include <qliept.h>

/ᑍ Note that this must be the last ᑍ/

/ᑍ include specified.

ᑍ/

int error_flag = ð;

/ᑍ Set by error handler

ᑍ/

/ᑍ Function:

error_handler

ᑍ/

/ᑍ Description: Handle exceptions.

void error_handler(int errparm)

{

_INTRPT_Hndlr_Parms_T ExcDta = {ð};

_GetExcData(&ExcDta);

error_flag = 1;

signal(SIGALL,error_handler);

}

/ᑍ Start of main procedure

ᑍ/

A-12 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

main(int argc, char ᑍᑍargv)

{

typedef struct attrib_struct {

int attrib_count;

Qus_Vlen_Rec_3_t keyinfo;

char key_value;

} attrib_struct;

Qus_EC_t error_code;

attrib_struct attrib_info;

char user_space[21];

char descr[5ð];

char initial_value = ðxðð;

char return_lib[1ð];

char ret_file_lib[2ð];

char file_and_lib[21];

char record_fmt[11];

char ᑍspace_ptr;

/ᑍ Error code parameter

/ᑍ Attribute to change

/ᑍ User space and library

/ᑍ Text description

/ᑍ Initial value for user spaceᑍ/

/ᑍ Return library ᑍ/

/ᑍ Returned file and library ᑍ/

/ᑍ File and library

/ᑍ Record format name

/ᑍ Pointer to user space objectᑍ/

ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ Start of executable code. ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

if (argc != 4) {

printf("This program requires 3 parameters:\n");

printf(" 1) User space name and library\n");

printf(" 2) File name and library\n");

printf(" 3) Record format name\n");

printf("Please retry with those parameters.\n");

exit(1);

}

memcpy(user_space, ᑍ++argv, 2ð);

memcpy(file_and_lib, ᑍ++argv, 2ð);

memcpy(record_fmt, ᑍ++argv, 1ð);

memset(desc,' ',5ð);

memcpy(descr,"RTVFD User Space",16);

signal(SIGALL,error_handler);

error_code.Bytes_Provided=ð;

/ᑍ Enable the error handler

ᑍ/

/ᑍ Have APIs return exceptions ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ Create the user space. ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

QUSCRTUS(user_space,

/ᑍ User space

/ᑍ Extended attribute

/ᑍ Initial size

ᑍ/

1ð24,

&initial_value,

"ᑍCHANGE ",

descr,

/ᑍ Initial value

/ᑍ Public authority

/ᑍ Text description

/ᑍ Replace if it exists

/ᑍ Error code

"ᑍYES

&error_code,

"ᑍUSER

");

/ᑍ Domain = USER

if (error_flag) {

exit(1);

}

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

Appendix A. Performing Tasks Using APIs—Examples A-13

Download from Www.Somanuals.com. All Manuals Search And Download.

/ᑍ Initialize the attributes to change structure.

ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

attrib_info.attrib_count = 1;

attrib_info.keyinfo.Key = 3;

/ᑍ Number of attributes

/ᑍ Key of attribute to change ᑍ/

attrib_info.keyinfo.Length_Vlen_Record = 1;

/ᑍ Length of data

/ᑍ Autoextend space

ᑍ/

attrib_info.key_value='1';

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ Change the user space to be automatically extendable. ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

QUSCUSAT(return_lib,

user_space,

/ᑍ Return library

ᑍ/

/ᑍ User space name and library ᑍ/

&attrib_info,

&error_code);

/ᑍ Attributes to change

/ᑍ Error code

ᑍ/

if (error_flag) {

exit(1);

}

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ Retrieve a pointer to the user space object. ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

QUSPTRUS(user_space,&space_ptr);

if (error_flag) {

exit(1);

}

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ Retrieve the file description information to the user space. ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

QDBRTVFD(space_ptr,

167767ð4,

/ᑍ Receiver variable

/ᑍ Return up to 16MB minus 512 ᑍ/

/ᑍ bytes of data ᑍ/

/ᑍ Returned file and library ᑍ/

ᑍ/

ret_file_lib,

"FILDð1ðð",

file_and_lib,

record_fmt,

"ð",

"ᑍLCL

"ᑍINT

&error_code);

/ᑍ File definition template

/ᑍ File and library name

/ᑍ Record format name

/ᑍ No override processing

/ᑍ Local system

ᑍ/

/ᑍ Internal formats .1/

/ᑍ Error code

if (error_flag) {

exit(1);

}

The example program uses the value *INT (.1/). A description and examples of

the internal (*INT) and external (*EXT) formats are provided in the “Retrieve Data-

base File Description (QDBRTVFD) API” in the System API Reference book.

A-14 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Using Data Queues versus User Queues

Data queues and user queues both provide a means for one or more processes to

communicate asynchronously. The queues can be processed FIFO (first-in

first-out), LIFO (last-in first-out), or by key. If user queues and data queues supply

the same function, which one should you choose for your implementation? The

following is a comparison of the two and an insight into when you should use one

queue rather than the other.

First, your programming experience is an important consideration in selecting a

queue type. If you are skilled in C or MI programming, you may want to select the

user queue. C and MI are the only languages that can use MI instructions, which,

as discussed later, has a bearing on performance. If your expertise is in COBOL or

RPG, then you should choose the data queue. You cannot implement a user

queue in COBOL or RPG because neither of these languages can use MI

instructions.

Next, performance plays an important part in determining what type of queue to

use. As stated in Chapter 1, “Application Programming Interface—Overview” on

page 1-1, APIs generally give better performance than CL commands. Also, MI

instructions perform better than an external call to an API because APIs have over-

head associated with them. User queues use MI instructions to manipulate entries;

data queues use APIs. Therefore, the user queue has better performance than the

data queue.

Last, you need to consider how the queue entries are manipulated. For example,

you need a way to perform enqueue and dequeue operations on entries from a

queue. As stated earlier, user queues use MI instructions to manipulate entries.

Specifically, you use the ENQ MI instruction to enqueue a message, and the DEQ

MI instruction to dequeue a message. If you are running at security level 40 or

greater, you must ensure that the user queue is created in the user domain in order

to directly manipulate a user queue using MI instructions. Because data queue

entries are manipulated by APIs, the security level of the machine does not limit the

use of the API.

You cannot create a user queue object in a library that does not permit user-

domain objects, which is determined by the QALWUSRDMN system value. (See

“Domain Concepts” on page 2-26 for more information on QALWUSRDMN.) Data

queues are always created in the system domain, so there is no problem with the

data queue being created into a specific library.

The following is a summary to help you select the type of queue that is right for

your program:

Ÿ Use user queues when:

– You have a programming background in or prefer to program in C or MI.

– You need the additional performance of an API for creating and deleting

and MI instructions for manipulating entries.

– You do not need to create a user-domain queue into a library where the

QALWUSRDMN system value does not permit user-domain user objects

when at security level 40 or 50.

Ÿ Use data queues when:

– You have a programming background in or prefer to program in COBOL or

RPG.

Appendix A. Performing Tasks Using APIs—Examples A-15

Download from Www.Somanuals.com. All Manuals Search And Download.

– You do not need the additional performance of MI instructions for directly

manipulating entries.

– You need to create queues into a library that is not listed in the

QALWUSRDMN system value.

Data Queue—ILE C Example

The following program illustrates how to use APIs to create and manipulate a data

queue.

/ᑍ

ᑍ/

/ᑍProgram Name: DQUEUEX

/ᑍ

/ᑍProgram Language: ILE C

/ᑍ

/ᑍDescription: This program illustrates how to use APIs to create

/ᑍ

and manipulate a data queue.

/ᑍHeader Files Included: <stdio.h>

/ᑍ

<string.h>

<stdlib.h>

<decimal.h>

<qrcvdtaq.h>

<qsnddtaq.h>

/ᑍ

/ᑍAPIs Used:

QSNDDTAQ - Send data queue

QRCVDTAQ - Receive data queue

/ᑍ

Includes

ᑍ/

#include <stdio.h>

#include <string.h>

#include <stdlib.h>

#include <decimal.h>

#include <qsnddtaq.h>

#include <qrcvdtaq.h>

/ᑍ from QSYSINC/h

ᑍ/

/ᑍ

ᑍ/

Main

void main()

{

decimal(5,ð) DataLength = 1ð.ðd,

WaitTime = ð.ðd;

char QueueData[1ð];

/ᑍ Create library QUEUELIB.

ᑍ/

A-16 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

system("CRTLIB LIB(QUEUELIB)");

/ᑍ Create a data queue called EXAMPLEQ in library QUEUELIB. The ᑍ/

/ᑍ queue will have a maximum entry length set at 1ð, and will be ᑍ/

/ᑍ FIFO (first-in first-out).

ᑍ/

system("CRTDTAQ DTAQ(QUEUELIB/EXAMPLEQ) MAXLEN(1ð)");

/ᑍ Send information to the data queue.

ᑍ/

QSNDDTAQ("EXAMPLEQ ",

"QUEUELIB ",

/ᑍ Data queue name

ᑍ/

/ᑍ Queue library name

/ᑍ Length of queue entry

/ᑍ Data sent to queue

DataLength,

"EXAMPLE ");

/ᑍ Receive information from the data queue. ᑍ/

QRCVDTAQ("EXAMPLEQ ",

"QUEUELIB ",

&DataLength,

/ᑍ Data queue name

/ᑍ Queue library name

/ᑍ Length of queue entry

/ᑍ Data received from queue ᑍ/

/ᑍ Wait time ᑍ/

ᑍ/

&QueueData,

WaitTime);

printf("Queue entry information: %.1ðs\n", QueueData);

/ᑍ Delete the data queue. ᑍ/

system("DLTDTAQ DTAQ(QUEUELIB/EXAMPLEQ)");

/ᑍ Delete the library.

ᑍ/

system("DLTLIB LIB(QUEUELIB)");

}

Note: For examples of the data queue program in additional languages, see “Data

Queue—Examples” on page B-165.

User Queue—ILE C Example

The following program illustrates how to use APIs to create and manipulate a user

queue.

/ᑍ

ᑍ/

/ᑍProgram Name: UQUEUEX

/ᑍ

/ᑍProgram Language: ILE C

Appendix A. Performing Tasks Using APIs—Examples A-17

Download from Www.Somanuals.com. All Manuals Search And Download.

/ᑍ

ᑍ/

/ᑍDescription: This program illustrates how to use APIs to create ᑍ/

/ᑍ

and manipulate a user queue.

ᑍ/

/ᑍHeader Files Included: <stdio.h>

/ᑍ

<signal.h>

<string.h>

<stdlib.h>

<miptrnam.h>

<miqueue.h>

<pointer.h>

<quscrtuq.h>

<qusdltuq.h>

<qusec.h>

/ᑍ

/ᑍAPIs Used:

QUSCRTUQ - Create a user queue

QUSDLTUQ - Delete a user queue

/ᑍ

Includes

ᑍ/

#include <stdio.h>

#include <signal.h>

#include <string.h>

#include <stdlib.h>

#include <milib.h>

/ᑍ from QCLE/h

ᑍ/

#include <miptrnam.h>

#include <miqueue.h>

#include <pointer.h>

#include <quscrtuq.h>

#include <qusdltuq.h>

#include <qusec.h>

/ᑍ from QSYSINC/h

ᑍ/

/ᑍ

Structures

ᑍ/

typedef struct {

Qus_EC_t ec_fields;

char

exception_data[1ðð];

} error_code_struct;

/ᑍ

ᑍ/

Main

void main()

{

char text_desc[5ð];

error_code_struct error_code;

_SYSPTR queuelib_sysptr,

user_queue_obj_sysptr;

A-18 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

_RSLV_Template_T rslvsp_template;

_ENQ_Msg_Prefix_T enq_msg_prefix;

_DEQ_Msg_Prefix_T deq_msg_prefix;

char enq_msg[5ð],

deq_msg[5ð];

int success=ð;

/ᑍ Create a library to create the user queue into.

ᑍ/

system("CRTLIB LIB(QUEUELIB)");

/ᑍ Initialize the error code parameter.

ᑍ/

error_code.ec_fields.Bytes_Provided=sizeof(error_code_struct);

/ᑍ Call the QUSCRTUQ API to create a user queue.

ᑍ/

/ᑍ

/ᑍ This will create a user queue called EXAMPLEQ in library

/ᑍ QUEUELIB, with the following attributes:

/ᑍ

1. Extended attribute of "VALID

been any valid ᑍNAME.

2. A queue type of "F", or First-in, first-out.

3. A key length of ð. If the queue is not keyed, this

value must be ð.

4. A maximum message size of 1ð bytes. This number can

be as large as 64K bytes.

5. The initial number of messages set to 1ð.

6. Additional number of messages set to 1ð.

7. Public authority of ᑍUSE.

8. A valid text description.

9. Replace option of ᑍYES. This means that if a user queue ᑍ/

", which could have

already exists by the name specified, in the library

specified, that it will be replaced by this

request.

ᑍ/

1ð. Domain value of ᑍUSER.

11. Pointer value of ᑍNO. Messages in the queue cannot

contain pointer data.

memcpy(text_desc, "THIS IS TEXT FOR THE EXAMPLE USER QUEUE

5ð);

QUSCRTUQ("EXAMPLEQ QUEUELIB ", /ᑍ Qualified user queue name

ᑍ/

"VALID

"F",

/ᑍ Extended attribute

/ᑍ Queue type

ð,

/ᑍ Key length

1ð,

/ᑍ Maximum message size

/ᑍ Initial number of messages

1ð,

/ᑍ Additional number of messages ᑍ/

"ᑍALL

text_desc,

"ᑍYES

/ᑍ Public authority

/ᑍ Text Description

/ᑍ Replace existing user queue ᑍ/

/ᑍ Error code ᑍ/

ᑍ/

&error_code,

Appendix A. Performing Tasks Using APIs—Examples A-19

Download from Www.Somanuals.com. All Manuals Search And Download.

"ᑍUSER

"ᑍNO

");

/ᑍ Domain of user queue

/ᑍ Allow pointer data

ᑍ/

/ᑍ If an exception occurred, the API would have returned the

/ᑍ exception in the error code parameter. The bytes available

ᑍ/

/ᑍ field will be set to zero if no exception occurred and greater ᑍ/

/ᑍ than zero if an exception did occur.

ᑍ/

if (error_code.ec_fields.Bytes_Available > ð)

{

printf("ATTEMPT TO CREATE A USER QUEUE FAILED WITH EXCEPTION:%.7s",

error_code.ec_fields.Exception_Id);

exit(1);

}

/ᑍ Send information to the queue.

ᑍ/

/ᑍ

/ᑍ We will need to use MI instructions to accomplish this.

/ᑍ There are three steps that must be done:

/ᑍ

/ᑍ 1. Resolve a system pointer to the library containing the user ᑍ/

/ᑍ

/ᑍ 2. Using the system pointer to the library, resolve a system

/ᑍ pointer to user queue object in the library.

/ᑍ 3. Enqueue the entry using the system pointer for the user

queue object.

ᑍ/

/ᑍ

queue.

/ᑍ First we must resolve to library QUEUELIB.

ᑍ/

memset(rslvsp_template.Obj.Name,' ',3ð);

memcpy(rslvsp_template.Obj.Name,"QUEUELIB",8);

rslvsp_template.Obj.Type_Subtype = _Library; /ᑍ found in milib.h ᑍ/

rslvsp_template.Auth = _AUTH_NONE; /ᑍ found in milib.h

ᑍ/

_RSLVSP6(&queuelib_sysptr,

&rslvsp_template,

/ᑍ system pointer to be set

/ᑍ resolve template

ᑍ/

&rslvsp_template.Auth); /ᑍ authority to set in sysptr ᑍ/

/ᑍ We can now resolve to the user queue object. We will pass the ᑍ/

/ᑍ system pointer to library QUEUELIB to RSLVSP so the resolve

/ᑍ will only search library QUEUELIB for the user queue object.

/ᑍ This is necessary so that we ensure that we are using the

/ᑍ correct object.

ᑍ/

memset(rslvsp_template.Obj.Name,' ',3ð);

memcpy(rslvsp_template.Obj.Name, "EXAMPLEQ", 8);

rslvsp_template.Obj.Type_Subtype = _Usrq; /ᑍ found in milib.h

rslvsp_template.Auth = _AUTH_ALL; /ᑍ found in milib.h

ᑍ/

_RSLVSP8(&user_queue_obj_sysptr, /ᑍ system pointer to be set

ᑍ/

&rslvsp_template,

/ᑍ resolve template

A-20 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

&queuelib_sysptr,

/ᑍ sysptr to library

ᑍ/

&rslvsp_template.Auth); /ᑍ authority to set in sysptr ᑍ/

/ᑍ Enqueue the entry.

ᑍ/

enq_msg_prefix.Msg_Len = 1ð;

enq_msg_prefix.Msg[ð] = '\ð';

memcpy(enq_msg, "EXAMPLE ", 1ð);

/ᑍ Only used for keyed queuesᑍ/

_ENQ(&user_queue_obj_sysptr,

&enq_msg_prefix,

/ᑍ system pointer to user queue ᑍ/

/ᑍ message prefix

/ᑍ message text

ᑍ/

(_SPCPTR)enq_msg);

/ᑍ Dequeue the entry. ᑍ/

success = _DEQI(&deq_msg_prefix, /ᑍ message prefix

(_SPCPTR)deq_msg, /ᑍ message text

ᑍ/

&user_queue_obj_sysptr); /ᑍ sys ptr to user queue ᑍ/

if(success)

{

printf("Queue entry information: %.1ðs\n", deq_msg);

}

else

{

printf("Entry not dequeued\n");

}

/ᑍ Delete the user queue.

ᑍ/

QUSDLTUQ("EXAMPLEQ QUEUELIB ", /ᑍ Qualified user queue name

&error_code); /ᑍ Error code

ᑍ/

/ᑍ If an exception occurred, the API would have returned the

/ᑍ exception in the error code parameter. The bytes available

ᑍ/

/ᑍ field will be set to zero if no exception occurred and greater ᑍ/

/ᑍ than zero if an exception did occur.

ᑍ/

if (error_code.ec_fields.Bytes_Available > ð)

{

printf("ATTEMPT TO DELETE A USER QUEUE FAILED WITH EXCEPTION:%.7s",

error_code.ec_fields.Exception_Id);

exit(1);

}

/ᑍ Delete the library created for this example.

ᑍ/

system("DLTLIB LIB(QUEUELIB)");

}

Appendix A. Performing Tasks Using APIs—Examples A-21

Download from Www.Somanuals.com. All Manuals Search And Download.

A-22 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Appendix B. Original Examples in Additional Languages

This appendix contains examples from the following areas of this book. The program examples in this

appendix are rewritten from the original examples into other programming languages.

Ÿ Chapter 3, “Common Information across APIs—Basic (OPM) Example”

Ÿ Chapter 4, “Common Information across APIs—Advanced (ILE) Example”

Ÿ Chapter 5, “List APIs”

Ÿ Chapter 6, “Original Program Model (OPM) and Integrated Language Environment (ILE) Differences”

Ÿ Appendix A, “Performing Tasks Using APIs—Examples”

This appendix also contains examples written in ILE C, ILE COBOL, and ILE RPG for using the integrated

file system.

The following tables describe the example tasks and refer you to the corresponding programming lan-

guage topic. In these tables, Yes means the task can be accomplished in the language identified but an

example is not provided. No means the task cannot be accomplished in the language identified.

Figure B-1. Original Program Model (OPM) API Examples from Chapter 3

Programming Language and Location of Example

Task

ILE C

OPM COBOL

ILE COBOL

OPM RPG

ILE RPG

Retrieving the HOLD Parameter (Exception

Messages)

B-2

B-4

3-6

B-6

Handling Error Conditions

3-8

B-8

Retrieving the HOLD Parameter (Error Code

Structure)

B-10

B-12

3-11

B-14

Accessing the HOLD Attribute

B-16

B-22

B-33

B-18

B-25

B-38

B-18

B-25

B-38

3-17

3-19

3-24

B-21

B-29

B-42

Accessing a Field Value (Initial Library List)

Using Keys with List Spooled Files API

Figure B-2. Integrated Language Environment (ILE) API Examples from Chapter 4

Programming Language and Location of Example

Task

ILE C

4-9

OPM COBOL

B-47

ILE COBOL

B-50

OPM RPG

B-54

ILE RPG

B-58

Retrieve Exit Point and Exit Program Informa-

tion

4-13

B-61

B-66

B-71

B-75

Remove Exit Program and Deregister Exit

Point

4-19

B-85

B-87

B-90

B-92

Figure B-3. List API Examples from Chapter 5

Programming Language and Location of Example

Task

ILE C

B-94

OPM COBOL

ILE COBOL

OPM RPG

ILE RPG

Listing Objects

B-101

5-4

B-106

Figure B-4 (Page 1 of 2). Pointer API Examples from Chapter 6

Programming Language and Location of Example

Task

ILE C

OPM COBOL

ILE COBOL

OPM RPG

ILE RPG

Logging Software Error (OPM API without

Pointers)

6-2

B-112

N/A

B-116

B-119

 Copyright IBM Corp. 1997

B-1

Download from Www.Somanuals.com. All Manuals Search And Download.

Figure B-4 (Page 2 of 2). Pointer API Examples from Chapter 6

Programming Language and Location of Example

Task

ILE C

OPM COBOL

ILE COBOL

OPM RPG

ILE RPG

Reporting Software Error (ILE API with

Pointers)

6-7

N/A

B-122

N/A

B-126

Figure B-5. Performing Tasks Using API Examples from Appendix A

Programming Language and Location of Example

Task

ILE C

B-129

A-11

OPM COBOL

B-136

ILE COBOL

B-136

OPM RPG

A-3

ILE RPG

B-144

B-155

B-172

Program for Packaging a Product

Retrieving a File Description to a User Space

Working with Data Queues

Working with User Queues

B-152

A-16

B-165

B-169

A-17

Figure B-6. UNIX-Type API Examples

Programming Language and Location of Example

Task

ILE C

OPM COBOL

ILE COBOL

OPM RPG

ILE RPG

Using the Integrated File System

B-175

B-178

B-183

Original Program Model (OPM) APIs—Examples

This topic includes the examples in Chapter 3, “Common Information across

APIs—Basic (OPM) Example.”

Retrieving the Hold Parameter (Exception Message)—ILE C Example

Refer to “Retrieving the Hold Parameter (Exception Message)—OPM RPG

Example” on page 3-6 for the original example.

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ

ᑍ/

/ᑍProgram Name:

/ᑍ

JOBDAPI

/ᑍProgramming Language: ILE C

/ᑍ

/ᑍDescription:

This example expects errors sent as

escape messages.

/ᑍ

/ᑍHeader Files Included: SIGNAL - C Error Signalling Routines

/ᑍ

STDIO - Standard Input/Output

STRING - String Functions

QUSEC - Error Code Parameter

QWDRJOBD - Retrieve Job Description API

QLIEPT - Entry Point Table

#include <signal.h>

#include <stdio.h>

#include <string.h>

B-2 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

#include <qusec.h>

/ᑍ Error Code Parameter Include for the APIs ᑍ/

#include <qwdrjobd.h> .2/

/ᑍ Retrieve Job Description API Include

ᑍ/

#include <qliept.h>

char received[8];

/ᑍ Used to receive error msgs signaled

/ᑍ from QWDRJOBD API.

ᑍ/

/ᑍ Function: error_handler ᑍ/

/ᑍ Description: This function handles exceptions signalled from the ᑍ/

/ᑍ

QWDRJOBD API. The message identifier received is

assigned to the variable 'received'.

ᑍ/

void error_handler(int dummy)

{

_INTRPT_Hndlr_Parms_T ExcDta = {ð};

_GetExcData(&ExcDta);

memcpy(received,ExcDta.Msg_Id,7);

signal(SIGALL,error_handler);

}

/ᑍ Error Code Structure

/ᑍ

ᑍ/

/ᑍ This shows how the user can define the variable length portion of ᑍ/

/ᑍ error code for the exception data.

/ᑍ

ᑍ/

typedef struct {

Qus_EC_t ec_fields;

char

Exception_Data[1ðð];

} error_code_t;

main(int argc, char ᑍargv[] .8/

{

error_code_t error_code;

char

qual_job_desc[2ð];

ᑍqual_job_ptr = qual_job_desc;

rec_var[39ð];

hold_value[1ð];

command_string[53];

/ᑍ Enable error handler. ᑍ/

signal(SIGALL,error_handler);

memset(hold_value, ' ', 1ð);

memset(received, ' ', 7);

/ᑍ Make sure we received the correct number of parameters. The argc ᑍ/

/ᑍ parameter will contain the number of parameters that was passed ᑍ/

/ᑍ to this program. This number also includes the program itself,

/ᑍ so we need to evaluate argc-1.

ᑍ/

Appendix B. Original Examples in Additional Languages B-3

Download from Www.Somanuals.com. All Manuals Search And Download.

if (((argc - 1) < 2) || ((argc - 1 > 2)))

/ᑍ We did not receive all of the required parameters so exit the

/ᑍ program.

ᑍ/

{

exit(1);

}

/ᑍ Move the two parameters passed into qual_job_desc. .9/

ᑍ/

memcpy(qual_job_ptr, argv[1], 1ð);

qual_job_ptr += 1ð;

memcpy(qual_job_ptr, argv[2], 1ð); .6/

/ᑍ Set the error code parameter to ð.

ᑍ/

error_code.ec_fields.Bytes_Provided = ð;

/ᑍ Call the QWDRJOBD API.

ᑍ/

QWDRJOBD(rec_var,

/ᑍ Receiver Variable

/ᑍ Receiver Length

ᑍ/

39ð, .3/

"JOBDð1ðð", .5/ /ᑍ Format Name

qual_job_desc,

&error_code);

/ᑍ Qualified Job Description

/ᑍ Error Code

if(memcmp(received, "

", 7) == ð)

memcpy(hold_value, ((Qwd_JOBDð1ðð_t ᑍ)rec_var)->Hold_Job_Queue, 1ð);

/ᑍ Let's tell everyone what the hold value was for this job.

ᑍ/

sprintf(command_string,

"SNDMSG MSG('HOLD value is %.7s') TOUSR(QPGMR)",

hold_value);

system(command_string);

} /ᑍ main ᑍ/

Retrieving the Hold Parameter (Exception Message)—ILE COBOL

Example

Refer to “Retrieving the Hold Parameter (Exception Message)—OPM RPG

Example” on page 3-6 for the original example. The following program also works

for OPM COBOL.

IDENTIFICATION DIVISION.

ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

ᑍ

ᑍProgram Name:

ᑍ

JOBDAPI

B-4 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

ᑍProgramming Language: COBOL

ᑍ

ᑍDescription:

This example expects errors sent as

escape messages.

ᑍ

ᑍHeader Files Included: QUSEC - Error Code Parameter

ᑍ

QWDRJOBD - Retrieve Job Description API

ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

ᑍ

PROGRAM-ID. JOBDAPI.

ᑍ

ENVIRONMENT DIVISION.

CONFIGURATION SECTION.

SOURCE-COMPUTER. IBM-AS4ðð.

OBJECT-COMPUTER. IBM-AS4ðð.

ᑍ

DATA DIVISION.

WORKING-STORAGE SECTION.

COPY QUSEC OF QSYSINC-QLBLSRC.

ᑍ

ᑍ Retrieve Job Description API Include

ᑍ

COPY QWDRJOBD OF QSYSINC-QLBLSRC. .2/

ᑍ

ᑍ Command String Data Structure

ᑍ

ð1 COMMAND-STRING.

ð5 TEXT1 PIC X(26) VALUE 'SNDMSG MSG(''HOLD value is'.

ð5 HOLD PIC X(1ð).

ð5 TEXT2 PIC X(15) VALUE ''') TOUSR(QPGMR)'.

ᑍ

ð1 COMMAND-LENGTH PIC S9(1ð)V99999 COMP-3.

ð1 RECEIVER-LENGTH PIC S9(9) COMP-4. .4/

ð1 FORMAT-NAME PIC X(8) VALUE 'JOBDð1ðð'. .5/

ð1 QCMDEXC PIC X(1ð) VALUE 'QCMDEXC'.

ᑍ

ᑍ Job Description and Library Name Structure

ᑍ

ð1 JOBD-AND-LIB-NAME.

ð5 JOB-DESC PIC X(1ð).

ð5 JOB-DESC-LIB PIC X(1ð).

ᑍ

LINKAGE SECTION.

ᑍ

ᑍ Two Parameters are being passed into this program.

ᑍ

ð1 JOBD PIC X(1ð).

ð1 JOBDL PIC X(1ð).

ᑍ

PROCEDURE DIVISION USING JOBD, JOBDL. .8/

MAIN-LINE.

ᑍ

ᑍ Beginning of Mainline

ᑍ

ᑍ Move the two parameters passed into JOB-DESC and JOB-DESC-LIB. .9/

ᑍ

Appendix B. Original Examples in Additional Languages B-5

Download from Www.Somanuals.com. All Manuals Search And Download.

MOVE JOBD TO JOB-DESC.

MOVE JOBDL TO JOB-DESC-LIB.

ᑍ

ᑍ Error Code Parameter is set to ð.

ᑍ

MOVE ð TO BYTES-PROVIDED. .6/

ᑍ

ᑍ Receiver Length Set to 39ð.

ᑍ

MOVE 39ð TO RECEIVER-LENGTH. .3/

ᑍ

ᑍ Call the QWDRJOBD API.

ᑍ

CALL QWDRJOBD USING QWD-JOBDð1ðð, RECEIVER-LENGTH,

FORMAT-NAME, JOBD-AND-LIB-NAME, QUS-EC.

ᑍ

ᑍ Move HOLD-JOB-QUEUE to HOLD so that we can display the value using

ᑍ the command string.

ᑍ

MOVE HOLD-JOB-QUEUE TO HOLD.

ᑍ

ᑍ Let's tell everyone what the hold value was for this job.

ᑍ

MOVE 51 TO COMMAND-LENGTH.

CALL QCMDEXC USING COMMAND-STRING, COMMAND-LENGTH.

ᑍ

STOP RUN.

Retrieving the Hold Parameter (Exception Message)—ILE RPG

Example

Refer to “Retrieving the Hold Parameter (Exception Message)—OPM RPG

Example” on page 3-6 for the original example.

Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Dᑍ

Dᑍ Program Name: JOBDAPI

Dᑍ

Dᑍ Programming Language: ILE RPG

Dᑍ

Dᑍ Description: This program retrieves the HOLD value from

Dᑍ

a job description. It expects errors to be

sent as escape messages.

Dᑍ Header Files Included: QUSEC - Error Code Parameter

Dᑍ

QWDRJOBD - Retrieve Job Description API

Dᑍ

Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Dᑍ

Dᑍ Error Code parameter include

Dᑍ

D/COPY QSYSINC/QRPGLESRC,QUSEC

Dᑍ

Dᑍ Retrieve Job Description API Include

Dᑍ

D/COPY QSYSINC/QRPGLESRC,QWDRJOBD

.2/

B-6 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Dᑍ

Dᑍ Command string data structure

Dᑍ

DCMD_STRING

1ð

INZ('SNDMSG MSG(''HOLD value is ')

INZ(''') TOUSR(QPGMR)')

D HOLD

Dᑍ

Dᑍ Miscellaneous data structure

Dᑍ

.4/

.2/ .3/

DRCVLEN

DFORMAT

DLENSTR

Cᑍ

9B ð INZ(%SIZE(QWDDð1ðð))

INZ('JOBDð1ðð') .5/

15 5 INZ(%SIZE(CMD_STRING))

Cᑍ Beginning of mainline

Cᑍ

Cᑍ Two parameters are being passed into this program

Cᑍ

ᑍENTRY

PLIST .8/

PARM

JOBD

JOBD_LIB

1ð

Cᑍ

Cᑍ Move the two parameters passed into LFNAM

Cᑍ

JOBD

CAT

JOBD_LIB

LFNAM

2ð .9/

Cᑍ

Cᑍ Error Code Bytes Provided is set to ð

Cᑍ

Z-ADD

QUSBPRV

.6/

Cᑍ

Cᑍ Call the API.

Cᑍ

CALL

PARM

QWDRJOBD

QWDDð1ðð

RCVLEN

FORMAT

LFNAM

QUSEC

Cᑍ

MOVEL

QWDHJQ

HOLD

Cᑍ Let's tell everyone what the hold value was for this job

Cᑍ

CALL

PARM

'QCMDEXC'

CMD_STRING

LENSTR

Cᑍ

EVAL

RETURN

ᑍINLR = '1'

Cᑍ End of MAINLINE

Cᑍ

Appendix B. Original Examples in Additional Languages B-7

Download from Www.Somanuals.com. All Manuals Search And Download.

Handling Error Conditions—ILE RPG Example

Refer to “Handling Error Conditions—OPM RPG Example” on page 3-8 for the ori-

ginal example. This example can be written only in OPM RPG and ILE RPG.

Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Dᑍ

Dᑍ Program Name: JOBDAPI

Dᑍ

Dᑍ Programming Language: ILE RPG

Dᑍ

Dᑍ Description: This program retrieves the HOLD value from

Dᑍ

a job description. It expects errors to be

sent as escape messages.

Dᑍ Header Files Included: QUSEC - Error Code Parameter

Dᑍ

QWDRJOBD - Retrieve Job Description API

Dᑍ

Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Dᑍ

Dᑍ Error Code parameter include

Dᑍ

D/COPY QSYSINC/QRPGLESRC,QUSEC

Dᑍ

Dᑍ Retrieve Job Description API Include

Dᑍ

D/COPY QSYSINC/QRPGLESRC,QWDRJOBD

Dᑍ

Dᑍ Program status DS

Dᑍ

DPGMSTS

D MSG_ID

Dᑍ

SDS .12/

4ð

Dᑍ Command string data structure

Dᑍ

DCMD_STRING

1ð

INZ('SNDMSG MSG(''HOLD value is ')

INZ(''') TOUSR(QPGMR)')

D HOLD

Dᑍ

Dᑍ Miscellaneous data structure

Dᑍ

DRCVLEN

DFORMAT

DLENSTR

DNO_JOBD

9B ð INZ(%SIZE(QWDDð1ðð))

INZ('JOBDð1ðð')

15 5 INZ(%SIZE(CMD_STRING))

INZ('SNDMSG MSG(''No such ᑍJOBD -

exists'') TOUSR(QPGMR)')

15 5 INZ(%SIZE(NO_JOBD))

DNO_JOBD_SZ

Cᑍ

Cᑍ Beginning of mainline

Cᑍ

Cᑍ Two parameters are being passed into this program

Cᑍ

ᑍENTRY

PLIST

PARM

JOBD

JOBD_LIB

1ð

Cᑍ

B-8 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Cᑍ Move the two parameters passed into LFNAM

Cᑍ

JOBD

CAT

JOBD_LIB

LFNAM

2ð

Cᑍ

Cᑍ Error Code Bytes Provided is set to ð

Cᑍ

Z-ADD

QUSBPRV

.11/

Cᑍ

Cᑍ Call the API.

Cᑍ

CALL

PARM

QWDRJOBD

ð1 .1ð/

QWDDð1ðð

RCVLEN

FORMAT

LFNAM

QUSEC

Cᑍ

Cᑍ Test for an error on the API call

Cᑍ

ᑍINð1 = ᑍON

Cᑍ If there was an error, exit to ERROR subroutine

Cᑍ

EXSR

ERROR

Cᑍ Else, process the HOLD value

Cᑍ

ELSE

MOVEL

QWDHJQ

HOLD

Cᑍ

Cᑍ Let's tell everyone what the hold value was for this job

Cᑍ

CALL

PARM

END

'QCMDEXC'

CMD_STRING

LENSTR

Cᑍ

EVAL

RETURN

ᑍINLR = '1'

Cᑍ End of MAINLINE

Cᑍ

Cᑍ Subroutine to handle errors received on the CALL

Cᑍ

ERROR

BEGSR

MSG_ID = 'CPF98ð1'

Cᑍ

Cᑍ Process errors returned from the API

Cᑍ

CALL

PARM

END

'QCMDEXC'

NO_JOBD

NO_JOBD_SZ

ENDSR

Appendix B. Original Examples in Additional Languages B-9

Download from Www.Somanuals.com. All Manuals Search And Download.

Retrieving the Hold Parameter (Error Code Structure)—ILE C Example

Refer to “Retrieving the Hold Parameter (Error Code Structure)—OPM RPG

Example” on page 3-11 for the original example.

/ᑍ

ᑍ/

/ᑍProgram Name:

/ᑍ

JOBDAPI

ᑍ/

/ᑍProgramming Language: ILE C

/ᑍ

/ᑍDescription:

ᑍ/

This example shows how to make use of an

ᑍ/

/ᑍ

error returned in the error code structure. ᑍ/

ᑍ/

/ᑍHeader Files Included: STDIO - Standard Input/Output

ᑍ/

/ᑍ

STRING - String Functions

QUSEC - Error Code Parameter

QWDRJOBD - Retrieve Job Description API

QLIEPT - Entry Point Table

#include <stdio.h>

#include <string.h>

#include <qusec.h> .14/ /ᑍ Error Code Parameter Include for the API ᑍ/

#include <qwdrjobd.h>

#include <qliept.h>

/ᑍ Retrieve Job Description API Include

ᑍ/

/ᑍ Error Code Structure

/ᑍ

ᑍ/

/ᑍ This shows how the user can define the variable length portion of ᑍ/

/ᑍ error code for the exception data.

/ᑍ

ᑍ/

typedef struct {

Qus_EC_t ec_fields;

char

Exception_Data[1ðð];

} error_code_t;

main(int argc, char ᑍargv[])

{

error_code_t error_code;

char

qual_job_desc[2ð];

ᑍqual_job_ptr = qual_job_desc;

rec_var[39ð];

hold_value[1ð];

message_id[7];

command_string[53];

message_string[67];

memset(hold_value, ' ', 1ð);

/ᑍ Make sure we received the correct number of parameters. The argc ᑍ/

/ᑍ parameter will contain the number of parameters that was passed ᑍ/

/ᑍ to this program. This number also includes the program itself,

ᑍ/

B-10 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

/ᑍ so we need to evaluate argc-1.

ᑍ/

if (((argc - 1) < 2) || ((argc - 1 > 2)))

/ᑍ We did not receive all of the required parameters so exit the

/ᑍ program.

ᑍ/

{

exit(1);

}

/ᑍ Move the two parameter passed in into qual_job_desc.

ᑍ/

memcpy(qual_job_ptr, argv[1], 1ð);

qual_job_ptr += 1ð;

memcpy(qual_job_ptr, argv[2], 1ð);

/ᑍ Set the error code parameter to 16.

ᑍ/

error_code.ec_fields.Bytes_Provided = 16; .15/

/ᑍ Call the QWDRJOBD API.

ᑍ/

QWDRJOBD(rec_var,

39ð,

/ᑍ Receiver Variable

/ᑍ Receiver Length

/ᑍ Format Name

/ᑍ Qualified Job Description

/ᑍ Error Code

ᑍ/

"JOBDð1ðð",

qual_job_desc,

&error_code);

/ᑍ If an error was returned, send an error message.

ᑍ/

if(error_code.ec_fields.Bytes_Available > ð) .13/

{

memcpy(message_id, error_code.ec_fields.Exception_Id, 7);

sprintf(message_string,

"SNDMSG MSG('Program failed with message ID %.7s') TOUSR(QPGMR)",

message_id);

system(message_string);

}

/ᑍ Let's tell everyone what the hold value was for this job.

ᑍ/

else

{

memcpy(hold_value, ((Qwd_JOBDð1ðð_t ᑍ)rec_var)->Hold_Job_Queue, 1ð);

sprintf(command_string,

"SNDMSG MSG('HOLD value is %.1ðs') TOUSR(QPGMR)",

hold_value);

system(command_string);

}

} /ᑍ main ᑍ/

Appendix B. Original Examples in Additional Languages B-11

Download from Www.Somanuals.com. All Manuals Search And Download.

Retrieving the Hold Parameter (Error Code Structure)—ILE COBOL

Example

Refer to “Retrieving the Hold Parameter (Error Code Structure)—OPM RPG

Example” on page 3-11 for the original example. The following program also works

for OPM COBOL.

IDENTIFICATION DIVISION.

ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

ᑍ

ᑍProgram Name:

ᑍ

JOBDAPI

ᑍProgramming Language: COBOL

ᑍ

ᑍDescription:

This example shows how to make use of an

error returned in the error code

structure.

ᑍ

ᑍHeader Files Included: QUSEC - Error Code Parameter

ᑍ

QWDRJOBD - Retrieve Job Description API

ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

ᑍ

PROGRAM-ID. JOBDAPI.

ᑍ

ENVIRONMENT DIVISION.

CONFIGURATION SECTION.

SOURCE-COMPUTER. IBM-AS4ðð.

OBJECT-COMPUTER. IBM-AS4ðð.

ᑍ

DATA DIVISION.

WORKING-STORAGE SECTION.

ᑍ

ᑍ Error Code parameter include. As this sample program

ᑍ uses COPY to include the error code structure, only the first

ᑍ 16 bytes of the error code structure are available. If the

ᑍ application program needs to access the variable length

ᑍ exception data for the error, the developer should physically

ᑍ copy the QSYSINC include and modify the copied include to

ᑍ define additional storage for the exception data.

ᑍ

COPY QUSEC OF QSYSINC-QLBLSRC. .14/

ᑍ

ᑍ Retrieve Job Description API Include

ᑍ

COPY QWDRJOBD OF QSYSINC-QLBLSRC.

ᑍ

ᑍ Command String Data Structure

ᑍ

ð1 COMMAND-STRING.

ð5 TEXT1 PIC X(26) VALUE 'SNDMSG MSG(''HOLD value is'.

ð5 HOLD PIC X(1ð).

ð5 TEXT2 PIC X(15) VALUE ''') TOUSR(QPGMR)'.

ᑍ

ᑍ Message Identifier Data Structure

ᑍ

B-12 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

ð1 MESSAGE-TWO.

ð5 MSG2A PIC X(43)

VALUE 'SNDMSG MSG(''Program failed with message ID'.

ð5 MSGIDD PIC X(7).

ð5 MSG2B PIC X(15) VALUE ''') TOUSR(QPGMR)'.

ᑍ

ð1 COMMAND-LENGTH PIC S9(1ð)V99999 COMP-3.

ð1 RECEIVER-LENGTH PIC S9(9) COMP-4.

ð1 FORMAT-NAME PIC X(8) VALUE 'JOBDð1ðð'.

ð1 QCMDEXC PIC X(1ð) VALUE 'QCMDEXC'.

ᑍ Job Description and Library Name Structure

ᑍ

ð1 JOBD-AND-LIB-NAME.

ð5 JOB-DESC PIC X(1ð).

ð5 JOB-DESC-LIB PIC X(1ð).

ᑍ

LINKAGE SECTION.

ᑍ

ᑍ Two Parameters are being passed into this program.

ᑍ

ð1 JOBD PIC X(1ð).

ð1 JOBDL PIC X(1ð).

ᑍ

PROCEDURE DIVISION USING JOBD, JOBDL.

MAIN-LINE.

ᑍ

ᑍ Beginning of Mainline

ᑍ

ᑍ Move the two parameters passed into JOB-DESC and JOB-DESC-LIB.

ᑍ

MOVE JOBD TO JOB-DESC.

MOVE JOBDL TO JOB-DESC-LIB.

ᑍ

ᑍ Error Code Parameter is set to 16.

ᑍ

MOVE 16 TO BYTES-PROVIDED. .15/

ᑍ

ᑍ Receiver Length Set to 39ð.

ᑍ

MOVE 39ð TO RECEIVER-LENGTH.

ᑍ

ᑍ Call the QWDRJOBD API.

ᑍ

CALL QWDRJOBD USING QWD-JOBDð1ðð, RECEIVER-LENGTH,

FORMAT-NAME, JOBD-AND-LIB-NAME, QUS-EC.

ᑍ

ᑍ See if any errors were returned in the error code parameter.

ᑍ

PERFORM ERRCOD.

ᑍ

ᑍ Move HOLD-JOB-QUEUE to HOLD so that we can display the value using

ᑍ the command string.

ᑍ

MOVE HOLD-JOB-QUEUE TO HOLD.

ᑍ

ᑍ Let's tell everyone what the hold value was for this job.

ᑍ

Appendix B. Original Examples in Additional Languages B-13

Download from Www.Somanuals.com. All Manuals Search And Download.

MOVE 51 TO COMMAND-LENGTH.

CALL QCMDEXC USING COMMAND-STRING, COMMAND-LENGTH.

ᑍ

STOP RUN.

ᑍ End of Mainline

ᑍ

ᑍ Subroutine to handle errors returned in the error code

ᑍ parameter.

ᑍ

ERRCOD.

ᑍ

IF BYTES-AVAILABLE OF QUS-EC > ð .13/

ᑍ

ᑍ Process errors returned from the API.

ᑍ

MOVE 65 TO COMMAND-LENGTH,

MOVE EXCEPTION-ID TO MSGIDD,

CALL QCMDEXC USING MESSAGE-TWO, COMMAND-LENGTH,

STOP RUN.

Retrieving the Hold Parameter (Error Code Structure)—ILE RPG

Example

Refer to “Retrieving the Hold Parameter (Error Code Structure)—OPM RPG

Example” on page 3-11 for the original example.

Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Dᑍ

Dᑍ Program Name: JOBDAPI

Dᑍ

Dᑍ Programming Language: ILE RPG

Dᑍ

Dᑍ Description: This program retrieves the HOLD value from

Dᑍ

a job description. It expects errors to be

returned via the error code parameter.

Dᑍ Header Files Included: QUSEC - Error Code Parameter

Dᑍ

QWDRJOBD - Retrieve Job Description API

Dᑍ

Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Dᑍ

Dᑍ Error Code parameter include

Dᑍ

D/COPY QSYSINC/QRPGLESRC,QUSEC .14/

Dᑍ

Dᑍ Retrieve Job Description API Include

Dᑍ

D/COPY QSYSINC/QRPGLESRC,QWDRJOBD

Dᑍ

Dᑍ Command string data structure

Dᑍ

DCMD_STRING

1ð

INZ('SNDMSG MSG(''HOLD value is ')

D HOLD

B-14 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

INZ(''') TOUSR(QPGMR)')

DCMD_STR2

INZ('SNDMSG MSG(''Program failed -

with message ID ')

D MSG_ID

Dᑍ

INZ(''') TOUSR(QPGMR)')

Dᑍ Miscellaneous data structure

Dᑍ

DRCVLEN

DFORMAT

DLENSTR

DLENSTR2

Cᑍ

9B ð INZ(%SIZE(QWDDð1ðð))

INZ('JOBDð1ðð')

15 5 INZ(%SIZE(CMD_STRING))

15 5 INZ(%SIZE(CMD_STR2))

Cᑍ Beginning of mainline

Cᑍ

Cᑍ Two parameters are being passed into this program

Cᑍ

ᑍENTRY

PLIST

PARM

JOBD

JOBD_LIB

1ð

Cᑍ

Cᑍ Move the two parameters passed into LFNAM

Cᑍ

JOBD

CAT

JOBD_LIB

LFNAM

2ð

Cᑍ

Cᑍ Error Code Bytes Provided is set to 16

Cᑍ

EVAL

QUSBPRV = %SIZE(QUSEC) .15/

Cᑍ

Cᑍ Call the API.

Cᑍ

CALL

PARM

QWDRJOBD

QWDDð1ðð

RCVLEN

FORMAT

LFNAM

QUSEC

Cᑍ

Cᑍ Test for an error on the API call

Cᑍ

QUSBAVL > ð

.13/

Cᑍ

Cᑍ If there was an error, exit to ERROR subroutine

Cᑍ

EXSR

ERROR

Cᑍ Else, process the HOLD value

Cᑍ

ELSE

MOVEL

QWDHJQ

HOLD

Cᑍ

Cᑍ Let's tell everyone what the hold value was for this job

Cᑍ

CALL

PARM

END

'QCMDEXC'

CMD_STRING

LENSTR

Appendix B. Original Examples in Additional Languages B-15

Download from Www.Somanuals.com. All Manuals Search And Download.

Cᑍ

EVAL

RETURN

ᑍINLR = '1'

Cᑍ

Cᑍ End of MAINLINE

Cᑍ

Cᑍ Subroutine to handle errors received on the CALL

Cᑍ

ERROR

BEGSR

Cᑍ Process errors returned from the API

Cᑍ

MOVEL

CALL

PARM

ENDSR

QUSEI

MSG_ID

'QCMDEXC'

CMD_STR2

LENSTR2

Accessing the HOLD Attribute—ILE C Example

Refer to “Accessing the HOLD Attribute—OPM RPG Example” on page 3-17 for

the original example.

/ᑍ

ᑍ/

/ᑍProgram Name:

/ᑍ

JOBDAPI

/ᑍProgramming Language: ILE C

/ᑍ

/ᑍDescription:

This example shows how to print messages

to spool files.

/ᑍ

/ᑍHeader Files Included: STDIO - Standard Input/Output

/ᑍ

STRING - String Functions

QUSEC - Error Code Parameter

QWDRJOBD - Retrieve Job Description API

QLIEPT - Entry Point Table

#include <stdio.h>

#include <string.h>

#include <qusec.h>

#include <qwdrjobd.h>

#include <qliept.h>

/ᑍ Error Code Parameter Include for the APIs ᑍ/

/ᑍ Retrieve Job Description API Include

/ᑍ Entry Point Table Include

ᑍ/

/ᑍ Error Code Structure

/ᑍ

ᑍ/

/ᑍ This shows how the user can define the variable length portion of ᑍ/

/ᑍ error code for the exception data.

/ᑍ

ᑍ/

typedef struct {

Qus_EC_t ec_fields;

char

Exception_Data[1ðð];

B-16 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

} error_code_t;

main(int argc, char ᑍargv[])

{

error_code_t error_code;

char

FILE

qual_job_desc[2ð];

ᑍqual_job_ptr = qual_job_desc;

rec_var[39ð];

hold_value[1ð];

message_id[7];

command_string[25];

message_string[29];

ᑍstream;

memset(hold_value, ' ', 1ð);

/ᑍ Make sure we received the correct number of parameters. The argc ᑍ/

/ᑍ parameter will contain the number of parameters that was passed ᑍ/

/ᑍ to this program. This number also includes the program itself,

/ᑍ so we need to evaluate argc-1.

ᑍ/

if (((argc - 1) < 2) || ((argc - 1 > 2)))

/ᑍ We did not receive all of the required parameters so exit the

/ᑍ program.

ᑍ/

{

exit(1);

}

/ᑍ Move the two parameter passed into qual_job_desc.

ᑍ/

memcpy(qual_job_ptr, argv[1], 1ð);

qual_job_ptr += 1ð;

memcpy(qual_job_ptr, argv[2], 1ð);

/ᑍ Set the error code parameter to 16.

ᑍ/

error_code.ec_fields.Bytes_Provided = 16;

/ᑍ Open QPRINT file so that data can be written to it. If the file ᑍ/

/ᑍ cannot be opened, print a message and exit.

ᑍ/

if((stream = fopen("QPRINT", "wb")) == NULL)

{

printf("File could not be opened\n");

exit(1);

}

/ᑍ Call the QWDRJOBD API.

ᑍ/

QWDRJOBD(rec_var, /ᑍ Receiver Variable ᑍ/

Appendix B. Original Examples in Additional Languages B-17

Download from Www.Somanuals.com. All Manuals Search And Download.

39ð,

/ᑍ Receiver Length

/ᑍ Format Name

/ᑍ Qualified Job Description

/ᑍ Error Code

ᑍ/

"JOBDð1ðð",

qual_job_desc,

&error_code);

/ᑍ If an error was returned, print the error message to the QPRINT ᑍ/

/ᑍ spool file.

ᑍ/

if(error_code.ec_fields.Bytes_Available > ð)

{

memcpy(message_id, error_code.ec_fields.Exception_Id, 7);

sprintf(message_string,

"Failed. Error ID - %.7s",

message_id);

fprintf(stream, message_string);

}

/ᑍ Let's tell everyone what the hold value was for this job.

/ᑍ The result will be printed in the QPRINT spool file.

ᑍ/

else

{

memcpy(hold_value, ((Qwd_JOBDð1ðð_t ᑍ)rec_var)->Hold_Job_Queue, 1ð);

sprintf(command_string,

"HOLD value - %.1ðs",

hold_value);

fprintf(stream, command_string);

}

fclose(stream);

} /ᑍ main ᑍ/

Accessing the HOLD Attribute—ILE COBOL Example

Refer to “Accessing the HOLD Attribute—OPM RPG Example” on page 3-17 for

the original example. The following example also works for OPM COBOL.

IDENTIFICATION DIVISION.

ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

ᑍ

ᑍProgram Name:

ᑍ

JOBDAPI

ᑍProgramming Language: COBOL

ᑍ

ᑍDescription:

This example shows how to print messages

to spool files.

ᑍ

ᑍHeader Files Included: QUSEC - Error Code Parameter

ᑍ

QWDRJOBD - Retrieve Job Description API

ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

ᑍ

PROGRAM-ID. JOBDAPI.

ᑍ

B-18 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

ENVIRONMENT DIVISION.

CONFIGURATION SECTION.

SOURCE-COMPUTER. IBM-AS4ðð.

OBJECT-COMPUTER. IBM-AS4ðð.

ᑍ

INPUT-OUTPUT SECTION.

FILE-CONTROL.

SELECT LISTING ASSIGN TO PRINTER-QPRINT

ORGANIZATION IS SEQUENTIAL.

DATA DIVISION.

FILE SECTION.

FD LISTING RECORD CONTAINS 132 CHARACTERS

LABEL RECORDS ARE STANDARD

DATA RECORD IS LIST-LINE.

ð1 LIST-LINE

PIC X(132).

ᑍ

WORKING-STORAGE SECTION.

ᑍ Error Code parameter include. As this sample program

ᑍ uses COPY to include the error code structure, only the first

ᑍ 16 bytes of the error code structure are available. If the

ᑍ application program needs to access the variable length

ᑍ exception data for the error, the developer should physically

ᑍ copy the QSYSINC include and modify the copied include to

ᑍ define additional storage for the exception data.

ᑍ

COPY QUSEC OF QSYSINC-QLBLSRC.

ᑍ

ᑍ Retrieve Job Description API Include

ᑍ

COPY QWDRJOBD OF QSYSINC-QLBLSRC.

ᑍ

ᑍ Command String Data Structure

ᑍ

ð1 HOLD-VALUE.

ð5 TEXT1 PIC X(13) VALUE 'HOLD value - '.

ð5 HOLD PIC X(1ð).

ᑍ

ᑍ Error Message Text

ᑍ

ð1 MESSAGE-TEXT.

ð5 MSG1 PIC X(19) VALUE 'Failed. Error ID - '.

ð5 MSGID PIC X(7).

ᑍ

ð1 RECEIVER-LENGTH PIC S9(9) COMP-4.

ð1 FORMAT-NAME PIC X(8) VALUE 'JOBDð1ðð'.

ð1 QCMDEXC PIC X(1ð) VALUE 'QCMDEXC'.

ᑍ

ᑍ Job Description and Library Name Structure

ᑍ

ð1 JOBD-AND-LIB-NAME.

ð5 JOB-DESC PIC X(1ð).

ð5 JOB-DESC-LIB PIC X(1ð).

ᑍ

LINKAGE SECTION.

Appendix B. Original Examples in Additional Languages B-19

Download from Www.Somanuals.com. All Manuals Search And Download.

ᑍ

ᑍ Two Parameters are being passed into this program.

ᑍ

ð1 JOBD PIC X(1ð).

ð1 JOBDL PIC X(1ð).

ᑍ

PROCEDURE DIVISION USING JOBD, JOBDL.

MAIN-LINE.

ᑍ

ᑍ Beginning of Mainline

ᑍ

ᑍ Move the two parameters passed into JOB-DESC and JOB-DESC-LIB.

ᑍ

MOVE JOBD TO JOB-DESC.

MOVE JOBDL TO JOB-DESC-LIB.

ᑍ

ᑍ Error Code Parameter is set to 16.

ᑍ

MOVE 16 TO BYTES-PROVIDED.

ᑍ

ᑍ Receiver Length Set to 39ð.

ᑍ

MOVE 39ð TO RECEIVER-LENGTH.

ᑍ

ᑍ Call the QWDRJOBD API.

ᑍ

CALL QWDRJOBD USING QWD-JOBDð1ðð, RECEIVER-LENGTH,

FORMAT-NAME, JOBD-AND-LIB-NAME, QUS-EC.

ᑍ

ᑍ If no bytes available, API was successful; print HOLD value

ᑍ

IF BYTES-AVAILABLE OF QUS-EC = ð PERFORM GOOD.

ᑍ

ᑍ If some bytes available, API failed; print Error message ID

ᑍ

IF BYTES-AVAILABLE OF QUS-EC > ð PERFORM BAD.

ᑍ

STOP RUN.

ᑍ

ᑍ End of Mainline

ᑍ

ᑍ Subroutine to perform if no errors were encountered.

ᑍ

GOOD.

OPEN OUTPUT LISTING.

MOVE HOLD-JOB-QUEUE TO HOLD.

WRITE LIST-LINE FROM HOLD-VALUE.

ᑍ

ᑍ Subroutine to perform if an error was returned in error code.

ᑍ

BAD.

OPEN OUTPUT LISTING.

MOVE EXCEPTION-ID TO MSGID.

B-20 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

WRITE LIST-LINE FROM MESSAGE-TEXT.

STOP RUN.

Accessing the HOLD Attribute—ILE RPG Example

Refer to “Accessing the HOLD Attribute—OPM RPG Example” on page 3-17 for

the original example.

Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Fᑍ

Fᑍ Program Name: JOBDAPI

Fᑍ

Fᑍ Programming Language: ILE RPG

Fᑍ

Fᑍ Description: This program retrieves the HOLD value from

Fᑍ

a job description and then prints the value.

It expects errors to be returned via the

error code parameter.

Fᑍ Header Files Included: QUSEC - Error Code Parameter

Fᑍ

QWDRJOBD - Retrieve Job Description API

Fᑍ

Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Fᑍ

FQPRINT

Dᑍ

F 132

PRINTER OFLIND(ᑍINOF)

Dᑍ Error Code parameter include

Dᑍ

D/COPY QSYSINC/QRPGLESRC,QUSEC

Dᑍ

Dᑍ Retrieve Job Description API Include

Dᑍ

D/COPY QSYSINC/QRPGLESRC,QWDRJOBD

Dᑍ

Dᑍ Miscellaneous data structure

Dᑍ

DRCVLEN

DFORMAT

Cᑍ

9B ð INZ(%SIZE(QWDDð1ðð))

INZ('JOBDð1ðð')

Cᑍ Beginning of mainline

Cᑍ

Cᑍ Two parameters are being passed into this program

Cᑍ

ᑍENTRY

PLIST

PARM

JOBD

JOBD_LIB

1ð

Cᑍ

Cᑍ Move the two parameters passed into LFNAM

Cᑍ

JOBD

CAT

JOBD_LIB

LFNAM

2ð

Cᑍ

Cᑍ Error Code Bytes Provided is set to 16

Cᑍ

EVAL

QUSBPRV = %SIZE(QUSEC)

Cᑍ

Cᑍ Call the API.

Appendix B. Original Examples in Additional Languages B-21

Download from Www.Somanuals.com. All Manuals Search And Download.

Cᑍ

CALL

PARM

QWDRJOBD

QWDDð1ðð

RCVLEN

FORMAT

LFNAM

QUSEC

Cᑍ

Cᑍ If no bytes available, API was successful; print HOLD value

Cᑍ

EXCEPT

ELSE

QUSBAVL = ð

GOOD

Cᑍ

Cᑍ If some bytes available, API failed; print Error message ID

Cᑍ

QUSBAVL > ð

BAD

EXCEPT

END

Cᑍ

END

Cᑍ End of program

Cᑍ

EVAL

RETURN

ᑍINLR = '1'

Cᑍ End of MAINLINE

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Oᑍ

OQPRINT

GOOD

1 6

'HOLD value - '

QWDHJQ

BAD

OQPRINT

1 6

'Failed. Error ID - '

QUSEI

Accessing a Field Value (Initial Library List)—ILE C Example

Refer to “Accessing a Field Value (Initial Library List)—OPM RPG Example” on

page 3-19 for the original example.

/ᑍ

ᑍ/

/ᑍProgram Name:

/ᑍ

JOBDAPI

/ᑍProgramming Language: ILE C

/ᑍ

/ᑍDescription:

This example shows how to access a field

value returned from a retrieve API.

/ᑍ

/ᑍHeader Files Included: STDIO - Standard Input/Output

/ᑍ

STRING - String Functions

QUSEC - Error Code Parameter

QWDRJOBD - Retrieve Job Description API

QLIEPT - Entry Point Table

B-22 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

#include <stdio.h>

#include <string.h>

#include <qusec.h>

#include <qwdrjobd.h>

#include <qliept.h>

/ᑍ Error Code Parameter Include for the APIs ᑍ/

/ᑍ Retrieve Job Description API Include

/ᑍ Entry Point Table Include

ᑍ/

/ᑍ Error Code Structure

/ᑍ

ᑍ/

/ᑍ This shows how the user can define the variable-length portion of ᑍ/

/ᑍ error code for the exception data.

/ᑍ

ᑍ/

typedef struct {

Qus_EC_t ec_fields;

char

Exception_Data[1ðð]; .7/

} error_code_t;

/ᑍ JOBDð1ðð Structure

/ᑍ

ᑍ/

/ᑍ This shows how the user can define the variable-length portion of ᑍ/

/ᑍ the JOBDð1ðð format.

/ᑍ

ᑍ/

typedef struct {

Qwd_JOBDð1ðð_t data;

char

} JOBDð1ðð;

Lib_Data[61ð]; .19/ .2ð/

main(int argc, char ᑍargv[])

{

error_code_t error_code;

char

int

library[1ð];

qual_job_desc[2ð];

ᑍqual_job_ptr = qual_job_desc;

rec_var[1ððð];

ᑍrec_ptr = rec_var;

hold_value[1ð];

message_id[7];

command_string[49];

int

num_libs;

int

offset;

int

rec_len = 1ððð;

memset(hold_value, ' ', 1ð);

/ᑍ Make sure we received the correct number of parameters. The argc ᑍ/

/ᑍ parameter will contain the number of parameters that was passed ᑍ/

/ᑍ to this program. This number also includes the program itself,

/ᑍ so we need to evaluate argc-1.

ᑍ/

Appendix B. Original Examples in Additional Languages B-23

Download from Www.Somanuals.com. All Manuals Search And Download.

if (((argc - 1) < 2) || ((argc - 1 > 2)))

/ᑍ We did not receive all of the required parameters so exit the

/ᑍ program.

ᑍ/

{

exit(1);

}

/ᑍ Move the two parameter passed into qual_job_desc.

ᑍ/

memcpy(qual_job_ptr, argv[1], 1ð);

qual_job_ptr += 1ð;

memcpy(qual_job_ptr, argv[2], 1ð);

/ᑍ Set the error code parameter to 16.

ᑍ/

error_code.ec_fields.Bytes_Provided = 16;

/ᑍ Call the QWDRJOBD API.

ᑍ/

QWDRJOBD(rec_var,

rec_len,

/ᑍ Receiver Variable

/ᑍ Receiver Length

/ᑍ Format Name

/ᑍ Qualified Job Description

/ᑍ Error Code

ᑍ/

"JOBDð1ðð",

qual_job_desc,

&error_code);

/ᑍ If an error was returned, send an error message.

ᑍ/

if(error_code.ec_fields.Bytes_Available > ð)

{

/ᑍ In this example, nothing was done for the error condition.

ᑍ/

}

/ᑍ Let's tell everyone what the library value was for this job.

ᑍ/

else

{

num_libs = ((JOBDð1ðð ᑍ)rec_var)->data.Number_Libs_In_Lib_list;

offset = ((JOBDð1ðð ᑍ)rec_var)->data.Offset_Initial_Lib_List;

/ᑍ Advance receiver variable pointer to the location where the

/ᑍ library list begins.

ᑍ/

rec_ptr += offset;

for(i=ð; i<num_libs; i++)

{

memcpy(library, rec_ptr, 1ð);

sprintf(command_string,

"SNDMSG MSG('LIBRARY %.1ðs') TOUSR(QPGMR)",

library);

system(command_string);

B-24 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

rec_ptr += 11;

if((offset + 1ð) >= rec_len)

break;

offset += 11;

}

} /ᑍ main ᑍ/

Accessing a Field Value (Initial Library List)—ILE COBOL Example

Refer to “Accessing a Field Value (Initial Library List)—OPM RPG Example” on

page 3-19 for the original example. The following program also works for OPM

COBOL.

IDENTIFICATION DIVISION.

ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

ᑍ

ᑍProgram Name:

ᑍ

JOBDAPI

ᑍProgramming Language: COBOL

ᑍ

ᑍDescription:

This example shows how to access a

field value returned from a retrieve

API.

ᑍ

ᑍHeader Files Included: QUSEC - Error Code Parameter

ᑍ

QWDRJOBD - Retrieve Job Description API

ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

ᑍ

PROGRAM-ID. JOBDAPI.

ᑍ

ENVIRONMENT DIVISION.

CONFIGURATION SECTION.

SOURCE-COMPUTER. IBM-AS4ðð.

OBJECT-COMPUTER. IBM-AS4ðð.

ᑍ

DATA DIVISION.

WORKING-STORAGE SECTION.

ᑍ

ᑍ Error Code parameter include. As this sample program

ᑍ uses COPY to include the error code structure, only the first

ᑍ 16 bytes of the error code structure are available. If the

ᑍ application program needs to access the variable length

ᑍ exception data for the error, the developer should physically

ᑍ copy the QSYSINC include and modify the copied include to

ᑍ define additional storage for the exception data.

ᑍ

COPY QUSEC OF QSYSINC-QLBLSRC.

ᑍ

ᑍ Retrieve Job Description API Include

ᑍ

ᑍ The header file for the QWDRJOBD API was included in this

Appendix B. Original Examples in Additional Languages B-25

Download from Www.Somanuals.com. All Manuals Search And Download.

ᑍ program so that the varying length portion of the structure

ᑍ can be defined as a fixed portion.

ᑍ

ᑍᑍᑍ START HEADER FILE SPECIFICATIONS ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

ᑍ

ᑍHeader File Name: H/QWDRJOBD

ᑍ

ᑍDescriptive Name: Retrieve Job Description Information API

ᑍ

ᑍ5763-SS1 (C) Copyright IBM Corp. 1994,1994

ᑍUS Government Users Restricted Rights -

ᑍUse, duplication or disclosure restricted

ᑍby GSA ADP Schedule Contract with IBM Corp.

ᑍ

ᑍLicensed Materials-Property of IBM

ᑍ

ᑍDescription: The Retrieve Job Description Information API

ᑍ

retrieves information from a job description

object and places it into a single variable in the

calling program.

ᑍHeader Files Included: None.

ᑍ

ᑍMacros List: None.

ᑍ

ᑍStructure List: Qwd_JOBDð1ðð_t

ᑍ

ᑍFunction Prototype List: QWDRJOBD

ᑍ

ᑍChange Activity:

ᑍ

ᑍCFD List:

ᑍ

ᑍFLAG REASON

LEVEL DATE PGMR

CHANGE DESCRIPTION

ᑍ---- ------------ ----- ------ --------- ----------------------

ᑍ$Að= D2862ððð

ᑍ

3D1ð 94ð424 ROCH:

New Include

ᑍEnd CFD List.

ᑍ

ᑍAdditional notes about the Change Activity

ᑍEnd Change Activity.

ᑍ

ᑍᑍᑍ END HEADER FILE SPECIFICATIONS ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

ᑍPrototype for QWDRJOBD API

ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

77 QWDRJOBD

PIC X(ððð1ð)

VALUE "QWDRJOBD".

ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

ᑍType Definition for the JOBDð1ðð format.

ᑍᑍᑍᑍ

ᑍᑍᑍ

ᑍNOTE: The following type definition defines only the fixed

ᑍ portion of the format. Any varying length field will

ᑍ have to be defined by the user.

ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

ð1 RECEIVER-VARIABLE PIC X(ð1ððð).

B-26 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

ð1 QWD-JOBDð1ðð REDEFINES RECEIVER-VARIABLE.

ð5 BYTES-RETURNED

PIC S9(ðððð9) BINARY.

PIC X(ððð1ð).

ð5 BYTES-AVAILABLE

ð5 JOB-DESCRIPTION-NAME

ð5 JOB-DESCRIPTION-LIB-NAME

ð5 USER-NAME

PIC X(ððð1ð).

ð5 JOB-DATE

PIC X(ðððð8).

ð5 JOB-SWITCHES

ð5 JOB-QUEUE-NAME

PIC X(ðððð8).

PIC X(ððð1ð).

ð5 JOB-QUEUE-LIB-NAME

ð5 JOB-QUEUE-PRIORITY

ð5 HOLD-JOB-QUEUE

ð5 OUTPUT-QUEUE-NAME

ð5 OUTPUT-QUEUE-LIB-NAME

ð5 OUTPUT-QUEUE-PRIORITY

ð5 PRINTER-DEVICE-NAME

ð5 PRINT-TEXT

PIC X(ððð1ð).

PIC X(ðððð2).

PIC X(ððð1ð).

PIC X(ðððð2).

PIC X(ððð1ð).

PIC X(ððð3ð).

ð5 SYNTAX-CHECK-SEVERITY

ð5 END-SEVERITY

ð5 MESSAGE-LOG-SEVERITY

ð5 MESSAGE-LOG-LEVEL

ð5 MESSAGE-LOG-TEXT

ð5 LOG-CL-PROGRAMS

ð5 INQUIRY-MESSAGE-REPLY

ð5 DEVICE-RECOVERY-ACTION

ð5 TIME-SLICE-END-POOL

ð5 ACCOUNTING-CODE

PIC S9(ðððð9) BINARY.

PIC X(ðððð1).

PIC X(ððð1ð).

PIC X(ððð13).

PIC X(ððð1ð).

PIC X(ððð15).

ð5 ROUTING-DATA

ð5 TEXT-DESCRIPTION

ð5 RESERVED

PIC X(ððð8ð).

PIC X(ððð5ð).

PIC X(ðððð1).

ð5 OFFSET-INITIAL-LIB-LIST

ð5 NUMBER-LIBS-IN-LIB-LIST

ð5 OFFSET-REQUEST-DATA

ð5 LENGTH-REQUEST-DATA

ð5 JOB-MESSAGE-QUEUE-MAX-SIZE

ð5 JOB-MESSAGE-QUEUE-FULL-ACTION

ð5 RESERVED2

PIC S9(ðððð9) BINARY. .19/

PIC S9(ðððð9) BINARY. .2ð/

PIC S9(ðððð9) BINARY.

PIC X(ððð1ð).

ᑍ

PIC X(ðððð1).

Varying length

ð5 INITIAL-LIB-LIST

PIC X(ððð11).

PIC X(ðððð1).

Varying length

ð5 REQUEST-DATA

Varying length

ᑍ Command String Data Structure

ᑍ

ð1 COMMAND-STRING.

ð5 TEXT1 PIC X(22) VALUE 'SNDMSG MSG(''LIBRARY- '.

ð5 LIB PIC X(1ð).

ð5 TEXT2 PIC X(15) VALUE ''') TOUSR(QPGMR)'.

ᑍ

ð1 COMMAND-LENGTH PIC S9(1ð)V99999 COMP-3.

ð1 RECEIVER-LENGTH PIC S9(9) COMP-4.

ð1 FORMAT-NAME PIC X(8) VALUE 'JOBDð1ðð'.

ð1 QCMDEXC PIC X(1ð) VALUE 'QCMDEXC'.

Appendix B. Original Examples in Additional Languages B-27

Download from Www.Somanuals.com. All Manuals Search And Download.

ð1 X PIC S9(9) BINARY.

ᑍ

ᑍ Job Description and Library Name Structure

ᑍ

ð1 JOBD-AND-LIB-NAME.

ð5 JOB-DESC PIC X(1ð).

ð5 JOB-DESC-LIB PIC X(1ð).

ᑍ

LINKAGE SECTION.

ᑍ

ᑍ Two Parameters are being passed into this program.

ᑍ

ð1 JOBD PIC X(1ð).

ð1 JOBDL PIC X(1ð).

ᑍ

PROCEDURE DIVISION USING JOBD, JOBDL.

MAIN-LINE.

ᑍ

ᑍ Beginning of Mainline

ᑍ

ᑍ Move the two parameters passed into JOB-DESC and JOB-DESC-LIB.

ᑍ

MOVE JOBD TO JOB-DESC.

MOVE JOBDL TO JOB-DESC-LIB.

ᑍ

ᑍ Error Code Parameter is set to 1ðð.

ᑍ

MOVE 1ðð TO BYTES-PROVIDED.

ᑍ

ᑍ Receiver Length Set to 1ððð.

ᑍ

MOVE 1ððð TO RECEIVER-LENGTH.

ᑍ

ᑍ Call the QWDRJOBD API.

ᑍ

CALL QWDRJOBD USING RECEIVER-VARIABLE, RECEIVER-LENGTH,

FORMAT-NAME, JOBD-AND-LIB-NAME, QUS-EC.

ᑍ

ᑍ See if any errors were returned in the error code parameter.

ᑍ

PERFORM ERRCOD.

ᑍ

ᑍ Add one to the Initial library list offset because COBOL is a

ᑍ Base 1 language.

ᑍ

MOVE OFFSET-INITIAL-LIB-LIST TO X.

ADD 1 TO X.

MOVE 47 TO COMMAND-LENGTH.

ᑍ

ᑍ Let's tell everyone what the library value was for this job.

ᑍ

PERFORM NUMBER-LIBS-IN-LIB-LIST TIMES

MOVE RECEIVER-VARIABLE(X:1ð) TO LIB,

CALL QCMDEXC USING COMMAND-STRING, COMMAND-LENGTH,

ADD 11 TO X,

PERFORM RECLEN,

END-PERFORM.

B-28 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

ᑍ

STOP RUN.

ᑍ End of Mainline

ᑍ

ᑍ Subroutine to handle errors returned in the error code

ᑍ parameter.

ᑍ

ERRCOD.

ᑍ

IF BYTES-AVAILABLE OF QUS-EC > ð

ᑍ

ᑍ Process errors returned from the API.

ᑍ

STOP RUN.

ᑍ

ᑍ Subroutine to check to see if there is enough room in the

ᑍ receiver variable for the next library in the list.

ᑍ

RECLEN.

ᑍ

IF (X + 1ð) >= RECEIVER-LENGTH

STOP RUN.

Accessing a Field Value (Initial Library List)—ILE RPG Example

Refer to “Accessing a Field Value (Initial Library List)—OPM RPG Example” on

page 3-19 for the original example.

Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Dᑍ

Dᑍ Program Name: JOBDAPI

Dᑍ

Dᑍ Programming Language: ILE RPG

Dᑍ

Dᑍ Description: This program retrieves the library list from

Dᑍ

a job description. It expects errors to be

returned via the error code parameter.

Dᑍ Header Files Included: QUSEC - Error Code Parameter

Dᑍ

Dᑍ Header Files Modified: QWDRJOBD - Retrieve Job Description API

Dᑍ

Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Dᑍ

Dᑍ Error Code parameter include

Dᑍ

D/COPY QSYSINC/QRPGLESRC,QUSEC

Dᑍ

Dᑍ The following QWDRJOBD include from QSYSINC is copied into

Dᑍ this program so that it can be declared as 1ððð bytes in

Dᑍ size. This size should accommodate the variable length Library

Dᑍ List array.

Dᑍ

Appendix B. Original Examples in Additional Languages B-29

Download from Www.Somanuals.com. All Manuals Search And Download.

Dᑍᑍᑍ START HEADER FILE SPECIFICATIONS ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Dᑍ

DᑍHeader File Name: H/QWDRJOBD

Dᑍ

DᑍDescriptive Name: Retrieve Job Description Information API

Dᑍ

Dᑍ5763-SS1 (C) Copyright IBM Corp. 1994,1994

DᑍUS Government Users Restricted Rights -

DᑍUse, duplication or disclosure restricted

Dᑍby GSA ADP Schedule Contract with IBM Corp.

Dᑍ

DᑍLicensed Materials-Property of IBM

Dᑍ

DᑍDescription: The Retrieve Job Description Information API

Dᑍ

retrieves information from a job description

object and places it into a single variable in the

calling program.

DᑍHeader Files Included: None.

Dᑍ

DᑍMacros List: None.

Dᑍ

DᑍStructure List: Qwd_JOBDð1ðð_t

Dᑍ

DᑍFunction Prototype List: QWDRJOBD

Dᑍ

DᑍChange Activity:

Dᑍ

DᑍCFD List:

Dᑍ

DᑍFLAG REASON

LEVEL DATE PGMR

CHANGE DESCRIPTION

Dᑍ---- ------------ ----- ------ --------- ----------------------

Dᑍ$Að= D2862ððð

Dᑍ

3D1ð 94ð424 ROCH:

New Include

DᑍEnd CFD List.

Dᑍ

DᑍAdditional notes about the Change Activity

DᑍEnd Change Activity.

Dᑍᑍᑍ END HEADER FILE SPECIFICATIONS ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

DᑍPrototype for QWDRJOBD API

Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

D QWDRJOBD

'QWDRJOBD'

Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

DᑍType Definition for the JOBDð1ðð format.

Dᑍᑍᑍᑍ

ᑍᑍᑍ

DᑍNOTE: The following type definition defines only the fixed

Dᑍ portion of the format. Any varying length field will

Dᑍ have to be defined by the user.

Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

DQWDDð1ðð

Dᑍ

D QWDBRTN

Dᑍ

D QWDBAVL

Dᑍ

1ððð

4B ð

8B ð

Qwd JOBDð1ðð

Bytes Returned

Bytes Available

B-30 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

D QWDJDN

Dᑍ

D QWDJDLN

Dᑍ

D QWDUN

Dᑍ

D QWDJD

Dᑍ

D QWDJS

Dᑍ

D QWDJQNðð

Dᑍ

D QWDJQLNðð

Dᑍ

D QWDJQP

Dᑍ

D QWDHJQ

Dᑍ

D QWDOQN

Dᑍ

D QWDOQLN

Dᑍ

D QWDOQP

Dᑍ

D QWDPDN

Dᑍ

D QWDPT

Dᑍ

D QWDSCS

Dᑍ

D QWDES

Dᑍ

D QWDMLS

Dᑍ

D QWDMLL

Dᑍ

D QWDMLT

Dᑍ

D QWDLCLP

Dᑍ

D QWDIMR

Dᑍ

D QWDDRA

Dᑍ

D QWDTSEP

Dᑍ

D QWDAC

Dᑍ

D QWDRD

Dᑍ

D QWDTD

Dᑍ

D QWDERVEDðð

Dᑍ

D QWDOILL

Dᑍ

Job Description Name

Job Description Lib Name

User Name

Job Date

Job Switches

Job Queue Name

Job Queue Lib Name

Job Queue Priority

Hold Job Queue

Output Queue Name

Output Queue Lib Name

Output Queue Priority

Printer Device Name

Print Text

1ð6

1ð7

1ð9

119

149

153

157

161

162

172

182

192

2ð5

215

23ð

31ð

36ð

361

365

1ð8

118

148

152B ð

156B ð

16ðB ð

161

Syntax Check Severity

End Severity

Message Log Severity

Message Log Level

Message Log Text

Log CL Programs

171

181

191

Inquiry Message Reply

Device Recovery Action

Time Slice End Pool

Accounting Code

2ð4

214

229

3ð9

Routing Data

359

Text Description

Reserved

36ð

364B ð .19/

368B ð .2ð/

Offset Initial Lib List

Number Libs In Lib list

D QWDNLILL

Dᑍ

Appendix B. Original Examples in Additional Languages B-31

Download from Www.Somanuals.com. All Manuals Search And Download.

D QWDORD

369

373

377

381

391

372B ð

376B ð

38ðB ð

39ð

Dᑍ

Offset Request Data

D QWDLRD

Dᑍ

Length Request Data

D QWDJMQMS

Dᑍ

Job Message Queue Max Size

Job Msg Queue Full Action

D QWDJMQFA

Dᑍ

DᑍQWDRSV2

391

Dᑍ

Varying length

4ð2

DᑍQWDILL

392

4ð3

DIM(ðððð1)

Dᑍ

Varying length

DᑍQWDRDðð

4ð3

Dᑍ

Varying length

Dᑍ Command string data structure

Dᑍ

DCMD_STRING

1ð

INZ('SNDMSG MSG(''LIBRARY - ')

INZ(''') TOUSR(QPGMR)')

D LIBRARY

Dᑍ

Dᑍ Miscellaneous data structure

Dᑍ

DRCVLEN

DFORMAT

DLENSTR

Cᑍ

9B ð INZ(%SIZE(QWDDð1ðð))

INZ('JOBDð1ðð')

15 5 INZ(%SIZE(CMD_STRING))

Cᑍ Beginning of mainline

Cᑍ

Cᑍ Two parameters are being passed into this program

Cᑍ

ᑍENTRY

PLIST

PARM

JOBD

JOBD_LIB

1ð

Cᑍ

Cᑍ Move the two parameters passed into LFNAM

Cᑍ

JOBD

CAT

JOBD_LIB

LFNAM

2ð

Cᑍ

Cᑍ Error Code Bytes Provided is set to 16

Cᑍ

EVAL

QUSBPRV = %SIZE(QUSEC)

Cᑍ

Cᑍ Call the API.

Cᑍ

CALL

PARM

QWDRJOBD

QWDDð1ðð

RCVLEN

FORMAT

LFNAM

QUSEC

Cᑍ

Cᑍ Test for an error on the API call

Cᑍ

B-32 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Cᑍ

QUSBAVL > ð

Cᑍ If there was an error, exit to ERROR subroutine

Cᑍ

EXSR

ELSE

ERROR

Cᑍ

Cᑍ Else, add 1 to the Initial library list offset because RPG

Cᑍ is a Base 1 language

Cᑍ

QWDOILL

ADD

5 ð

QWDNLILL

EVAL

LIBRARY = %SUBST(QWDDð1ðð:X:1ð)

Cᑍ

Cᑍ Let's tell everyone what the library value is

Cᑍ

CALL

PARM

ADD

'QCMDEXC'

CMD_STRING

LENSTR

(X + 1ð) > RCVLEN

LEAVE

ENDIF

ENDDO

ENDIF

Cᑍ

EVAL

RETURN

ᑍINLR = '1'

Cᑍ

Cᑍ End of MAINLINE

Cᑍ

Cᑍ Subroutine to handle errors returned in the error code parameter

Cᑍ

ERROR

BEGSR

Cᑍ Process errors returned from the API. As this sample program

Cᑍ used /COPY to include the error code structure, only the first

Cᑍ 16 bytes of the error code structure are available. If the

Cᑍ application program needed to access the variable length

Cᑍ exception data for the error, the developer should physically

Cᑍ copy the QSYSINC include and modify the copied include to

Cᑍ define additional storage for the exception data.

Cᑍ

ENDSR

Using Keys with List Spooled Files API—ILE C Example

Refer to “Using Keys with List Spooled Files API—Example” on page 3-24 for the

original example.

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ

ᑍ/

/ᑍ Program:

List Spooled Files for Current User

ILE C

/ᑍ

/ᑍ Language:

/ᑍ

/ᑍ Description: This example shows the steps necessary to

/ᑍ process keyed output from an API

Appendix B. Original Examples in Additional Languages B-33

Download from Www.Somanuals.com. All Manuals Search And Download.

/ᑍ

ᑍ/

/ᑍ APIs Used:

QUSLSPL - List Spooled Files

/ᑍ

QUSCRTUS - Create User Space

QUSPTRUS - Retrieve Pointer to User Space

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

#include <stdio.h>

#include <string.h>

#include <quslspl.h>

#include <quscrtus.h>

#include <qusptrus.h>

#include <qusgen.h>

#include <qusec.h>

#include <qliept.h>

/ᑍ QUSLSPL API header

/ᑍ QUSCRTUS API header

/ᑍ QUSPTRUS API header

ᑍ/

/ᑍ Format Structures for User Space .11/ ᑍ/

/ᑍ Error Code parameter include for APIs ᑍ/

/ᑍ Entry Point Table include for APIs

ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ Global variables ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

char

int

char

int

spc_name[2ð] = "SPCNAME QTEMP

spc_size = 2ððð;

spc_init = ðxðð;

ᑍspcptr, ᑍlstptr, ᑍlstptr2;

pages;

struct keys { int key1;

int key2;

.7/

.8/

int key3;} keys = {2ð1, 211, 216};

number_of_keys = 3;

ext_attr[1ð] = "QUSLSPL ";

spc_aut[1ð] = "ᑍALL

spc_text[5ð] = "

spc_replac[1ð] = "ᑍYES

spc_domain[1ð] = "ᑍUSER

format[8] = "SPLFð2ðð";

usr_prf[1ð] = "ᑍCURRENT ";

outq[2ð] = "ᑍALL

int

char

.4/

formtyp[1ð] = "ᑍALL

usrdta[1ð] = "ᑍALL

jobnam[26] = "

prtfil[1ð];

opndat[7];

typedef struct {

Qus_LSPL_Key_Info_t Key_Info;

char

} var_record_t;

Data_Field[1ðð];

Qus_EC_t error_code;

int

i, j;

char

FILE

prtlin[1ðð];

ᑍrecord;

main()

{

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ Open print file for report

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

ᑍ/

if((record = fopen("QPRINT", "wb, lrecl=132, type=record")) == NULL)

{ printf("File QPRINT could not be opened\n");

B-34 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

exit();

}

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ Set Error Code structure to use exceptions ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

error_code.Bytes_Provided = ð;

.1/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ Create a User Space for the List generated by QUSLSPL ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

QUSCRTUS(spc_name,

ext_attr,

/ᑍ User space name and library .2/ ᑍ/

/ᑍ Extended attribute

/ᑍ Initial space size

/ᑍ Initialize value for space

/ᑍ Public authorization

/ᑍ Text description

ᑍ/

spc_size,

&spc_init,

spc_aut,

spc_text,

spc_replac,

error_code,

spc_domain);

/ᑍ Replace option

/ᑍ Error code structure

/ᑍ Domain of space

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ Call QUSLSPL to get all spooled files for ᑍCURRENT user ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

QUSLSPL( spc_name,

format,

/ᑍ User space name and library .3/ ᑍ/

/ᑍ API format

/ᑍ User profile

/ᑍ Output Queue

/ᑍ Form type

.4/

ᑍ/

usr_prf,

outq,

formtyp,

usrdta,

error_code,

jobnam,

keys,

/ᑍ User data

/ᑍ Error code structure

/ᑍ Job name

/ᑍ Keys to return

.5/

.6/

number_of_keys); /ᑍ Number of keys

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ Get a resolved pointer to the User Space ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

QUSPTRUS(spc_name,

&spcptr,

/ᑍ User space name and library .9/ ᑍ/

/ᑍ Space pointer

ᑍ/

error_code);

/ᑍ Error code structure

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ If valid information returned

ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

if(memcmp\

(((Qus_Generic_Header_ð1ðð_t ᑍ)spcptr)->Structure_Release_Level, .12/

"ð1ðð", 4) != ð) { printf("Unknown Generic Header"); .13/

exit();

}

if((((Qus_Generic_Header_ð1ðð_t ᑍ)spcptr)->Information_Status=='C')\ .14/

|| (((Qus_Generic_Header_ð1ðð_t ᑍ)spcptr)->Information_Status\

== 'P'))

Appendix B. Original Examples in Additional Languages B-35

Download from Www.Somanuals.com. All Manuals Search And Download.

{

if(((Qus_Generic_Header_ð1ðð_t ᑍ)spcptr)->Number_List_Entries\ .16/

> ð)

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ address current list entry

ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

{

lstptr = spcptr + (((Qus_Generic_Header_ð1ðð_t ᑍ)spcptr)\

->Offset_List_Data);

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ process all the entries

ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

for(i = ð; i < (((Qus_Generic_Header_ð1ðð_t ᑍ)spcptr)\ .2ð/

->Number_List_Entries); i++)

{

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ set lstptr2 to first variable length record for this entry ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

lstptr2 = lstptr + 4;

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ process all the variable length records for this entry

ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

for(j = ð; j < (((Qus_SPLFð2ðð_t ᑍ)lstptr)\ .22/.23/

->Num_Fields_Retd); j++)

{

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ extract spooled file name for report

ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

if((((Qus_LSPL_Key_Info_t ᑍ)lstptr2)\ .24/.25/

->Key_Field_for_Field_Retd) == 2ð1)

{ memcpy(prtfil, "

", 1ð);

memcpy(prtfil, (((var_record_t ᑍ)\

lstptr2)->Data_Field),

(((Qus_LSPL_Key_Info_t ᑍ)lstptr2)\

->Data_Length));

}

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ extract number of pages for report

ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

if((((Qus_LSPL_Key_Info_t ᑍ)lstptr2)\ .24/.25/

->Key_Field_for_Field_Retd) == 211)

{ memcpy(&pages, (((var_record_t ᑍ)\

lstptr2)->Data_Field),

(((Qus_LSPL_Key_Info_t ᑍ)lstptr2)\

->Data_Length));

}

B-36 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ extract age of spooled file for report

ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

if((((Qus_LSPL_Key_Info_t ᑍ)lstptr2)\ .24/.25/

->Key_Field_for_Field_Retd) == 216)

{ memcpy(opndat, "

", 7);

memcpy(opndat, (((var_record_t ᑍ)\

lstptr2)->Data_Field),

(((Qus_LSPL_Key_Info_t ᑍ)lstptr2)\

->Data_Length));

}

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ bump lstptr2 to next variable length record

ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

lstptr2 = lstptr2 +

(((Qus_LSPL_Key_Info_t ᑍ)lstptr2)\

->Len_Field_Info_Retd);

}

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ print collected information

ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

sprintf(prtlin, "%.1ðs

%.1ðd

%.7s", .26/

prtfil, pages, opndat);

fwrite(prtlin, 1, 1ðð, record);

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ bump lstptr to next list entry

ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

lstptr += (((Qus_Generic_Header_ð1ðð_t ᑍ)spcptr)\ .27/

->Size_Each_Entry);

}

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ exit at end of list

ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

fclose(record);

exit();

}

else

{ printf("List data not valid");

.15/

.28/

exit();

}

Appendix B. Original Examples in Additional Languages B-37

Download from Www.Somanuals.com. All Manuals Search And Download.

Using Keys with List Spooled Files API—ILE COBOL Example

Refer to “Using Keys with List Spooled Files API—Example” on page 3-24 for the

original example. The following program also works for OPM COBOL.

IDENTIFICATION DIVISION.

ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

ᑍ

ᑍ Program:

List Spooled Files for Current User

ᑍ

ᑍ Language:

ᑍ

ILE COBOL

ᑍ Description: This example shows the steps necessary to

ᑍ

process keyed output from an API.

ᑍ APIs Used:

QUSLSPL - List Spooled Files

QUSCRTUS - Create User Space

QUSPTRUS - Retrieve Pointer to User Space

ᑍ

ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

ᑍ

PROGRAM-ID. LSTSPL.

ENVIRONMENT DIVISION.

CONFIGURATION SECTION.

SOURCE-COMPUTER. IBM-AS4ðð.

OBJECT-COMPUTER. IBM-AS4ðð.

INPUT-OUTPUT SECTION.

FILE-CONTROL.

SELECT LISTING ASSIGN TO PRINTER-QPRINT

ORGANIZATION IS SEQUENTIAL.

DATA DIVISION.

FILE SECTION.

FD LISTING RECORD CONTAINS 132 CHARACTERS

LABEL RECORDS ARE STANDARD

DATA RECORD IS LIST-LINE.

ð1 LIST-LINE

PIC X(132).

ᑍ

WORKING-STORAGE SECTION.

ᑍ Error Code parameter include. As this sample program

ᑍ uses COPY to include the error code structure, only the first

ᑍ 16 bytes of the error code structure are available. If the

ᑍ application program needs to access the variable length

ᑍ exception data for the error, the developer should physically

ᑍ copy the QSYSINC include and modify the copied include to

ᑍ define additional storage for the exception data.

ᑍ

COPY QUSEC OF QSYSINC-QLBLSRC.

ᑍ

ᑍ Listing text

ᑍ

ð1 PRTLIN.

ð5 PRTFIL

ð5 FILLER

ð5 PAGES

ð5 FILLER

PIC X(1ð).

PIC X(ð5).

PIC S9(ð9).

PIC X(ð5).

B-38 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

ð5 OPNDAT

ð1 LSTERR.

ð5 TEXT1

ð1 HDRERR.

ð5 TEXT2

PIC X(ð7).

PIC X(22) VALUE "List data not valid".

PIC X(22) VALUE "Unknown Generic Header".

ᑍ

ð1 MISC.

ð5 SPC-NAME

PIC X(2ð) VALUE "SPCNAME QTEMP

PIC S9(ð9) VALUE 2ððð BINARY. .2/

PIC X(ð1) VALUE X"ðð".

POINTER.

ð5 SPC-SIZE

ð5 SPC-INIT

ð5 SPCPTR

ð5 SPC-TYPE

ð5 EXT-ATTR

ð5 SPC-AUT

ð5 SPC-TEXT

ð5 SPC-REPLAC

ð5 SPC-DOMAIN

PIC X(1ð) VALUE "ᑍUSRSPC".

PIC X(1ð) VALUE "QUSLSPL ". .3/

PIC X(1ð) VALUE "ᑍALL".

PIC X(5ð).

PIC X(1ð) VALUE "ᑍYES".

PIC X(1ð) VALUE "ᑍUSER".

ð5 LST-FORMAT-NAME PIC X(ð8) VALUE "SPLFð2ðð". .4/

ð5 USR-PRF

ð5 OUTQ

ð5 FORMTYP

ð5 USRDTA

ð5 JOBNAM

PIC X(1ð) VALUE "ᑍCURRENT ".

PIC X(2ð) VALUE "ᑍALL".

PIC X(1ð) VALUE "ᑍALL".

PIC X(26).

ð1 KEYS.

.7/

ð5 KEY1

ð5 KEY2

ð5 KEY3

PIC S9(ð9) BINARY VALUE 2ð1. .8/

PIC S9(ð9) BINARY VALUE 216.

PIC S9(ð9) BINARY VALUE 211.

PIC S9(ð9) BINARY VALUE 3.

ð1 NUMBER-OF-KEYS

ð1 MISC2.

ð5 PAGESA

ð5 PAGESN

PIC X(ð4).

REDEFINES PAGESA

PIC S9(ð9) BINARY.

ᑍ

LINKAGE SECTION.

ᑍ String to map User Space offsets into

ᑍ

ð1 STRING-SPACE

PIC X(32ððð).

ᑍ

ᑍ User Space Generic Header include. These includes will be

ᑍ mapped over a User Space.

ᑍ

COPY QUSGEN OF QSYSINC-QLBLSRC.

.11/

ᑍ

ᑍ List Spool Files API include. These includes will be

ᑍ mapped over a User Space. The include is copied into the

ᑍ source so that we can define the variable length portion

ᑍ of QUS-LSPL-KEY-INFO.

ᑍ

ð1 QUS-LSPL-KEY-INFO.

ð5 LEN-FIELD-INFO-RETD

ð5 KEY-FIELD-FOR-FIELD-RETD

ð5 TYPE-OF-DATA

PIC S9(ðððð9) BINARY.

PIC X(ðððð1).

ð5 RESERV3

PIC X(ðððð3).

ð5 DATA-LENGTH

ð5 DATA-FIELD

PIC S9(ðððð9) BINARY.

PIC X(ðð1ðð).

ᑍ

Varying length

Appendix B. Original Examples in Additional Languages B-39

Download from Www.Somanuals.com. All Manuals Search And Download.

ᑍ

ð5 RESERVED

PIC X(ðððð1).

Varying length

ð1 QUS-SPLFð2ðð.

ð5 NUM-FIELDS-RETD

ð5 KEY-INFO.

PIC S9(ðððð9) BINARY.

ð9 LEN-FIELD-INFO-RETD

PIC S9(ðððð9) BINARY.

PIC X(ðððð1).

ð9 KEY-FIELD-FOR-FIELD-RETD

ð9 TYPE-OF-DATA

ð9 RESERV3

PIC X(ðððð3).

ð9 DATA-LENGTH

ð9 DATA-FIELD

ð9 RESERVED

PIC S9(ðððð9) BINARY.

PIC X(ðððð1).

ᑍ

Varying length

ᑍ Beginning of mainline

ᑍ

PROCEDURE DIVISION.

MAIN-LINE.

ᑍ

ᑍ Open LISTING file

ᑍ

OPEN OUTPUT LISTING.

ᑍ

ᑍ Set Error Code structure to use exceptions

ᑍ

MOVE ð TO BYTES-PROVIDED OF QUS-EC.

ᑍ

.1/

ᑍ Create a User Space for the List generated by QUSLSPL

ᑍ

CALL "QUSCRTUS" USING SPC-NAME, EXT-ATTR, SPC-SIZE, .2/

SPC-INIT, SPC-AUT, SPC-TEXT,

SPC-REPLAC, QUS-EC, SPC-DOMAIN

ᑍ

ᑍ Call QUSLSPL to get all spooled files for ᑍCURRENT user

ᑍ

CALL "QUSLSPL" USING SPC-NAME, LST-FORMAT-NAME, USR-PRF, .3/.4/

OUTQ, FORMTYP, USRDTA, QUS-EC,

JOBNAM, KEYS, NUMBER-OF-KEYS. .5/.6/

ᑍ

ᑍ Get a resolved pointer to the User Space for performance

ᑍ

CALL "QUSPTRUS" USING SPC-NAME, SPCPTR, QUS-EC.

.9/

ᑍ

ᑍ If valid information was returned

ᑍ

SET ADDRESS OF QUS-GENERIC-HEADER-ð1ðð TO SPCPTR.

IF STRUCTURE-RELEASE-LEVEL OF QUS-GENERIC-HEADER-ð1ðð .12/

NOT EQUAL "ð1ðð" WRITE LIST-LINE FROM HDRERR, .13/

STOP RUN.

IF (INFORMATION-STATUS OF QUS-GENERIC-HEADER-ð1ðð = "C" .14/

OR INFORMATION-STATUS OF QUS-GENERIC-HEADER-ð1ðð = "P")

AND NUMBER-LIST-ENTRIES OF QUS-GENERIC-HEADER-ð1ðð > ð .16/

ᑍ

B-40 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

ᑍ address current list entry

ᑍ

SET ADDRESS OF STRING-SPACE TO SPCPTR,

SET ADDRESS OF QUS-SPLFð2ðð TO

ADDRESS OF STRING-SPACE((OFFSET-LIST-DATA

OF QUS-GENERIC-HEADER-ð1ðð + 1):1),

.18/

ᑍ

ᑍ and process all of the entries

ᑍ

PERFORM PROCES

NUMBER-LIST-ENTRIES OF QUS-GENERIC-HEADER-ð1ðð TIMES, .2ð/

ELSE

WRITE LIST-LINE FROM LSTERR.

STOP RUN.

.15/

.28/

ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

PROCES.

ᑍ

ᑍ address the first variable length record for this entry

ᑍ

SET ADDRESS OF QUS-LSPL-KEY-INFO TO ADDRESS OF

QUS-SPLFð2ðð(5:).

ᑍ

ᑍ process all variable length records associated with this entry

ᑍ

PERFORM PROCES2 NUM-FIELDS-RETD TIMES. .22/.23/

WRITE LIST-LINE FROM PRTLIN.

.26/

ᑍ

ᑍ after each entry, increment to the next entry

ᑍ

SET ADDRESS OF STRING-SPACE TO ADDRESS OF QUS-SPLFð2ðð. .27/

SET ADDRESS OF QUS-SPLFð2ðð TO ADDRESS OF STRING-SPACE

((SIZE-EACH-ENTRY OF QUS-GENERIC-HEADER-ð1ðð + 1):1).

ᑍ

ᑍ Process each variable length record based on key

ᑍ

PROCES2.

ᑍ

ᑍ extract spooled file name for report

ᑍ

IF KEY-FIELD-FOR-FIELD-RETD OF QUS-LSPL-KEY-INFO = 2ð1 .24/.25/

MOVE SPACES TO PRTFIL,

MOVE DATA-FIELD OF QUS-LSPL-KEY-INFO(

1:DATA-LENGTH OF QUS-LSPL-KEY-INFO)

TO PRTFIL.

ᑍ

ᑍ extract number of pages for report

ᑍ

IF KEY-FIELD-FOR-FIELD-RETD OF QUS-LSPL-KEY-INFO = 211 .24/.25/

MOVE DATA-FIELD OF QUS-LSPL-KEY-INFO(

1:DATA-LENGTH OF QUS-LSPL-KEY-INFO)

TO PAGESA,

MOVE PAGESN TO PAGES.

ᑍ

Appendix B. Original Examples in Additional Languages B-41

Download from Www.Somanuals.com. All Manuals Search And Download.

ᑍ extract age of spooled file for report

ᑍ

IF KEY-FIELD-FOR-FIELD-RETD OF QUS-LSPL-KEY-INFO = 216 .24/.25/

MOVE SPACES TO OPNDAT,

MOVE DATA-FIELD OF QUS-LSPL-KEY-INFO(

1:DATA-LENGTH OF QUS-LSPL-KEY-INFO)

TO OPNDAT.

ᑍ

ᑍ address next variable length entry

ᑍ

SET ADDRESS OF STRING-SPACE TO ADDRESS OF QUS-LSPL-KEY-INFO.

SET ADDRESS OF QUS-LSPL-KEY-INFO TO ADDRESS OF

STRING-SPACE(

LEN-FIELD-INFO-RETD OF QUS-LSPL-KEY-INFO + 1:1).

Using Keys with List Spooled Files API—ILE RPG Example

Refer to “Using Keys with List Spooled Files API—Example” on page 3-24 for the

original example.

Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Fᑍ

Fᑍ Program:

List Spooled Files for Current User

Fᑍ

Fᑍ Language:

Fᑍ

ILE RPG

Fᑍ Description: This example shows the steps necessary to

Fᑍ

process keyed output from an API.

Fᑍ APIs Used:

QUSLSPL - List Spooled Files

QUSCRTUS - Create User Space

QUSPTRUS - Retrieve Pointer to User Space

Fᑍ

Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Fᑍ

FQPRINT

Dᑍ

F 132

PRINTER OFLIND(ᑍINOF)

Dᑍ Error Code parameter include

Dᑍ

D/COPY QSYSINC/QRPGLESRC,QUSEC

Dᑍ

.11/

DSPC_NAME

DSPC_SIZE

DSPC_INIT

DLSTPTR

DLSTPTR2

DSPCPTR

DARR

2ð

INZ('SPCNAME QTEMP

.2/

9B ð INZ(2ððð)

INZ(X'ðð')

ᑍ

BASED(LSTPTR) DIM(32767)

DPAGES#

DPAGESA

DKEYS

4B ð

.7/

.8/

9B ð INZ(2ð1)

9B ð INZ(216)

9B ð INZ(211)

B-42 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

DKEY#

9B ð INZ(3)

Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Dᑍ

Dᑍ The following QUSGEN include from QSYSINC is copied into .11/

Dᑍ this program so that it can be declared as BASED on SPCPTR

Dᑍ

Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

DQUSHð1ðð

Dᑍ

D QUSUA

Dᑍ

D QUSSGH

Dᑍ

D QUSSRL

Dᑍ

D QUSFN

Dᑍ

D QUSAU

Dᑍ

D QUSDTC

Dᑍ

D QUSIS

Dᑍ

D QUSSUS

Dᑍ

D QUSOIP

Dᑍ

D QUSSIP

Dᑍ

D QUSOHS

Dᑍ

D QUSSHS

Dᑍ

D QUSOLD

Dᑍ

D QUSSLD

Dᑍ

D QUSNBRLE

Dᑍ

D QUSSEE

Dᑍ

D QUSSIDLE

Dᑍ

D QUSCID

Dᑍ

D QUSLID

Dᑍ

D QUSSLI

Dᑍ

D QUSERVEDðð

Dᑍ

BASED(SPCPTR)

Qus Generic Header ð1ðð

User Area

68B ð

Size Generic Header

Structure Release Level

Format Name

8ð

9ð

API Used

1ð3

Date Time Created

Information Status

Size User Space

Offset Input Parameter

Size Input Parameter

Offset Header Section

Size Header Section

Offset List Data

Size List Data

1ð4

1ð5

1ð9

113

117

121

125

129

133

137

141

145

147

15ð

151

1ð4

1ð8B ð

112B ð

116B ð

12ðB ð

124B ð

128B ð

132B ð

136B ð

14ðB ð

144B ð

146

Number List Entries

Size Each Entry

CCSID List Ent

Country ID

149

Language ID

15ð

Subset List Indicator

192

Reserved

Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Dᑍ

Dᑍ The following QUSLSPL include from QSYSINC is copied into

Dᑍ this program so that it can be declared as BASED

Dᑍ

Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Appendix B. Original Examples in Additional Languages B-43

Download from Www.Somanuals.com. All Manuals Search And Download.

DᑍPrototype for calling List Spooled File API QUSLSPL

Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

D QUSLSPL

'QUSLSPL'

Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

DᑍType definition for the SPLFð2ðð format.

Dᑍᑍᑍᑍᑍᑍᑍ

DᑍNOTE: The following type definition only defines the fixed

Dᑍ portion of the format. Any varying length field will

Dᑍ have to be defined by the user.

Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

DQUSSPLKI

1ðð

BASED(LSTPTR2)

Qus LSPL Key Info

Dᑍ

D QUSLFIRð2

4B ð

Dᑍ

Len Field Info Retd

Key Field for Field Retd

Type of Data

D QUSKFFFRðð

8B ð

Dᑍ

D QUSTODð2

Dᑍ

D QUSR3ðð

1ð

Dᑍ

Reserv3

D QUSDLð2

Dᑍ

16B ð

Data Length

DᑍQUSDATAð8

Dᑍ

DᑍQUSERVED34

Dᑍ

DQUSFð2ðð

Dᑍ

D QUSNBRFRðð

Dᑍ

DᑍQUSKIðð

Dᑍ QUSLFIRð3

Dᑍ QUSKFFFRð1

Dᑍ QUSTODð3

Dᑍ QUSR3ð1

Dᑍ QUSDLð3

Dᑍ QUSDATAð9

Dᑍ QUSERVED35

Dᑍ

Varying length

BASED(LSTPTR)

Qus SPLFð2ðð

4B ð

Num Fields Retd

8B ð

12B ð

2ðB ð

Dᑍ

Cᑍ

Varying length

Cᑍ Start of mainline

Cᑍ

Cᑍ Set Error Code structure to use exceptions

Cᑍ

Z-ADD

QUSBPRV

.1/

Cᑍ Create a User Space for the List generated by QUSLSPL

Cᑍ

CALL

PARM

'QUSCRTUS'

.2/

SPC_NAME

'QUSLSPL ' EXT_ATTR

SPC_SIZE

1ð

SPC_INIT

SPC_AUT

'ᑍALL'

B-44 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

PARM

ᑍBLANKS

'ᑍYES'

SPC_TEXT

SPC_REPLAC

QUSEC

5ð

1ð

Cᑍ

'ᑍUSER'

SPC_DOMAIN

1ð

Cᑍ Call QUSLSPL to get all spooled files for ᑍCURRENT user

Cᑍ

CALL

PARM

'QUSLSPL'

.3/

SPC_NAME

FORMAT

USR_PRF

OUTQ

FORMTYP

USRDTA

QUSEC

JOBNAM

KEYS

KEY#

'SPLFð2ðð'

'ᑍCURRENT'

'ᑍALL'

8 .4/

1ð

2ð

1ð

.5/

.6/

Cᑍ Get a resolved pointer to the User Space for performance

Cᑍ

CALL

PARM

'QUSPTRUS'

.9/

SPC_NAME

SPCPTR

QUSEC

Cᑍ

Cᑍ If valid information was returned

Cᑍ

QUSSRL

QUSIS

IFEQ

OREQ

'ð1ðð'

'C'

'P'

.12/

.14/

Cᑍ

Cᑍ and list entries were found

Cᑍ

QUSNBRLE

IFGT

.16/

Cᑍ

Cᑍ set LSTPTR to the first byte of the User Space

Cᑍ

EVAL

LSTPTR = SPCPTR

Cᑍ increment LSTPTR to the first List entry

Cᑍ

EVAL

LSTPTR = %ADDR(ARR(QUSOLD + 1)) .18/

Cᑍ and process all of the entries

Cᑍ

QUSNBRLE

.2ð/

Cᑍ

Cᑍ set LSTPTR2 to the first variable length record for this entry

Cᑍ

Z-ADD

EVAL

9 ð

LSTPTR2 = %ADDR(ARR(X)) .22/

Cᑍ

QUSNBRFRðð

.23/

Cᑍ process the data based on key type

Cᑍ

QUSKFFFRðð

CASEQ

2ð1

211

FILNAM

PAGES

.24/

Appendix B. Original Examples in Additional Languages B-45

Download from Www.Somanuals.com. All Manuals Search And Download.

QUSKFFFRðð

CASEQ

CAS

END

216

AGE

ERROR

Cᑍ

Cᑍ increment LSTPTR2 to next variable length record

Cᑍ

ADD

EVAL

END

QUSLFIRð2

LSTPTR2 = %ADDR(ARR(X))

Cᑍ

EXCEPT

PRTLIN .26/

Cᑍ after each entry, increment LSTPTR to the next entry

Cᑍ

EVAL

END

LSTPTR = %ADDR(ARR(QUSSEE + 1)) .27/

END

ELSE

EXCEPT

END

ELSE

EXCEPT

END

LSTERR

HDRERR

.15/

.13/

Cᑍ

Cᑍ Exit the program

Cᑍ

EVAL

ᑍINLR = '1'

.28/

RETURN

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Cᑍ

FILNAM

BEGSR

ᑍBLANKS

PRTFIL

1ð

Cᑍ extract number of pages for report

Cᑍ

EVAL

PAGESA = %SUBST(QUSSPLKI:17:QUSDLð2) .25/

ENDSR

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Cᑍ

AGE

BEGSR

Cᑍ extract age of spooled file for report

Cᑍ

MOVE

EVAL

ENDSR

ᑍBLANKS

OPNDAT

OPNDAT = %SUBST(QUSSPLKI:17:QUSDLð2) .25/

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

ERROR

QUSKFFFRðð

BEGSR

DSPLY

EVAL

ᑍINLR = '1'

RETURN

ENDSR

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

OQPRINT PRTLIN

B-46 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

PRTFIL

PAGES#

OPNDAT

LSTERR

1ð

4ð

OQPRINT

22 'List data not valid'

OQPRINT

HDRERR

22 'Unknown Generic Header'

Integrated Language Environment (ILE) APIs—Examples

This section includes the examples in Chapter 4, “Common Information across

APIs—Advanced (ILE) Example.”

Refer to “Register Exit Point and Add Exit Program—ILE C Example” on page 4-9

for the original example.

IDENTIFICATION DIVISION.

ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

ᑍ

ᑍ Program:

Add an Exit Program

ᑍ

ᑍ Language:

ᑍ

OPM COBOL

ᑍ Description: This program registers an exit point with the

ᑍ

registration facility. After the successful

completion of the registration of the exit point,

an exit program is added to the exit point.

ᑍ

ᑍ APIs Used:

ᑍ

QUSRGPT - Register Exit Point

QUSADDEP - Add Exit Program

ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

ᑍ

ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

PROGRAM-ID. REGFAC1.

ENVIRONMENT DIVISION.

CONFIGURATION SECTION.

SOURCE-COMPUTER. IBM-AS4ðð.

OBJECT-COMPUTER. IBM-AS4ðð.

INPUT-OUTPUT SECTION.

FILE-CONTROL.

SELECT LISTING ASSIGN TO PRINTER-QPRINT

ORGANIZATION IS SEQUENTIAL.

DATA DIVISION.

FILE SECTION.

FD LISTING RECORD CONTAINS 132 CHARACTERS

LABEL RECORDS ARE STANDARD

DATA RECORD IS LIST-LINE.

ð1 LIST-LINE

PIC X(132).

WORKING-STORAGE SECTION.

ᑍ

ᑍ Keyed Variable Length Record includes

ᑍ

COPY QUS OF QSYSINC-QLBLSRC.

Appendix B. Original Examples in Additional Languages B-47

Download from Www.Somanuals.com. All Manuals Search And Download.

ᑍ

ᑍ Error Code parameter include. As this sample program

ᑍ uses COPY to include the error code structure, only the first

ᑍ 16 bytes of the error code structure are available. If the

ᑍ application program needs to access the variable length

ᑍ exception data for the error, the developer should physically

ᑍ copy the QSYSINC include and modify the copied include to

ᑍ define additional storage for the exception data.

ᑍ

COPY QUSEC OF QSYSINC-QLBLSRC.

ᑍ

ᑍ Error message text

ᑍ

ð1 BAD-REG.

ð5 TEXT1

PIC X(39)

VALUE "Attempt to register exit point failed: ".

ð5 EXCEPTION-ID PIC X(ð7).

ð1 BAD-ADD.

ð5 TEXT1

PIC X(36)

VALUE "Attempt to add exit program failed: ".

ð5 EXCEPTION-ID PIC X(ð7).

ᑍ

ᑍ Miscellaneous elements

ᑍ

ð1 VARREC.

ð5 NBR-RECORDS PIC S9(ð9) BINARY.

ð5 VAR-RECORDS PIC X(1ððð).

ð1 MISC.

ð5 VAR-OFFSET

PIC S9(ð9) VALUE 1.

ð5 BINARY-NUMBER PIC S9(ð9) BINARY.

ð5 BINARY-CHAR REDEFINES BINARY-NUMBER PIC X(ð4).

ð5 X

PIC S9(ð9) BINARY.

ð5 EXIT-POINT-NAME PIC X(2ð) VALUE "EXAMPLE_EXIT_POINT".

ð5 EXIT-PGM

PIC X(2ð) VALUE "EXAMPLEPGMEXAMPLELIB".

PIC S9(ð9) VALUE 1 BINARY.

ð5 EXIT-PGM-NBR

ð5 EXIT-PGM-DATA PIC X(25)

VALUE "EXAMPLE EXIT PROGRAM DATA".

PIC X(ð8) VALUE "EXMPð1ðð".

ð5 FORMAT-NAME

ᑍ

ᑍ Beginning of mainline

ᑍ

PROCEDURE DIVISION.

MAIN-LINE.

ᑍ

ᑍ Register the exit point with the registration facility. If the

ᑍ registration of the exit point is successful, add an exit

ᑍ program to the exit point.

ᑍ

ᑍ Initialize the error code parameter. To signal exceptions to

ᑍ this program by the API, you need to set the bytes provided

ᑍ field of the error code to zero. Because this program has

ᑍ exceptions sent back through the error code parameter, it sets

ᑍ the bytes provided field to the number of bytes it gives the

ᑍ API for the parameter.

ᑍ

MOVE 16 TO BYTES-PROVIDED.

ᑍ

ᑍ Set the exit point controls. Each control field is passed to

B-48 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

ᑍ the API using a variable length record. Each record must

ᑍ start on a 4-byte boundary.

ᑍ

ᑍ Set the total number of controls that are being specified on

ᑍ the call. This program lets the API take the default for the

ᑍ controls that are not specified.

ᑍ

MOVE 2 TO NBR-RECORDS.

ᑍ

ᑍ Set the values for the two controls that are specified:

ᑍ Maximum number of exit programs = 1ð

ᑍ Exit point description = 'EXIT POINT EXAMPLE'

ᑍ

MOVE 3 TO CONTROL-KEY OF QUS-VLEN-REC-4.

MOVE 4 TO LENGTH-DATA OF QUS-VLEN-REC-4.

MOVE 1ð TO BINARY-NUMBER.

MOVE BINARY-CHAR TO VAR-RECORDS((VAR-OFFSET + 12):4).

PERFORM CALCULATE-NEXT-OFFSET.

MOVE 8 TO CONTROL-KEY OF QUS-VLEN-REC-4.

MOVE 5ð TO LENGTH-DATA OF QUS-VLEN-REC-4.

MOVE "EXIT POINT EXAMPLE"

TO VAR-RECORDS((VAR-OFFSET + 12):5ð).

PERFORM CALCULATE-NEXT-OFFSET.

Cᑍ

Cᑍ Call the API to add the exit point.

Cᑍ

CALL "QUSRGPT" USING EXIT-POINT-NAME OF MISC,

FORMAT-NAME OF MISC,

VARREC, QUS-EC.

Cᑍ

Cᑍ If an exception occurs, the API returns the exception in the

Cᑍ error code parameter. The bytes available field is set to

Cᑍ zero if no exception occurs and greater than zero if an

Cᑍ exception does occur.

Cᑍ

IF BYTES-AVAILABLE OF QUS-EC > ð

OPEN OUTPUT LISTING,

MOVE EXCEPTION-ID OF QUS-EC

TO EXCEPTION-ID OF BAD-REG,

WRITE LIST-LINE FROM BAD-REG,

STOP RUN.

ᑍ

ᑍ If the call to register an exit point is successful, add

ᑍ an exit program to the exit point.

ᑍ

ᑍ Set the total number of exit program attributes that are being

ᑍ specified on the call. This program lets the API take the

ᑍ default for the attributes that are not specified. Each

ᑍ attribute record must be 4-byte aligned.

ᑍ

MOVE 2 TO NBR-RECORDS.

MOVE 1 TO VAR-OFFSET.

ᑍ

ᑍ Set the values for the two attributes that are being specified:

ᑍ Replace exit program

= 1

ᑍ Exit program data CCSID = 37

ᑍ

MOVE 4 TO CONTROL-KEY OF QUS-VLEN-REC-4.

Appendix B. Original Examples in Additional Languages B-49

Download from Www.Somanuals.com. All Manuals Search And Download.

MOVE 1 TO LENGTH-DATA OF QUS-VLEN-REC-4.

MOVE 1 TO VAR-RECORDS((VAR-OFFSET + 12):1).

PERFORM CALCULATE-NEXT-OFFSET.

MOVE 3 TO CONTROL-KEY OF QUS-VLEN-REC-4.

MOVE 4 TO LENGTH-DATA OF QUS-VLEN-REC-4.

MOVE 37 TO BINARY-NUMBER.

MOVE BINARY-CHAR TO VAR-RECORDS((VAR-OFFSET + 12):4).

PERFORM CALCULATE-NEXT-OFFSET.

ᑍ

ᑍ Call the API to register the exit program.

ᑍ

CALL "QUSADDEP" USING EXIT-POINT-NAME OF MISC,

FORMAT-NAME OF MISC,

EXIT-PGM-NBR OF MISC,

EXIT-PGM OF MISC,

EXIT-PGM-DATA OF MISC,

BY CONTENT LENGTH OF EXIT-PGM-DATA OF MISC,

VARREC, QUS-EC.

ᑍ

ᑍ If an exception occurs, the API returns the exception in the

ᑍ error code parameter. The bytes available field is set to

ᑍ zero if no exception occurs and greater than zero if an

ᑍ exception does occur.

ᑍ

IF BYTES-AVAILABLE OF QUS-EC > ð

OPEN OUTPUT LISTING,

MOVE EXCEPTION-ID OF QUS-EC

TO EXCEPTION-ID OF BAD-ADD,

WRITE LIST-LINE FROM BAD-ADD,

STOP RUN.

ᑍ

STOP RUN.

ᑍ

ᑍ End of MAINLINE

ᑍ

ᑍ Calculate 4-byte aligned offset for next variable length record

ᑍ

CALCULATE-NEXT-OFFSET.

COMPUTE BINARY-NUMBER = LENGTH-DATA OF QUS-VLEN-REC-4 + 12.

DIVIDE BINARY-NUMBER BY 4 GIVING BINARY-NUMBER REMAINDER X.

IF X = ð COMPUTE LENGTH-VLEN-RECORD OF QUS-VLEN-REC-4 =

LENGTH-DATA OF QUS-VLEN-REC-4 + 12

ELSE COMPUTE LENGTH-VLEN-RECORD OF QUS-VLEN-REC-4 =

LENGTH-DATA OF QUS-VLEN-REC-4 + 12 +

( 4 - X ).

MOVE QUS-VLEN-REC-4 TO VAR-RECORDS(VAR-OFFSET:12).

COMPUTE VAR-OFFSET = VAR-OFFSET + LENGTH-VLEN-RECORD OF

QUS-VLEN-REC-4.

Refer to “Register Exit Point and Add Exit Program—ILE C Example” on page 4-9

for the original example.

B-50 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

IDENTIFICATION DIVISION.

ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

ᑍ

ᑍ Program:

Add an Exit Program

ᑍ

ᑍ Language:

ᑍ

ILE COBOL

ᑍ Description: This program registers an exit point with the

ᑍ

registration facility. After the successful

completion of the registration of the exit point,

an exit program is added to the exit point.

ᑍ

ᑍ APIs Used:

ᑍ

QusRegisterExitPoint - Register Exit Point

QusAddExitProgram - Add Exit Program

ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

ᑍ

ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

PROGRAM-ID. REGFAC1.

ENVIRONMENT DIVISION.

CONFIGURATION SECTION.

SOURCE-COMPUTER. IBM-AS4ðð.

OBJECT-COMPUTER. IBM-AS4ðð.

INPUT-OUTPUT SECTION.

FILE-CONTROL.

SELECT LISTING ASSIGN TO PRINTER-QPRINT

ORGANIZATION IS SEQUENTIAL.

DATA DIVISION.

FILE SECTION.

FD LISTING RECORD CONTAINS 132 CHARACTERS

LABEL RECORDS ARE STANDARD

DATA RECORD IS LIST-LINE.

ð1 LIST-LINE

PIC X(132).

WORKING-STORAGE SECTION.

ᑍ

ᑍ Keyed Variable Length Record includes

ᑍ

COPY QUS OF QSYSINC-QLBLSRC.

ᑍ

ᑍ Error Code parameter include. As this sample program

ᑍ uses COPY to include the error code structure, only the first

ᑍ 16 bytes of the error code structure are available. If the

ᑍ application program needs to access the variable length

ᑍ exception data for the error, the developer should physically

ᑍ copy the QSYSINC include and modify the copied include to

ᑍ define additional storage for the exception data.

ᑍ

COPY QUSEC OF QSYSINC-QLBLSRC.

ᑍ

ᑍ Error message text

ᑍ

ð1 BAD-REG.

ð5 TEXT1

PIC X(39)

VALUE "Attempt to register exit point failed: ".

ð5 EXCEPTION-ID PIC X(ð7).

ð1 BAD-ADD.

Appendix B. Original Examples in Additional Languages B-51

Download from Www.Somanuals.com. All Manuals Search And Download.

ð5 TEXT1

PIC X(36)

VALUE "Attempt to add exit program failed: ".

ð5 EXCEPTION-ID PIC X(ð7).

ᑍ

ᑍ Miscellaneous elements

ᑍ

ð1 VARREC.

ð5 NBR-RECORDS PIC S9(ð9) BINARY.

ð5 VAR-RECORDS PIC X(1ððð).

ð1 MISC.

ð5 VAR-OFFSET

PIC S9(ð9) VALUE 1.

ð5 BINARY-NUMBER PIC S9(ð9) BINARY.

ð5 BINARY-CHAR REDEFINES BINARY-NUMBER PIC X(ð4).

ð5 X

PIC S9(ð9) BINARY.

ð5 EXIT-POINT-NAME PIC X(2ð) VALUE "EXAMPLE_EXIT_POINT".

ð5 EXIT-PGM

PIC X(2ð) VALUE "EXAMPLEPGMEXAMPLELIB".

PIC S9(ð9) VALUE 1 BINARY.

ð5 EXIT-PGM-NBR

ð5 EXIT-PGM-DATA PIC X(25)

VALUE "EXAMPLE EXIT PROGRAM DATA".

PIC X(ð8) VALUE "EXMPð1ðð".

ð5 FORMAT-NAME

ᑍ

ᑍ Beginning of mainline

ᑍ

PROCEDURE DIVISION.

MAIN-LINE.

ᑍ

ᑍ Register the exit point with the registration facility. If the

ᑍ registration of the exit point is successful, add an exit

ᑍ program to the exit point.

ᑍ

ᑍ Initialize the error code parameter. To signal exceptions to

ᑍ this program by the API, you need to set the bytes provided

ᑍ field of the error code to zero. Because this program has

ᑍ exceptions sent back through the error code parameter, it sets

ᑍ the bytes provided field to the number of bytes it gives the

ᑍ API for the parameter.

ᑍ

MOVE 16 TO BYTES-PROVIDED.

ᑍ

ᑍ Set the exit point controls. Each control field is passed to

ᑍ the API using a variable length record. Each record must

ᑍ start on a 4-byte boundary.

ᑍ

ᑍ Set the total number of controls that are being specified on

ᑍ the call. This program lets the API take the default for the

ᑍ controls that are not specified.

ᑍ

MOVE 2 TO NBR-RECORDS.

ᑍ

ᑍ Set the values for the two controls that are specified:

ᑍ Maximum number of exit programs = 1ð

ᑍ Exit point description = 'EXIT POINT EXAMPLE'

ᑍ

MOVE 3 TO CONTROL-KEY OF QUS-VLEN-REC-4.

MOVE 4 TO LENGTH-DATA OF QUS-VLEN-REC-4.

MOVE 1ð TO BINARY-NUMBER.

MOVE BINARY-CHAR TO VAR-RECORDS((VAR-OFFSET + 12):4).

PERFORM CALCULATE-NEXT-OFFSET.

B-52 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

MOVE 8 TO CONTROL-KEY OF QUS-VLEN-REC-4.

MOVE 5ð TO LENGTH-DATA OF QUS-VLEN-REC-4.

MOVE "EXIT POINT EXAMPLE"

TO VAR-RECORDS((VAR-OFFSET + 12):5ð).

PERFORM CALCULATE-NEXT-OFFSET.

ᑍ

ᑍ Call the API to add the exit point.

ᑍ

CALL PROCEDURE "QusRegisterExitPoint" USING

EXIT-POINT-NAME OF MISC,

FORMAT-NAME OF MISC,

VARREC, QUS-EC.

ᑍ

ᑍ If an exception occurs, the API returns the exception in the

ᑍ error code parameter. The bytes available field is set to

ᑍ zero if no exception occurs and greater than zero if an

ᑍ exception does occur.

ᑍ

IF BYTES-AVAILABLE OF QUS-EC > ð

OPEN OUTPUT LISTING,

MOVE EXCEPTION-ID OF QUS-EC

TO EXCEPTION-ID OF BAD-REG,

WRITE LIST-LINE FROM BAD-REG,

STOP RUN.

ᑍ

ᑍ If the call to register an exit point is successful, add

ᑍ an exit program to the exit point.

ᑍ

ᑍ Set the total number of exit program attributes that are being

ᑍ specified on the call. This program lets the API take the

ᑍ default for the attributes that are not specified. Each

ᑍ attribute record must be 4-byte aligned.

ᑍ

MOVE 2 TO NBR-RECORDS.

MOVE 1 TO VAR-OFFSET.

ᑍ

ᑍ Set the values for the two attributes that are being specified:

ᑍ Replace exit program

= 1

ᑍ Exit program data CCSID = 37

ᑍ

MOVE 4 TO CONTROL-KEY OF QUS-VLEN-REC-4.

MOVE 1 TO LENGTH-DATA OF QUS-VLEN-REC-4.

MOVE 1 TO VAR-RECORDS((VAR-OFFSET + 12):1).

PERFORM CALCULATE-NEXT-OFFSET.

MOVE 3 TO CONTROL-KEY OF QUS-VLEN-REC-4.

MOVE 4 TO LENGTH-DATA OF QUS-VLEN-REC-4.

MOVE 37 TO BINARY-NUMBER.

MOVE BINARY-CHAR TO VAR-RECORDS((VAR-OFFSET + 12):4).

PERFORM CALCULATE-NEXT-OFFSET.

ᑍ

ᑍ Call the API to register the exit program.

ᑍ

CALL PROCEDURE "QusAddExitProgram" USING

EXIT-POINT-NAME OF MISC,

FORMAT-NAME OF MISC,

EXIT-PGM-NBR OF MISC,

EXIT-PGM OF MISC,

EXIT-PGM-DATA OF MISC,

Appendix B. Original Examples in Additional Languages B-53

Download from Www.Somanuals.com. All Manuals Search And Download.

BY CONTENT LENGTH OF EXIT-PGM-DATA OF MISC,

VARREC, QUS-EC.

ᑍ

ᑍ If an exception occurs, the API returns the exception in the

ᑍ error code parameter. The bytes available field is set to

ᑍ zero if no exception occurs and greater than zero if an

ᑍ exception does occur.

ᑍ

IF BYTES-AVAILABLE OF QUS-EC > ð

OPEN OUTPUT LISTING,

MOVE EXCEPTION-ID OF QUS-EC

TO EXCEPTION-ID OF BAD-ADD,

WRITE LIST-LINE FROM BAD-ADD,

STOP RUN.

ᑍ

STOP RUN.

ᑍ

ᑍ End of MAINLINE

ᑍ

ᑍ Calculate 4-byte aligned offset for next variable length record

ᑍ

CALCULATE-NEXT-OFFSET.

COMPUTE BINARY-NUMBER = LENGTH-DATA OF QUS-VLEN-REC-4 + 12.

DIVIDE BINARY-NUMBER BY 4 GIVING BINARY-NUMBER REMAINDER X.

IF X = ð COMPUTE LENGTH-VLEN-RECORD OF QUS-VLEN-REC-4 =

LENGTH-DATA OF QUS-VLEN-REC-4 + 12

ELSE COMPUTE LENGTH-VLEN-RECORD OF QUS-VLEN-REC-4 =

LENGTH-DATA OF QUS-VLEN-REC-4 + 12 +

( 4 - X ).

MOVE QUS-VLEN-REC-4 TO VAR-RECORDS(VAR-OFFSET:12).

COMPUTE VAR-OFFSET = VAR-OFFSET + LENGTH-VLEN-RECORD OF

QUS-VLEN-REC-4.

Refer to “Register Exit Point and Add Exit Program—ILE C Example” on page 4-9

for the original example.

Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Fᑍ

Fᑍ Program:

Add an Exit Program

Fᑍ

Fᑍ Language:

Fᑍ

OPM RPG

Fᑍ Description: This program registers an exit point with the

Fᑍ

registration facility. After the successful

completion of the registration of the exit point,

an exit program is added to the exit point.

Fᑍ

Fᑍ APIs Used:

QUSRGPT - Register Exit Point

QUSADDEP - Add Exit Program

Fᑍ

Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Fᑍ

B-54 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

FQPRINT O F

132

PRINTER

1ððð 1

Eᑍ COMPILE TIME ARRAY

Iᑍ

REC

Iᑍ Keyed Variable Length Record includes

Iᑍ

I/COPY QSYSINC/QRPGSRC,QUS

Iᑍ

Iᑍ Error Code parameter include. As this sample program

Iᑍ uses /COPY to include the error code structure, only the first

Iᑍ 16 bytes of the error code structure are available. If the

Iᑍ application program needs to access the variable length

Iᑍ exception data for the error, the developer should physically

Iᑍ copy the QSYSINC include and modify the copied include to

Iᑍ define additional storage for the exception data.

Iᑍ

I/COPY QSYSINC/QRPGSRC,QUSEC

Iᑍ

Iᑍ Miscellaneous data

Iᑍ

IVARREC

1ðð8

I I

Iᑍ

B 1 4ðNBRREC

51ðð4 REC

B1ðð51ðð8ðVO

IOVRLAY

B 1 4ðBINARY

1 4 BINC

Iᑍ

I I

'EXAMPLE_EXIT_POINT '

1 2ð EPNTNM

'EXAMPLEPGMEXAMPLELIB' 21 4ð EPGM

'EXAMPLE EXIT PROGRAM- 41 65 EPGMDT

' DATA'

I I

Cᑍ

'EXAMPLE POINT EXAMPL- 66 115 EPTXT

'E'

B 68 71ðEPGMSZ

Cᑍ Beginning of mainline

Cᑍ

Cᑍ Register the exit point with the registration facility. If the

Cᑍ registration of the exit point is successful, add an exit

Cᑍ program to the exit point.

Cᑍ

Cᑍ Initialize the error code parameter. To signal exceptions to

Cᑍ this program by the API, you need to set the bytes provided

Cᑍ field of the error code to zero. Because this program has

Cᑍ exceptions sent back through the error code parameter, it sets

Cᑍ the bytes provided field to the number of bytes it gives the

Cᑍ API for the parameter.

Cᑍ

Z-ADD16

QUSBNB

Cᑍ

Cᑍ Set the exit point controls. Each control field is passed to

Cᑍ the API using a variable length record. Each record must

Cᑍ start on a 4-byte boundary.

Cᑍ

Cᑍ Set the total number of controls that are being specified on

Appendix B. Original Examples in Additional Languages B-55

Download from Www.Somanuals.com. All Manuals Search And Download.

Cᑍ the call. This program lets the API take the default for the

Cᑍ controls that are not specified.

Cᑍ

Z-ADD2

NBRREC

Cᑍ

Cᑍ Set the values for the two controls that are specified:

Cᑍ Maximum number of exit programs = 1ð

Cᑍ Exit point description = 'EXIT POINT EXAMPLE'

Cᑍ

Z-ADD3

QUSBCC

QUSBCD

BINARY

Z-ADD4

Z-ADD1ð

ADD VO

MOVEABINC

EXSR CALCVO

Z-ADD8

Z-ADD5ð

ADD VO

MOVEAEPTXT

EXSR CALCVO

5ð

REC,OF

QUSBCC

QUSBCD

REC,OF

Cᑍ Call the API to register the exit point.

Cᑍ

CALL 'QUSRGPT'

PARM

PARM 'EXMPð1ðð'FORMAT 8

PARM

EPNTNM

VARREC

QUSBN

Cᑍ

Cᑍ If an exception occurs, the API returns the exception in the

Cᑍ error code parameter. The bytes available field is set to

Cᑍ zero if no exception occurs and greater than zero if an

Cᑍ exception does occur.

Cᑍ

QUSBNC

IFGT ð

OPEN QPRINT

EXCPTERREPT

EXSR DONE

ENDIF

Cᑍ

Cᑍ If the call to register an exit point is successful, add

Cᑍ an exit program to the exit point.

Cᑍ

Cᑍ Set the total number of exit program attributes that are being

Cᑍ specified on the call. This program lets the API take the

Cᑍ default for the attributes that are not specified. Each

Cᑍ attribute record must be 4-byte aligned.

Cᑍ

Z-ADD2

Z-ADD1

NBRREC

Cᑍ

Cᑍ Set the values for the two attributes that are being specified:

Cᑍ Replace exit program

= 1

Cᑍ Exit program data CCSID = 37

Cᑍ

Z-ADD4

Z-ADD1

ADD VO

QUSBCC

QUSBCD

5ð

B-56 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

MOVE '1'

EXSR CALCVO

Z-ADD3

REC,OF

QUSBCC

QUSBCD

BINARY

Z-ADD4

Z-ADD37

ADD VO

MOVEABINC

EXSR CALCVO

5ð

REC,OF

Cᑍ

Cᑍ Call the API to add the exit program.

Cᑍ

CALL 'QUSADDEP'

PARM

EPNTNM

PARM 'EXMPð1ðð'FORMAT

PARM 1

PARM

BINARY

EPGM

EPGMDT

EPGMSZ

VARREC

QUSBN

Cᑍ If an exception occurs, the API returns the exception in the

Cᑍ error code parameter. The bytes available field is set to

Cᑍ zero if no exception occurs and greater than zero if an

Cᑍ exception does occur.

Cᑍ

QUSBNC

IFGT ð

OPEN QPRINT

EXCPTERRPGM

EXSR DONE

ENDIF

EXSR DONE

Cᑍ

Cᑍ End of MAINLINE

Cᑍ

Cᑍ Return to programs caller

DONE

BEGSR

SETON

RETRN

ENDSR

Cᑍ

Cᑍ Calculate 4-byte aligned offset for next variable length record

Cᑍ

CALCVO

QUSBCD

BEGSR

ADD 12

DIV 4

MVR

IFEQ ð

ADD 12

ELSE

SUB BINARY

ADD QUSBCD

ADD 12

END

MOVEAQUSBC

ADD QUSBCB

ENDSR

BINARY

QUSBCD

QUSBCB

REC,VO

Appendix B. Original Examples in Additional Languages B-57

Download from Www.Somanuals.com. All Manuals Search And Download.

Oᑍ

OQPRINT E 1ð6

ERREPT

'Attempt to register exit'

' point failed: '

QUSBND

ERRPGM

OQPRINT E 1ð6

'Attempt to add an exit'

' program failed: '

QUSBND

Refer to “Register Exit Point and Add Exit Program—ILE C Example” on page 4-9

for the original example.

Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Fᑍ

Fᑍ Program:

Add an Exit Program

Fᑍ

Fᑍ Language:

Fᑍ

ILE RPG

Fᑍ Description: This program registers an exit point with the

Fᑍ

registration facility. After the successful

completion of the registration of the exit point,

an exit program is added to the exit point.

Fᑍ

Fᑍ APIs Used:

QusRegisterExitPoint - Register Exit Point

Fᑍ

QusAddExitProgram

- Add Exit Program

Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Fᑍ

FQPRINT

Dᑍ

F 132

PRINTER OFLIND(ᑍINOF) USROPN

Dᑍ Keyed Variable Length Record includes

Dᑍ

D/COPY QSYSINC/QRPGLESRC,QUS

Dᑍ

Dᑍ Error Code parameter include. As this sample program

Dᑍ uses /COPY to include the error code structure, only the first

Dᑍ 16 bytes of the error code structure are available. If the

Dᑍ application program needs to access the variable length

Dᑍ exception data for the error, the developer should physically

Dᑍ copy the QSYSINC include and modify the copied include to

Dᑍ define additional storage for the exception data.

Dᑍ

D/COPY QSYSINC/QRPGLESRC,QUSEC

Dᑍ

Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

DᑍPrototype for calling Register Exit Point API.

Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

D QUSREPð5

'QusRegisterExitPoint'

Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

DᑍPrototype for calling Add Exit Program API.

Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

D QUSAEPGM

'QusAddExitProgram'

B-58 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Dᑍ

Dᑍ Miscellaneous data

Dᑍ

DVARREC

D NBR_RECS

D RECS

DV_OFFSET

Dᑍ

DOVERLAYS

D BINARY

D BINARY_C

Dᑍ

9B ð

1ððð

9 ð INZ(1)

9B ð

OVERLAY(BINARY)

DEPNTNAME

DEPGM

DEPGMDTA

DEPGMDTA_SZ

Cᑍ

2ð

INZ('EXAMPLE_EXIT_POINT')

INZ('EXAMPLEPGMEXAMPLELIB')

INZ('EXAMPLE EXIT PROGRAM DATA')

9B ð INZ(%SIZE(EPGMDTA))

Cᑍ Beginning of mainline

Cᑍ

Cᑍ Register the exit point with the registration facility. If the

Cᑍ registration of the exit point is successful, add an exit

Cᑍ program to the exit point.

Cᑍ

Cᑍ Initialize the error code parameter. To signal exceptions to

Cᑍ this program by the API, you need to set the bytes provided

Cᑍ field of the error code to zero. Because this program has

Cᑍ exceptions sent back through the error code parameter, it sets

Cᑍ the bytes provided field to the number of bytes it gives the

Cᑍ API for the parameter.

Cᑍ

EVAL

QUSBPRV = %SIZE(QUSEC)

Cᑍ

Cᑍ Set the exit point controls. Each control field is passed to

Cᑍ the API using a variable length record. Each record must

Cᑍ start on a 4-byte boundary.

Cᑍ

Cᑍ Set the total number of controls that are being specified on

Cᑍ the call. This program lets the API take the default for the

Cᑍ controls that are not specified.

Cᑍ

EVAL

NBR_RECS = 2

Cᑍ

Cᑍ Set the values for the two controls that are specified:

Cᑍ Maximum number of exit programs = 1ð

Cᑍ Exit point description = 'EXIT POINT EXAMPLE'

Cᑍ

EVAL

EXSR

EVAL

QUSCK = 3

QUSLD = 4

BINARY = 1ð

%SUBST(RECS:V_OFFSET+12) = BINARY_C

CALC_VOFF

QUSCK = 8

QUSLD = 5ð

%SUBST(RECS:V_OFFSET+12:5ð) = 'EXIT +

POINT EXAMPLE'

EXSR

CALC_VOFF

Cᑍ Call the API to register the exit point.

Appendix B. Original Examples in Additional Languages B-59

Download from Www.Somanuals.com. All Manuals Search And Download.

Cᑍ

CALLB

PARM

QUSREPð5

EPNTNAME

FORMAT

VARREC

QUSEC

'EXMPð1ðð'

Cᑍ

Cᑍ If an exception occurs, the API returns the exception in the

Cᑍ error code parameter. The bytes available field is set to

Cᑍ zero if no exception occurs and greater than zero if an

Cᑍ exception does occur.

Cᑍ

QUSBAVL > ð

QPRINT

ERRAEPNT

DONE

OPEN

EXCEPT

EXSR

ENDIF

Cᑍ

Cᑍ If the call to register an exit point is successful, add

Cᑍ an exit program to the exit point.

Cᑍ

Cᑍ Set the total number of exit program attributes that are being

Cᑍ specified on the call. This program lets the API take the

Cᑍ default for the attributes that are not specified. Each

Cᑍ attribute record must be 4-byte aligned.

Cᑍ

EVAL

NBR_RECS = 2

V_OFFSET = 1

Cᑍ

Cᑍ Set the values for the two attributes that are being specified:

Cᑍ Replace exit program

= 1

Cᑍ Exit program data CCSID = 37

Cᑍ

EVAL

EXSR

EVAL

EXSR

QUSCK = 4

QUSLD = 1

%SUBST(RECS:V_OFFSET+12) = '1'

CALC_VOFF

QUSCK = 3

QUSLD = 4

BINARY = 37

%SUBST(RECS:V_OFFSET+12) = BINARY_C

CALC_VOFF

Cᑍ Call the API to add the exit program.

Cᑍ

CALLB

PARM

QUSAEPGM

EPNTNAME

FORMAT

BINARY

EPGM

EPGMDTA

EPGMDTA_SZ

VARREC

QUSEC

'EXMPð1ðð'

Cᑍ If an exception occurs, the API returns the exception in the

Cᑍ error code parameter. The bytes available field is set to

Cᑍ zero if no exception occurs and greater than zero if an

B-60 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Cᑍ exception does occur.

Cᑍ

QUSBAVL > ð

QPRINT

ERRAEPGM

DONE

OPEN

EXCEPT

EXSR

ENDIF

EXSR

DONE

Cᑍ

Cᑍ End of MAINLINE

Cᑍ

Cᑍ Return to programs caller

DONE

BEGSR

EVAL

RETURN

ENDSR

ᑍINLR = '1'

Cᑍ

Cᑍ Calculate 4-byte aligned offset for next variable length record

Cᑍ

Oᑍ

CALC_VOFF

BEGSR

EVAL

DIV

BINARY = QUSLD + 12

BINARY

MVR

BINARY = ð

EVAL

ELSE

EVAL

END

QUSLVRðð = (QUSLD + 12)

QUSLVRðð = (QUSLD + 12 + (4 - BINARY))

EVAL

ENDSR

%SUBST(RECS:V_OFFSET:12) = QUSVR4

V_OFFSET = V_OFFSET + QUSLVRðð

OQPRINT

ERRAEPNT

1 6

'Attempt to register exit -

point failed: '

QUSEI

ERRAEPGM

OQPRINT

'Attempt to add exit -

program failed: '

QUSEI

Retrieve Exit Point and Exit Program Information—OPM COBOL

Example

Refer to “Retrieve Exit Point and Exit Program Information—ILE C Example” on

page 4-13 for the original example.

IDENTIFICATION DIVISION.

ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

ᑍ

ᑍ Program:

Retrieve Exit Point and Exit Program Information

ᑍ

ᑍ Language:

ᑍ

OPM COBOL

ᑍ Description: This program retrieves exit point and exit

ᑍ

program information. After retrieving the

Appendix B. Original Examples in Additional Languages B-61

Download from Www.Somanuals.com. All Manuals Search And Download.

ᑍ

exit point information, the program calls each

exit program.

ᑍ

ᑍ APIs Used:

QUSCRTUS - Create User Space

ᑍ

QUSPTRUS - Retrieve Pointer to User Space

QUSRTVEI - Retrieve Exit Information

ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

ᑍ

PROGRAM-ID. REGFAC2.

ENVIRONMENT DIVISION.

CONFIGURATION SECTION.

SOURCE-COMPUTER. IBM-AS4ðð.

OBJECT-COMPUTER. IBM-AS4ðð.

INPUT-OUTPUT SECTION.

FILE-CONTROL.

SELECT LISTING ASSIGN TO PRINTER-QPRINT

ORGANIZATION IS SEQUENTIAL.

DATA DIVISION.

FILE SECTION.

FD LISTING RECORD CONTAINS 132 CHARACTERS

LABEL RECORDS ARE STANDARD

DATA RECORD IS LIST-LINE.

ð1 LIST-LINE

PIC X(132).

WORKING-STORAGE SECTION.

ᑍ

ᑍ Error Code parameter include. As this sample program

ᑍ uses COPY to include the error code structure, only the first

ᑍ 16 bytes of the error code structure are available. If the

ᑍ application program needs to access the variable length

ᑍ exception data for the error, the developer should physically

ᑍ copy the QSYSINC include and modify the copied include to

ᑍ define additional storage for the exception data.

ᑍ

COPY QUSEC OF QSYSINC-QLBLSRC.

ᑍ

ᑍ Error message text

ᑍ

ð1 BAD-EXIT-POINT.

ð5 TEXT1

PIC X(4ð)

VALUE "Attempt to retrieve information failed: ".

ð5 EXCEPTION-ID PIC X(ð7).

ð1 BAD-EXIT-PGM.

ð5 TEXT1

PIC X(42)

VALUE "Attempt to retrieve Exit Programs failed: ".

ð5 EXCEPTION-ID PIC X(ð7).

ð1 BAD-CREATE.

ð5 TEXT1

PIC X(37)

VALUE "Allocation of RCVVAR storage failed: ".

ð5 EXCEPTION-ID PIC X(ð7).

ᑍ

ᑍ Miscellaneous elements

ᑍ

ð1 MISC.

ð5 EXIT-POINT-NAME PIC X(2ð) VALUE "EXAMPLE_EXIT_POINT".

ð5 EXIT-PGM-NBR

PIC S9(ð9) VALUE -1 BINARY.

ð5 EXIT-PARAMETERS PIC X(1ð).

B-62 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

ð5 FORMAT-NAME

PIC X(ð8) VALUE "EXTIð1ðð".

ð5 FORMAT-NAME-1 PIC X(ð8) VALUE "EXTIð2ðð".

ð5 FORMAT-NAME-2 PIC X(ð8) VALUE "EXMPð1ðð".

ð5 NBR-OF-SELECT-CRITERIA PIC S9(ð9) VALUE ð BINARY.

ð5 CONTINUATION-HDL PIC X(16).

ð5 BASE-POINTER

ð5 INFO-POINTER

ð5 SPACE-NAME

ð5 SPACE-ATTR

ð5 SPACE-SIZE

ð5 SPACE-VALUE

ð5 SPACE-AUTH

ð5 SPACE-TEXT

POINTER.

PIC X(2ð) VALUE "RCVVAR

PIC X(1ð).

PIC S9(ð9) VALUE 35ðð BINARY.

PIC X(ð1) VALUE X"ðð".

PIC X(1ð) VALUE "ᑍUSE".

PIC X(5ð).

QTEMP

ð5 SPACE-REPLACE PIC X(1ð) VALUE "ᑍNO".

ð5 SPACE-DOMAIN PIC X(1ð) VALUE "ᑍUSER".

ᑍ

LINKAGE SECTION.

ᑍ Variable to hold results of QUSRTVEI. The storage for this

ᑍ variable will be allocated by way of a User Space.

ᑍ

ð1 RCVVAR

PIC X(35ðð).

ᑍ

ᑍ Registration Facility API include. These includes will be

ᑍ mapped over the RCVVAR (User Space) previously defined.

ᑍ

COPY QUSREG OF QSYSINC-QLBLSRC.

ᑍ

ᑍ Beginning of mainline

ᑍ

PROCEDURE DIVISION.

MAIN-LINE.

ᑍ

ᑍ Retrieve the exit point information first. If the current

ᑍ number of exit programs is not zero, retrieve the exit

ᑍ programs. It is not necessary to call for the exit point

ᑍ information to determine if the exit point has any exit

ᑍ programs. It is done here for illustrative purposes only.

ᑍ You can make one call to the API for the exit program

ᑍ information and check the number of exit program entries

ᑍ returned field to see if there are any exit programs to call.

ᑍ

ᑍ Initialize the error code to inform the API that all

ᑍ exceptions should be returned through the error code parameter.

ᑍ

MOVE 16 TO BYTES-PROVIDED OF QUS-EC.

ᑍ

ᑍ Create a User Space for RCVVAR.

ᑍ

CALL "QUSCRTUS" USING SPACE-NAME, SPACE-ATTR, SPACE-SIZE,

SPACE-VALUE, SPACE-AUTH, SPACE-TEXT,

SPACE-REPLACE, QUS-EC, SPACE-DOMAIN.

ᑍ

ᑍ If an exception occurs, the API returns the exception in the

ᑍ error code parameter. The bytes available field is set to

ᑍ zero if no exception occurs and greater than zero if an

ᑍ exception does occur.

ᑍ

Appendix B. Original Examples in Additional Languages B-63

Download from Www.Somanuals.com. All Manuals Search And Download.

IF BYTES-AVAILABLE OF QUS-EC > ð

IF EXCEPTION-ID OF QUS-EC = "CPF987ð"

CONTINUE

ELSE

OPEN OUTPUT LISTING,

MOVE EXCEPTION-ID OF QUS-EC

TO EXCEPTION-ID OF BAD-CREATE,

WRITE LIST-LINE FROM BAD-CREATE,

STOP RUN.

ᑍ

ᑍ Assign BASE-POINTER to address RCVVAR

ᑍ

CALL "QUSPTRUS" USING SPACE-NAME, BASE-POINTER, QUS-EC.

ᑍ

ᑍ If an exception occurs, the API returns the exception in the

ᑍ error code parameter. The bytes available field is set to

ᑍ zero if no exception occurs and greater than zero if an

ᑍ exception does occur.

ᑍ

IF BYTES-AVAILABLE OF QUS-EC > ð

OPEN OUTPUT LISTING,

MOVE EXCEPTION-ID OF QUS-EC

TO EXCEPTION-ID OF BAD-CREATE,

WRITE LIST-LINE FROM BAD-CREATE,

STOP RUN.

ᑍ

SET ADDRESS OF RCVVAR TO BASE-POINTER.

ᑍ

ᑍ Blank out the continuation handle to let the API know that this

ᑍ is a first attempt at the retrieve operation.

ᑍ

MOVE SPACES TO CONTINUATION-HDL.

ᑍ

ᑍ Call the API to retrieve the exit programs

ᑍ

CALL "QUSRTVEI" USING CONTINUATION-HDL, RCVVAR,

BY CONTENT LENGTH OF RCVVAR,

FORMAT-NAME OF MISC,

EXIT-POINT-NAME OF MISC,

FORMAT-NAME-2, EXIT-PGM-NBR,

NBR-OF-SELECT-CRITERIA, QUS-EC.

ᑍ

ᑍ If an exception occurs, the API returns the exception in the

ᑍ error code parameter. The bytes available field is set to

ᑍ zero if no exception occurs and greater than zero if an

ᑍ exception does occur.

ᑍ

IF BYTES-AVAILABLE OF QUS-EC > ð

OPEN OUTPUT LISTING,

MOVE EXCEPTION-ID OF QUS-EC

TO EXCEPTION-ID OF BAD-EXIT-POINT,

WRITE LIST-LINE FROM BAD-EXIT-POINT,

STOP RUN.

ᑍ

ᑍ If the call to retrieve exit point information is successful,

ᑍ check to see if there are any exit programs to call.

ᑍ

SET ADDRESS OF QUS-EXTIð1ðð TO BASE-POINTER.

B-64 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

SET ADDRESS OF QUS-EXTIð2ðð TO BASE-POINTER.

ᑍ

IF NUMBER-POINTS-RETURNED OF QUS-EXTIð1ðð > ð

SET ADDRESS OF QUS-EXTIð1ðð-ENTRY TO

ADDRESS OF RCVVAR((OFFSET-EXIT-POINT-ENTRY OF

QUS-EXTIð1ðð + 1):)

ELSE STOP RUN.

ᑍ

IF NUMBER-EXIT-PROGRAMS OF QUS-EXTIð1ðð-ENTRY > ð

ᑍ There are some exit programs to call. Blank out the continuation

ᑍ handle to let the API know that this is a first attempt at the

ᑍ retrieve operation.

ᑍ

MOVE SPACES TO CONTINUATION-HDL,

ᑍ

ᑍ Call the exit programs

ᑍ

PERFORM CALL-EXIT-PROGRAMS,

ᑍ

ᑍ If the continuation handle field in the receiver variable is

ᑍ not set to blanks, the API has more information to return than

ᑍ what could fit in the receiver variable. Call the API for

ᑍ more exit programs to call.

ᑍ

PERFORM UNTIL CONTINUE-HANDLE OF QUS-EXTIð2ðð = SPACES

MOVE CONTINUE-HANDLE OF QUS-EXTIð2ðð

TO CONTINUATION-HDL,

PERFORM CALL-EXIT-PROGRAMS,

END-PERFORM.

ᑍ

STOP RUN.

ᑍ

ᑍ End of MAINLINE

ᑍ

ᑍ Process exit programs in receiver variable

ᑍ

CALL-EXIT-PROGRAMS.

ᑍ

ᑍ Call the API to retrieve the exit program information

ᑍ

CALL "QUSRTVEI" USING CONTINUATION-HDL, RCVVAR,

BY CONTENT LENGTH OF RCVVAR,

FORMAT-NAME-1,

EXIT-POINT-NAME OF MISC,

FORMAT-NAME-2, EXIT-PGM-NBR,

NBR-OF-SELECT-CRITERIA, QUS-EC.

ᑍ

ᑍ If an exception occurs, the API returns the exception in the

ᑍ error code parameter. The bytes available field is set to

ᑍ zero if no exception occurs and greater than zero if an

ᑍ exception does occur.

ᑍ

IF BYTES-AVAILABLE OF QUS-EC > ð

OPEN OUTPUT LISTING,

MOVE EXCEPTION-ID OF QUS-EC

TO EXCEPTION-ID OF BAD-EXIT-PGM,

Appendix B. Original Examples in Additional Languages B-65

Download from Www.Somanuals.com. All Manuals Search And Download.

WRITE LIST-LINE FROM BAD-EXIT-PGM,

STOP RUN.

ᑍ

ᑍ If the call to retrieve exit program information is successful,

ᑍ check to see if there are any exit programs to call.

ᑍ

ᑍ The receiver variable offers enough room for a minimum of one

ᑍ exit program entry because the receiver variable was declared

ᑍ as 35ðð bytes. Therefore, this example only checks the

ᑍ number of exit programs returned field. If the receiver

ᑍ variable were not large enough to hold at least one entry,

ᑍ the bytes available field would need to be checked as well as

ᑍ the number of exit programs returned field. If the number of

ᑍ exit programs returned field is set to zero and the bytes

ᑍ available field is greater than the bytes returned field, the

ᑍ API had at least one exit program entry to return but was

ᑍ unable to because the receiver variable was too small.

ᑍ

SET ADDRESS OF QUS-EXTIð2ðð-ENTRY

TO ADDRESS OF RCVVAR(OFFSET-PROGRAM-ENTRY

OF QUS-EXTIð2ðð + 1:).

PERFORM CALL-PGMS

NUMBER-PROGRAMS-RETURNED OF QUS-EXTIð2ðð TIMES.

ᑍ

CALL-PGMS.

ᑍ

ᑍ Call the exit program while ignoring failures on the call

ᑍ

CALL PROGRAM-NAME OF QUS-EXTIð2ðð-ENTRY USING

EXIT-PARAMETERS

ON EXCEPTION CONTINUE.

ᑍ

ᑍ Address the next exit program entry

ᑍ

SET ADDRESS OF QUS-EXTIð2ðð-ENTRY

TO ADDRESS OF RCVVAR(OFFSET-NEXT-ENTRY

OF QUS-EXTIð2ðð-ENTRY + 1:).

Retrieve Exit Point and Exit Program Information—ILE COBOL

Example

Refer to “Retrieve Exit Point and Exit Program Information—ILE C Example” on

page 4-13 for the original example.

IDENTIFICATION DIVISION.

ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

ᑍ

ᑍ Program:

Retrieve Exit Point and Exit Program Information

ᑍ

ᑍ Language:

ᑍ

ILE COBOL

ᑍ Description: This program retrieves exit point and exit

ᑍ

program information. After retrieving the

exit point information, the program calls each

exit program.

ᑍ

ᑍ APIs Used:

QUSCRTUS - Create User Space

B-66 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

ᑍ

QUSPTRUS - Retrieve Pointer to User Space

QusRetrieveExitInformation - Retrieve Exit

Information

ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

ᑍ

PROGRAM-ID. REGFAC2.

ENVIRONMENT DIVISION.

CONFIGURATION SECTION.

SOURCE-COMPUTER. IBM-AS4ðð.

OBJECT-COMPUTER. IBM-AS4ðð.

INPUT-OUTPUT SECTION.

FILE-CONTROL.

SELECT LISTING ASSIGN TO PRINTER-QPRINT

ORGANIZATION IS SEQUENTIAL.

DATA DIVISION.

FILE SECTION.

FD LISTING RECORD CONTAINS 132 CHARACTERS

LABEL RECORDS ARE STANDARD

DATA RECORD IS LIST-LINE.

ð1 LIST-LINE

PIC X(132).

WORKING-STORAGE SECTION.

ᑍ

ᑍ Error Code parameter include. As this sample program

ᑍ uses COPY to include the error code structure, only the first

ᑍ 16 bytes of the error code structure are available. If the

ᑍ application program needs to access the variable length

ᑍ exception data for the error, the developer should physically

ᑍ copy the QSYSINC include and modify the copied include to

ᑍ define additional storage for the exception data.

ᑍ

COPY QUSEC OF QSYSINC-QLBLSRC.

ᑍ

ᑍ Error message text

ᑍ

ð1 BAD-EXIT-POINT.

ð5 TEXT1

PIC X(4ð)

VALUE "Attempt to retrieve information failed: ".

ð5 EXCEPTION-ID PIC X(ð7).

ð1 BAD-EXIT-PGM.

ð5 TEXT1

PIC X(42)

VALUE "Attempt to retrieve Exit Programs failed: ".

ð5 EXCEPTION-ID PIC X(ð7).

ð1 BAD-CREATE.

ð5 TEXT1

PIC X(37)

VALUE "Allocation of RCVVAR storage failed: ".

ð5 EXCEPTION-ID PIC X(ð7).

ᑍ

ᑍ Miscellaneous elements

ᑍ

ð1 MISC.

ð5 EXIT-POINT-NAME PIC X(2ð) VALUE "EXAMPLE_EXIT_POINT".

ð5 EXIT-PGM-NBR

PIC S9(ð9) VALUE -1 BINARY.

ð5 EXIT-PARAMETERS PIC X(1ð).

ð5 FORMAT-NAME

PIC X(ð8) VALUE "EXTIð1ðð".

ð5 FORMAT-NAME-1 PIC X(ð8) VALUE "EXTIð2ðð".

ð5 FORMAT-NAME-2 PIC X(ð8) VALUE "EXMPð1ðð".

Appendix B. Original Examples in Additional Languages B-67

Download from Www.Somanuals.com. All Manuals Search And Download.

ð5 NBR-OF-SELECT-CRITERIA PIC S9(ð9) VALUE ð BINARY.

ð5 CONTINUATION-HDL PIC X(16).

ð5 BASE-POINTER

ð5 INFO-POINTER

ð5 SPACE-NAME

ð5 SPACE-ATTR

ð5 SPACE-SIZE

ð5 SPACE-VALUE

ð5 SPACE-AUTH

ð5 SPACE-TEXT

POINTER.

PIC X(2ð) VALUE "RCVVAR

PIC X(1ð).

PIC S9(ð9) VALUE 35ðð BINARY.

PIC X(ð1) VALUE X"ðð".

PIC X(1ð) VALUE "ᑍUSE".

PIC X(5ð).

QTEMP

ð5 SPACE-REPLACE PIC X(1ð) VALUE "ᑍNO".

ð5 SPACE-DOMAIN PIC X(1ð) VALUE "ᑍUSER".

ᑍ

LINKAGE SECTION.

ᑍ Variable to hold results of QusRetrieveExitInformation. The

ᑍ storage for this variable will be allocated by way of a User

ᑍ Space.

ᑍ

ð1 RCVVAR

PIC X(35ðð).

ᑍ

ᑍ Registration Facility API include. These includes will be

ᑍ mapped over the RCVVAR (User Space) previously defined.

ᑍ

COPY QUSREG OF QSYSINC-QLBLSRC.

ᑍ

ᑍ Beginning of mainline

ᑍ

PROCEDURE DIVISION.

MAIN-LINE.

ᑍ

ᑍ Retrieve the exit point information first. If the current

ᑍ number of exit programs is not zero, retrieve the exit

ᑍ programs. It is not necessary to call for the exit point

ᑍ information to determine if the exit point has any exit

ᑍ programs. It is done here for illustrative purposes only.

ᑍ You can make one call to the API for the exit program

ᑍ information and check the number of exit program entries

ᑍ returned field to see if there are any exit programs to call.

ᑍ

ᑍ Initialize the error code to inform the API that all

ᑍ exceptions should be returned through the error code parameter.

ᑍ

MOVE 16 TO BYTES-PROVIDED OF QUS-EC.

ᑍ

ᑍ Create a User Space for RCVVAR.

ᑍ

CALL "QUSCRTUS" USING SPACE-NAME, SPACE-ATTR, SPACE-SIZE,

SPACE-VALUE, SPACE-AUTH, SPACE-TEXT,

SPACE-REPLACE, QUS-EC, SPACE-DOMAIN.

ᑍ

ᑍ If an exception occurs, the API returns the exception in the

ᑍ error code parameter. The bytes available field is set to

ᑍ zero if no exception occurs and greater than zero if an

ᑍ exception does occur.

ᑍ

IF BYTES-AVAILABLE OF QUS-EC > ð

IF EXCEPTION-ID OF QUS-EC = "CPF987ð"

B-68 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

CONTINUE

ELSE

OPEN OUTPUT LISTING,

MOVE EXCEPTION-ID OF QUS-EC

TO EXCEPTION-ID OF BAD-CREATE,

WRITE LIST-LINE FROM BAD-CREATE,

STOP RUN.

ᑍ

ᑍ Assign BASE-POINTER to address RCVVAR

ᑍ

CALL "QUSPTRUS" USING SPACE-NAME, BASE-POINTER, QUS-EC.

ᑍ

ᑍ If an exception occurs, the API returns the exception in the

ᑍ error code parameter. The bytes available field is set to

ᑍ zero if no exception occurs and greater than zero if an

ᑍ exception does occur.

ᑍ

IF BYTES-AVAILABLE OF QUS-EC > ð

OPEN OUTPUT LISTING,

MOVE EXCEPTION-ID OF QUS-EC

TO EXCEPTION-ID OF BAD-CREATE,

WRITE LIST-LINE FROM BAD-CREATE,

STOP RUN.

ᑍ

SET ADDRESS OF RCVVAR TO BASE-POINTER.

ᑍ

ᑍ Blank out the continuation handle to let the API know that this

ᑍ is a first attempt at the retrieve operation.

ᑍ

MOVE SPACES TO CONTINUATION-HDL.

ᑍ

ᑍ Call the API to retrieve the exit programs

ᑍ

CALL PROCEDURE "QusRetrieveExitInformation" USING

CONTINUATION-HDL,

RCVVAR,

BY CONTENT LENGTH OF RCVVAR,

FORMAT-NAME OF MISC,

EXIT-POINT-NAME OF MISC,

FORMAT-NAME-2, EXIT-PGM-NBR,

NBR-OF-SELECT-CRITERIA, QUS-EC.

ᑍ

ᑍ If an exception occurs, the API returns the exception in the

ᑍ error code parameter. The bytes available field is set to

ᑍ zero if no exception occurs and greater than zero if an

ᑍ exception does occur.

ᑍ

IF BYTES-AVAILABLE OF QUS-EC > ð

OPEN OUTPUT LISTING,

MOVE EXCEPTION-ID OF QUS-EC

TO EXCEPTION-ID OF BAD-EXIT-POINT,

WRITE LIST-LINE FROM BAD-EXIT-POINT,

STOP RUN.

ᑍ

ᑍ If the call to retrieve exit point information is successful,

ᑍ check to see if there are any exit programs to call.

ᑍ

SET ADDRESS OF QUS-EXTIð1ðð TO BASE-POINTER.

Appendix B. Original Examples in Additional Languages B-69

Download from Www.Somanuals.com. All Manuals Search And Download.

SET ADDRESS OF QUS-EXTIð2ðð TO BASE-POINTER.

ᑍ

IF NUMBER-POINTS-RETURNED OF QUS-EXTIð1ðð > ð

SET ADDRESS OF QUS-EXTIð1ðð-ENTRY TO

ADDRESS OF RCVVAR((OFFSET-EXIT-POINT-ENTRY OF

QUS-EXTIð1ðð + 1):)

ELSE STOP RUN.

ᑍ

IF NUMBER-EXIT-PROGRAMS OF QUS-EXTIð1ðð-ENTRY > ð

ᑍ There are some exit programs to call. Blank out the continuation

ᑍ handle to let the API know that this is a first attempt at the

ᑍ retrieve operation.

ᑍ

MOVE SPACES TO CONTINUATION-HDL,

ᑍ

ᑍ Call the exit programs

ᑍ

PERFORM CALL-EXIT-PROGRAMS,

ᑍ

ᑍ If the continuation handle field in the receiver variable is

ᑍ not set to blanks, the API has more information to return than

ᑍ what could fit in the receiver variable. Call the API for

ᑍ more exit programs to call.

ᑍ

PERFORM UNTIL CONTINUE-HANDLE OF QUS-EXTIð2ðð = SPACES

MOVE CONTINUE-HANDLE OF QUS-EXTIð2ðð

TO CONTINUATION-HDL,

PERFORM CALL-EXIT-PROGRAMS,

END-PERFORM.

ᑍ

STOP RUN.

ᑍ

ᑍ End of MAINLINE

ᑍ

ᑍ Process exit programs in receiver variable

ᑍ

CALL-EXIT-PROGRAMS.

ᑍ

ᑍ Call the API to retrieve the exit program information

ᑍ

CALL PROCEDURE "QusRetrieveExitInformation" USING

CONTINUATION-HDL, RCVVAR,

BY CONTENT LENGTH OF RCVVAR,

FORMAT-NAME-1,

EXIT-POINT-NAME OF MISC,

FORMAT-NAME-2, EXIT-PGM-NBR,

NBR-OF-SELECT-CRITERIA, QUS-EC.

ᑍ

ᑍ If an exception occurs, the API returns the exception in the

ᑍ error code parameter. The bytes available field is set to

ᑍ zero if no exception occurs and greater than zero if an

ᑍ exception does occur.

ᑍ

IF BYTES-AVAILABLE OF QUS-EC > ð

OPEN OUTPUT LISTING,

MOVE EXCEPTION-ID OF QUS-EC

B-70 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

TO EXCEPTION-ID OF BAD-EXIT-PGM,

WRITE LIST-LINE FROM BAD-EXIT-PGM,

STOP RUN.

ᑍ

ᑍ If the call to retrieve exit program information is successful,

ᑍ check to see if there are any exit programs to call.

ᑍ

ᑍ The receiver variable offers enough room for a minimum of one

ᑍ exit program entry because the receiver variable was declared

ᑍ as 35ðð bytes. Therefore, this example only checks the

ᑍ number of exit programs returned field. If the receiver

ᑍ variable were not large enough to hold at least one entry,

ᑍ the bytes available field would need to be checked as well as

ᑍ the number of exit programs returned field. If the number of

ᑍ exit programs returned field is set to zero and the bytes

ᑍ available field is greater than the bytes returned field, the

ᑍ API had at least one exit program entry to return but was

ᑍ unable to because the receiver variable was too small.

ᑍ

SET ADDRESS OF QUS-EXTIð2ðð-ENTRY

TO ADDRESS OF RCVVAR(OFFSET-PROGRAM-ENTRY

OF QUS-EXTIð2ðð + 1:).

PERFORM CALL-PGMS

NUMBER-PROGRAMS-RETURNED OF QUS-EXTIð2ðð TIMES.

ᑍ

CALL-PGMS.

ᑍ

ᑍ Call the exit program while ignoring failures on the call

ᑍ

CALL PROGRAM-NAME OF QUS-EXTIð2ðð-ENTRY USING

EXIT-PARAMETERS

ON EXCEPTION CONTINUE.

ᑍ

ᑍ Address the next exit program entry

ᑍ

SET ADDRESS OF QUS-EXTIð2ðð-ENTRY

TO ADDRESS OF RCVVAR(OFFSET-NEXT-ENTRY

OF QUS-EXTIð2ðð-ENTRY + 1:).

Retrieve Exit Point and Exit Program Information—OPM RPG Example

Refer to “Retrieve Exit Point and Exit Program Information—ILE C Example” on

page 4-13 for the original example.

Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Fᑍ

Fᑍ Program:

Retrieve Exit Point and Exit Program Information

Fᑍ

Fᑍ Language:

Fᑍ

OPM RPG

Fᑍ Description: This program retrieves exit point and exit

Fᑍ

program information. After retrieving the

exit point information, the program calls each

exit program.

Fᑍ

Fᑍ APIs Used:

Fᑍ

QUSRTVEI - Retrieve Exit Information

Appendix B. Original Examples in Additional Languages B-71

Download from Www.Somanuals.com. All Manuals Search And Download.

Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Fᑍ

FQPRINT O F

Iᑍ

132

PRINTER

Iᑍ Error Code parameter include. As this sample program

Iᑍ uses /COPY to include the error code structure, only the first

Iᑍ 16 bytes of the error code structure are available. If the

Iᑍ application program needs to access the variable length

Iᑍ exception data for the error, the developer should physically

Iᑍ copy the QSYSINC include and modify the copied include to

Iᑍ define additional storage for the exception data.

Iᑍ

I/COPY QSYSINC/QRPGSRC,QUSEC

Iᑍ

Iᑍ Formats for the Retrieve Exit Information API.

Iᑍ

I/COPY QSYSINC/QRPGSRC,QUSREG

Iᑍ

Iᑍ Miscellaneous data

Iᑍ

I I

'EXAMPLE_EXIT_POINT '

1 2ð EPNTNM

B 21 24ðEPGMNB

B 25 28ðRCVSZ

B 29 32ðX

-1

35ðð

IRCV

Cᑍ

B 33 36ðY

37 57 CALLPG

35ðð

Cᑍ Beginning of mainline

Cᑍ

Cᑍ Retrieve the exit point information first. If the current

Cᑍ number of exit programs is not zero, retrieve the exit

Cᑍ programs. It is not necessary to call for the exit point

Cᑍ information to determine if the exit point has any exit

Cᑍ programs. It is done here for illustrative purposes only.

Cᑍ You can make one call to the API for the exit program

Cᑍ information and check the number of exit program entries

Cᑍ returned field to see if there are any exit programs to call.

Cᑍ

Cᑍ Initialize the error code to inform the API that all

Cᑍ exceptions should be returned through the error code parameter.

Cᑍ

Z-ADD16

QUSBNB

Cᑍ Blank out the continuation handle to let the API know that this

Cᑍ is a first attempt at the retrieve operation.

Cᑍ

MOVE ᑍBLANKS CONTHD 16

Cᑍ Call the API to retrieve the exit point information

Cᑍ

CALL 'QUSRTVEI'

PARM

CONTHD

RCV

RCVSZ

PARM 'EXTIð1ðð'FORMAT 8

B-72 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

PARM

EPNTNM

PARM 'EXMPð1ðð'EPTFMT 8

PARM

PARM ð

PARM

EPGMNB

QUSCCB

QUSBN

Cᑍ

Cᑍ If an exception occurs, the API returns the exception in the

Cᑍ error code parameter. The bytes available field is set to

Cᑍ zero if no exception occurs and greater than zero if an

Cᑍ exception does occur.

Cᑍ

QUSBNC

IFGT ð

OPEN QPRINT

EXCPTERREPT

EXSR DONE

ENDIF

Cᑍ

Cᑍ If the call to retrieve exit point information is successful,

Cᑍ check to see if there are any exit programs to call.

Cᑍ

QUSCGG

2ð1

QUSCFF

SUBSTRCV:1

IFGT ð

ADD QUSCGF

SUBSTRCV:X

IFGT ð

QUSCG

QUSCF

Cᑍ

Cᑍ There are some exit programs to call. Blank out the continuation

Cᑍ handle to let the API know that this is a first attempt at the

Cᑍ retrieve operation.

Cᑍ

MOVE ᑍBLANKS CONTHD

Cᑍ

Cᑍ Call the exit programs

Cᑍ

EXSR CUSREI

Cᑍ If the continuation handle field in the receiver variable is

Cᑍ not set to blanks, the API has more information to return than

Cᑍ what could fit in the receiver variable. Call the API for

Cᑍ more exit programs to call.

Cᑍ

QUSCGD

DOWNEᑍBLANKS

MOVELQUSCGD

EXSR CUSREI

ENDDO

CONTHD

ENDIF

EXSR DONE

Cᑍ

Cᑍ End of MAINLINE

Cᑍ

Cᑍ Process exit programs in receiver variable

Cᑍ

CUSREI

BEGSR

Cᑍ Call the API to retrieve the exit program information

Cᑍ

CALL 'QUSRTVEI'

Appendix B. Original Examples in Additional Languages B-73

Download from Www.Somanuals.com. All Manuals Search And Download.

Cᑍ

PARM

CONTHD

RCV

RCVSZ

PARM 'EXTIð2ðð'FORMAT 8

PARM

EPNTNM

PARM 'EXMPð1ðð'EPTFMT 8

PARM

PARM ð

PARM

EPGMNB

QUSCCB

QUSBN

Cᑍ If an exception occurs, the API returns the exception in the

Cᑍ error code parameter. The bytes available field is set to

Cᑍ zero if no exception occurs and greater than zero if an

Cᑍ exception does occur.

Cᑍ

QUSBNC

IFGT ð

OPEN QPRINT

EXCPTERRPGM

EXSR DONE

ENDIF

Cᑍ

Cᑍ If the call to retrieve exit program information is successful,

Cᑍ check to see if there are any exit programs to call.

Cᑍ

Cᑍ The receiver variable offers enough room for a minimum of one

Cᑍ exit program entry because the receiver variable was declared

Cᑍ as 35ðð bytes. Therefore, this example only checks the

Cᑍ number of exit programs returned field. If the receiver

Cᑍ variable were not large enough to hold at least one entry,

Cᑍ the bytes available field would need to be checked as well as

Cᑍ the number of exit programs returned field. If the number of

Cᑍ exit programs returned field is set to zero and the bytes

Cᑍ available field is greater than the bytes returned field, the

Cᑍ API had at least one exit program entry to return but was

Cᑍ unable to because the receiver variable was too small.

Cᑍ

SUBSTRCV:1

ADD QUSCJF

SUBSTRCV:Y

DO QUSCJG

QUSCJ

QUSCH

Cᑍ

Cᑍ Get the exit program name and library

Cᑍ

MOVE ᑍBLANKS CALLPG

MOVELQUSCHL

CAT '/':ð

CALLPG

Cᑍ

CALLPG

CAT QUSCHK:ð CALLPG

Cᑍ Call the exit program while ignoring failures on the call

Cᑍ

CALL CALLPG

PARM

ð1

EXTPRM 1ð

Cᑍ

Cᑍ Set Y to point to the next exit program entry

Cᑍ

ADD QUSCHB

SUBSTRCV:Y

ENDDO

QUSCH

B-74 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

ENDSR

Cᑍ

Cᑍ Return to programs caller

DONE

BEGSR

SETON

RETRN

ENDSR

Oᑍ

OQPRINT E 1ð6

ERREPT

'Attempt to retrieve infor'

'mation failed: '

QUSBND

ERRPGM

OQPRINT E 1ð6

'Attempt to retrieve Exit'

' Programs failed: '

QUSBND

Retrieve Exit Point and Exit Program Information—ILE RPG Example

Refer to “Retrieve Exit Point and Exit Program Information—ILE C Example” on

page 4-13 for the original example.

Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Fᑍ

Fᑍ Program:

Retrieve Exit Point and Exit Program Information

Fᑍ

Fᑍ Language:

Fᑍ

ILE RPG

Fᑍ Description: This program retrieves exit point and exit

Fᑍ

program information. After retrieving the

exit point information, the program calls each ,

exit program.

Fᑍ

Fᑍ APIs Used:

QusRetrieveExitInformation - Retrieve Exit

Information

Fᑍ

Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Fᑍ

FQPRINT

Dᑍ

F 132

PRINTER OFLIND(ᑍINOF) USROPN

Dᑍ The following QUSREG include from QSYSINC is copied into

Dᑍ this program so that the data structures can be declared as

Dᑍ BASED.

Dᑍ

Dᑍᑍᑍ START HEADER FILE SPECIFICATIONS ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Dᑍ

DᑍHeader File Name: H/QUSREG

Dᑍ

DᑍDescriptive Name: Standard Registration Structures.

Dᑍ

DᑍUS Government Users Restricted Rights -

DᑍUse, duplication or disclosure restricted

Dᑍby GSA ADP Schedule Contract with IBM Corp.

Dᑍ

Appendix B. Original Examples in Additional Languages B-75

Download from Www.Somanuals.com. All Manuals Search And Download.

DᑍLicensed Materials-Property of IBM

Dᑍ

DᑍDescription: All of the structures that are used in the

Dᑍ

Registration facilities are kept here to avoid

conflict due to repetition.

DᑍHeader Files Included: None.

Dᑍ

DᑍMacros List: None.

Dᑍ

DᑍStructure List: Qus_Prep_Exit_t

Dᑍ

Qus_Qmff_t

Qus_Selcrtr_t

Qus_Select_Entry_t

Qus_Program_Data_t

Qus_EXTIð1ðð_t

Qus_EXTIð1ðð_Entry_t

Qus_EXTIð2ðð_t

Qus_EXTIð2ðð_Entry_t

Qus_EXTIð3ðð_t

Qus_EXTIð3ðð_Entry_t

DᑍFunction Prototype List: none.

Dᑍ

DᑍChange Activity:

Dᑍ

DᑍCFD List:

Dᑍ

DᑍFLAG REASON

LEVEL DATE PGMR

CHANGE DESCRIPTION

Dᑍ---- ------------ ----- ------ --------- ----------------------

Dᑍ$Að= D2862ððð

Dᑍ

3D1ð 94ð327 LUPA:

New Include

DᑍEnd CFD List.

Dᑍ

DᑍAdditional notes about the Change Activity

DᑍEnd Change Activity.

Dᑍᑍᑍ END HEADER FILE SPECIFICATIONS ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

DᑍFormat structure for the Preprocessing Exit Program Format for

DᑍQusRegisterExitPoint API.

Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

DQUSPE

Dᑍ

D QUSPPN

Dᑍ

D QUSPPLIB

Dᑍ

D QUSPPF

Dᑍ

Qus Prep Exit

1ð

2ð

Prep Prog Name

Prep Prog Library

Prep Prog Format

Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

DᑍFormat structure for the Qualified Message File Format for the

Dᑍentire service program.

Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

DQUSQMFF

Dᑍ

D QUSMFIL

Dᑍ

Qus Qmff

1ð

Message File

B-76 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

D QUSMLIB

Dᑍ

D QUSMI

Dᑍ

2ð

Message Library

Message Id

Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

DᑍFormat structure for the Exit Program Selection Criteria of the

DᑍQusRetrieveExitInformation API.

Dᑍᑍᑍᑍ

ᑍᑍᑍ

DᑍNOTE: This structure only defines fixed fields. Any varying

Dᑍ length or repeating field will have to be defined by

Dᑍ the user.

Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

DQUSSE

Dᑍ

D QUSSEðð

Dᑍ

D QUSCO

Dᑍ

D QUSSPD

Dᑍ

Qus Select Entry

Size Entry

4B ð

8B ð

12B ð

16B ð

Comp Operator

Start Pgm Data

Length Comp Data

D QUSLCD

Dᑍ

DᑍQUSCD

Dᑍ

Varying length

DQUSS

Dᑍ

Qus Selcrtr

D QUSNBRSC

Dᑍ

4B ð

Number Sel Criteria

DIM(ðððð1)

DᑍQUSARRAY

Dᑍ QUSSEð1

Dᑍ QUSCOðð

Dᑍ QUSSPDðð

Dᑍ QUSLCDðð

Dᑍ QUSCDðð

Dᑍ

9B ð OVERLAY(QUSARRAY:ðððð1)

9B ð OVERLAY(QUSARRAY:ðððð5)

9B ð OVERLAY(QUSARRAY:ðððð9)

9B ð OVERLAY(QUSARRAY:ððð13)

OVERLAY(QUSARRAY:ððð17)

Dᑍ

Varying length

Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

DᑍFormat Structure for the Program Data. This structure has

Dᑍset up to facilitate COBOL and RPG pointer basing.

Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

DQUSPGMD

Dᑍ

Qus Program Data

Varying length

D QUSDATAð1

Dᑍ

Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

DᑍFormat structure for the EXTIð1ðð Format for the

DᑍQusRetrieveExitInformation API.

Dᑍᑍᑍᑍ

ᑍᑍᑍ

DᑍNOTE: This structure only defines fixed fields. Any varying

Dᑍ length or repeating field will have to be defined by

Dᑍ the user.

Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

DQUSð1ððE

Dᑍ

D QUSEPNðð

Dᑍ

D QUSFNð8

BASED(INFSPCPTR)

Qus EXTIð1ðð Entry

2ð

Exit Point Name

Appendix B. Original Examples in Additional Languages B-77

Download from Www.Somanuals.com. All Manuals Search And Download.

Dᑍ

Format Name

D QUSMEP

32B ð

36B ð

Dᑍ

Max Exit Programs

Number Exit Programs

Allow Deregistration

Allow Change Control

Registered Exit Point

Prep Name Add Pgm

Prep Lib Add Pgm

Prep Format Add

Prep Name Rmv Pgm

Prep Lib Rmv Pgm

Prep Format Rmv

Prep Name Rtv Info

Prep Lib Rtv Info

Prep Format Rtv

Desc Indicator

D QUSNBREP

Dᑍ

D QUSAD

Dᑍ

D QUSACC

Dᑍ

D QUSREP

Dᑍ

D QUSPNAP

4ð

Dᑍ

D QUSPLAP

5ð

Dᑍ

D QUSPFA

6ð

Dᑍ

D QUSPNRP

Dᑍ

D QUSPLRP

Dᑍ

D QUSPFR

Dᑍ

D QUSPNRI

1ð5

Dᑍ

D QUSPLRI

1ð6

116

124

125

135

145

152

2ð2

115

123

124

134

144

151

2ð1

2ð2

Dᑍ

D QUSPFRðð

Dᑍ

D QUSDI

Dᑍ

D QUSDMFIL

Dᑍ

Desc Msg File

D QUSDMLIB

Dᑍ

Desc Msg Library

Desc Msg Id

D QUSDMI

Dᑍ

D QUSTD

Dᑍ

Text Description

DᑍQUSERVEDð3

Dᑍ

Varying length

BASED(BASSPCPTR)

Qus EXTIð1ðð

DQUSIð1ðð

Dᑍ

D QUSBRTN

4B ð

8B ð

Dᑍ

Bytes Returned

D QUSBAVLðð

Dᑍ

Bytes Available

D QUSCH

Dᑍ

Continue Handle

D QUSOEPE

28B ð

32B ð

36B ð

Dᑍ

Offset Exit Point Entry

Number Points Returned

Length Exit Point Entry

D QUSNBRPR

Dᑍ

D QUSLEPE

Dᑍ

DᑍQUSERVEDð4

Dᑍ

B-78 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Dᑍ

Varying length

DᑍQUSARRAYðð

Dᑍ QUSEPNð1

Dᑍ QUSFNð9

Dᑍ QUSMEPðð

Dᑍ QUSNBREPðð

Dᑍ QUSADðð

Dᑍ QUSACCðð

Dᑍ QUSREPðð

Dᑍ QUSPNAPðð

Dᑍ QUSPLAPðð

Dᑍ QUSPFAðð

Dᑍ QUSPNRPðð

Dᑍ QUSPLRPðð

Dᑍ QUSPFRð1

Dᑍ QUSPNRIðð

Dᑍ QUSPLRIðð

Dᑍ QUSPFRð2

Dᑍ QUSDIðð

Dᑍ QUSDMFILðð

Dᑍ QUSDMLIBðð

Dᑍ QUSDMIðð

Dᑍ QUSTDðð

Dᑍ QUSERVEDð5

Dᑍ

2ð2

2ð

DIM(ðððð1)

OVERLAY(QUSARRAYðð:ðððð1)

OVERLAY(QUSARRAYðð:ððð21)

9B ð OVERLAY(QUSARRAYðð:ððð29)

9B ð OVERLAY(QUSARRAYðð:ððð33)

1ð

OVERLAY(QUSARRAYðð:ððð37)

OVERLAY(QUSARRAYðð:ððð38)

OVERLAY(QUSARRAYðð:ððð39)

OVERLAY(QUSARRAYðð:ððð4ð)

OVERLAY(QUSARRAYðð:ððð5ð)

OVERLAY(QUSARRAYðð:ððð6ð)

OVERLAY(QUSARRAYðð:ððð68)

OVERLAY(QUSARRAYðð:ððð78)

OVERLAY(QUSARRAYðð:ððð88)

OVERLAY(QUSARRAYðð:ððð96)

OVERLAY(QUSARRAYðð:ðð1ð6)

OVERLAY(QUSARRAYðð:ðð116)

OVERLAY(QUSARRAYðð:ðð124)

OVERLAY(QUSARRAYðð:ðð125)

OVERLAY(QUSARRAYðð:ðð135)

OVERLAY(QUSARRAYðð:ðð145)

OVERLAY(QUSARRAYðð:ðð152)

OVERLAY(QUSARRAYðð:ðð2ð2)

1ð

5ð

Dᑍ

Varying length

Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

DᑍFormat structure for the EXTIð2ðð Format for the

DᑍQusRetrieveExitInformation API.

Dᑍᑍᑍᑍ

ᑍᑍᑍ

DᑍNOTE: This structure only defines fixed fields. Any varying

Dᑍ length or repeating field will have to be defined by

Dᑍ the user.

Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

DQUSð2ððE

BASED(INFSPCPTR)

Qus EXTIð2ðð Entry

Dᑍ

D QUSONE

Dᑍ

4B ð

Offset Next Entry

Exit Point Name

Format Name

D QUSEPNð2

Dᑍ

D QUSFN1ð

Dᑍ

D QUSREPð1

Dᑍ

Registered Exit Pt

Complete Entry

Reserved

D QUSCE

Dᑍ

D QUSERVEDð6

Dᑍ

D QUSPGMN

4ðB ð

5ð

Dᑍ

Program Number

Program Name

D QUSPGMNðð

Dᑍ

D QUSPGML

Dᑍ

6ð

Program Library

Data CCSID

D QUSDC

Dᑍ

D QUSOED

Dᑍ

64B ð

68B ð

Offset Exit Data

Appendix B. Original Examples in Additional Languages B-79

Download from Www.Somanuals.com. All Manuals Search And Download.

D QUSLED

Dᑍ

DᑍQUSERVEDð6

Dᑍ

72B ð

Length Exit Data

Varying length

DᑍQUSPD

Dᑍ QUSDATAð2

Dᑍ

Varying length

BASED(BASSPCPTR)

DQUSIð2ðð

Dᑍ

Qus EXTIð2ðð

D QUSBRTNðð

Dᑍ

D QUSBAVLð1

Dᑍ

D QUSCHðð

Dᑍ

4B ð

8B ð

Bytes Returned

Bytes Available

Continue Handle

D QUSOPGME

Dᑍ

D QUSNBRPRðð

Dᑍ

D QUSLPGME

Dᑍ

DᑍQUSERVEDð7

Dᑍ

28B ð

32B ð

36B ð

Offset Program Entry

Number Programs Returned

Length Program Entry

Varying length

DIM(ðððð1)

DᑍQUSARRAYð1

Dᑍ QUSONEðð

Dᑍ QUSEPNð3

Dᑍ QUSFN11

Dᑍ QUSREPð2

Dᑍ QUSCEðð

Dᑍ QUSERVEDð8

Dᑍ QUSPGMNð1

Dᑍ QUSPGMNð2

Dᑍ QUSPGMLðð

Dᑍ QUSDCðð

Dᑍ QUSOEDðð

Dᑍ QUSLEDðð

Dᑍ QUSERVEDð8

Dᑍ QUSPDðð

Dᑍ QUSDATAð3

Dᑍ

9B ð OVERLAY(QUSARRAYð1:ðððð1)

2ð

OVERLAY(QUSARRAYð1:ðððð5)

OVERLAY(QUSARRAYð1:ððð25)

OVERLAY(QUSARRAYð1:ððð33)

OVERLAY(QUSARRAYð1:ððð34)

OVERLAY(QUSARRAYð1:ððð35)

9B ð OVERLAY(QUSARRAYð1:ððð37)

1ð

OVERLAY(QUSARRAYð1:ððð41)

OVERLAY(QUSARRAYð1:ððð51)

9B ð OVERLAY(QUSARRAYð1:ððð61)

9B ð OVERLAY(QUSARRAYð1:ððð65)

9B ð OVERLAY(QUSARRAYð1:ððð69)

OVERLAY(QUSARRAYð1:ððð73)

OVERLAY(QUSARRAYð1:ðððð1)

Varying length

Dᑍ

Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

DᑍFormat structure for the EXTIð3ðð Format for the

DᑍQusRetrieveExitInformation API.

Dᑍᑍᑍᑍ

ᑍᑍᑍ

DᑍNOTE: This structure only defines fixed fields. Any varying

Dᑍ length or repeating field will have to be defined by

Dᑍ the user.

Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

DQUSð3ððE

Dᑍ

Qus EXTIð3ðð Entry

Offset Next Entry

Exit Point Name

D QUSONEð1

Dᑍ

D QUSEPNð4

Dᑍ

4B ð

B-80 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

D QUSFN12

Dᑍ

Format Name

D QUSREPð3

Dᑍ

Registered Exit Point

Complete Entry

Reserved

D QUSCEð1

Dᑍ

D QUSERVEDð9

Dᑍ

D QUSPGMNð3

4ðB ð

5ð

Dᑍ

Program Number

Program Name

Program Library

Desc Indicator

Message File

Message File Library

Message Id

D QUSPGMNð4

Dᑍ

D QUSPGMLð1

6ð

Dᑍ

D QUSDIð1

Dᑍ

D QUSMFILðð

Dᑍ

D QUSMFILL

Dᑍ

D QUSMIðð

Dᑍ

D QUSTDð1

138

Dᑍ

Text Desc

D QUSRSV2ð1

139

141

145

149

153

14ð

Dᑍ

Reserved2

D QUSDCð1

144B ð

148B ð

152B ð

153

Dᑍ

Data CCSID

D QUSOPD

Dᑍ

Offset Pgm Data

Length Pgm Data

D QUSLPD

Dᑍ

DᑍQUSERVEDð9

Dᑍ

Varying length

DᑍQUSPDð1

Dᑍ QUSDATAð4

Dᑍ

154

Varying length

Qus EXTIð3ðð

DQUSIð3ðð

Dᑍ

D QUSBRTNð1

4B ð

8B ð

Dᑍ

Bytes Returned

D QUSBAVLð2

Dᑍ

Bytes Available

D QUSCHð1

Dᑍ

Continue Handle

D QUSOPGMEðð

28B ð

32B ð

36B ð

Dᑍ

Offset Program Entry

Number Programs Returned

Length Program Entry

D QUSNBRPRð1

Dᑍ

D QUSLPGMEðð

Dᑍ

DᑍQUSERVED1ð

Dᑍ

DᑍQUSARRAYð2

Dᑍ QUSONEð2

Varying length

DIM(ðððð1)

154

9B ð OVERLAY(QUSARRAYð2:ðððð1)

Appendix B. Original Examples in Additional Languages B-81

Download from Www.Somanuals.com. All Manuals Search And Download.

Dᑍ QUSEPNð5

Dᑍ QUSFN13

Dᑍ QUSREPð4

Dᑍ QUSCEð2

Dᑍ QUSERVED11

Dᑍ QUSPGMNð5

Dᑍ QUSPGMNð6

Dᑍ QUSPGMLð2

Dᑍ QUSDIð2

Dᑍ QUSMFILð1

Dᑍ QUSMFILLðð

Dᑍ QUSMIð1

Dᑍ QUSTDð2

Dᑍ QUSRSV2ð2

Dᑍ QUSDCð2

Dᑍ QUSOPDðð

Dᑍ QUSLPDðð

Dᑍ QUSERVED11

Dᑍ QUSPDð2

Dᑍ QUSDATAð5

Dᑍ

2ð

OVERLAY(QUSARRAYð2:ðððð5)

OVERLAY(QUSARRAYð2:ððð25)

OVERLAY(QUSARRAYð2:ððð33)

OVERLAY(QUSARRAYð2:ððð34)

OVERLAY(QUSARRAYð2:ððð35)

9B ð OVERLAY(QUSARRAYð2:ððð37)

1ð

OVERLAY(QUSARRAYð2:ððð41)

OVERLAY(QUSARRAYð2:ððð51)

OVERLAY(QUSARRAYð2:ððð61)

OVERLAY(QUSARRAYð2:ððð62)

OVERLAY(QUSARRAYð2:ððð72)

OVERLAY(QUSARRAYð2:ððð82)

OVERLAY(QUSARRAYð2:ððð89)

OVERLAY(QUSARRAYð2:ðð139)

5ð

9B ð OVERLAY(QUSARRAYð2:ðð141)

9B ð OVERLAY(QUSARRAYð2:ðð145)

9B ð OVERLAY(QUSARRAYð2:ðð149)

OVERLAY(QUSARRAYð2:ðð153)

OVERLAY(QUSARRAYð2:ðððð1)

Varying length

Dᑍ

Dᑍ Error Code parameter include. As this sample program

Dᑍ uses /COPY to include the error code structure, only the first

Dᑍ 16 bytes of the error code structure are available. If the

Dᑍ application program needs to access the variable length

Dᑍ exception data for the error, the developer should physically

Dᑍ copy the QSYSINC include and modify the copied include to

Dᑍ define additional storage for the exception data.

Dᑍ

D/COPY QSYSINC/QRPGLESRC,QUSEC

Dᑍ

Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

DᑍPrototype for calling Retrieve Exit Information

Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

D QUSREI

Dᑍ

'QusRetrieveExitInformation'

Dᑍ Miscellaneous data

Dᑍ

DEPNTNAME

DEPGM_NBR

DRCVVAR

2ð

INZ('EXAMPLE_EXIT_POINT')

9B ð INZ(-1)

DIM(35ðð)

9B ð INZ(%SIZE(RCVVAR:ᑍALL))

DRCVVAR_SZ

DBASSPCPTR

DINFSPCPTR

DCALL_PGM

Cᑍ

ᑍ

Cᑍ Beginning of mainline

Cᑍ

Cᑍ Retrieve the exit point information first. If the current

Cᑍ number of exit programs is not zero, retrieve the exit

Cᑍ programs. It is not necessary to call for the exit point

Cᑍ information to determine if the exit point has any exit

Cᑍ programs. It is done here for illustrative purposes only.

Cᑍ You can make one call to the API for the exit program

Cᑍ information and check the number of exit program entries

Cᑍ returned field to see if there are any exit programs to call.

B-82 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Cᑍ

Cᑍ Initialize the error code to inform the API that all

Cᑍ exceptions should be returned through the error code parameter.

Cᑍ

EVAL

QUSBPRV = %SIZE(QUSEC)

Cᑍ Blank out the continuation handle to let the API know that this

Cᑍ is a first attempt at the retrieve operation.

Cᑍ

MOVE

ᑍBLANKS

CONTIN_HDL

Cᑍ

Cᑍ Call the API to retrieve the exit programs

Cᑍ

CALLB

PARM

QUSREI

CONTIN_HDL

RCVVAR

RCVVAR_SZ

FORMAT

EPNTNAME

EPNT_FMT

EPGM_NBR

QUSNBRSC

QUSEC

'EXTIð1ðð'

'EXMPð1ðð'

Cᑍ If an exception occurs, the API returns the exception in the

Cᑍ error code parameter. The bytes available field is set to

Cᑍ zero if no exception occurs and greater than zero if an

Cᑍ exception does occur.

Cᑍ

QUSBAVL > ð

QPRINT

ERRAEPNT

DONE

OPEN

EXCEPT

EXSR

ENDIF

Cᑍ

Cᑍ If the call to retrieve exit point information is successful,

Cᑍ check to see if there are any exit programs to call.

Cᑍ

EVAL

BASSPCPTR = %ADDR(RCVVAR)

QUSNBRPR > ð

INFSPCPTR = %ADDR(RCVVAR(QUSOEPE+1))

QUSNBREP > ð

Cᑍ

Cᑍ There are some exit programs to call. Blank out the continuation

Cᑍ handle to let the API know that this is a first attempt at the

Cᑍ retrieve operation.

Cᑍ

EVAL

CONTIN_HDL = ᑍBLANKS

Cᑍ

Cᑍ Call the exit programs

Cᑍ

EXSR

CUSREI

Cᑍ

Cᑍ If the continuation handle field in the receiver variable is

Cᑍ not set to blanks, the API has more information to return than

Cᑍ what could fit in the receiver variable. Call the API for

Cᑍ more exit programs to call.

Cᑍ

Appendix B. Original Examples in Additional Languages B-83

Download from Www.Somanuals.com. All Manuals Search And Download.

DOW

QUSCHðð <> ᑍBLANKS

CONTIN_HDL = QUSCHðð

CUSREI

EVAL

EXSR

ENDDO

ENDIF

EXSR

DONE

Cᑍ

Cᑍ End of MAINLINE

Cᑍ

Cᑍ Process exit programs in receiver variable

Cᑍ

CUSREI

BEGSR

Cᑍ Call the API to retrieve the exit program information

Cᑍ

CALLB

PARM

QUSREI

CONTIN_HDL

RCVVAR

RCVVAR_SZ

FORMAT

EPNTNAME

EPNT_FMT

EPGM_NBR

QUSNBRSC

QUSEC

'EXTIð2ðð'

'EXMPð1ðð'

Cᑍ If an exception occurs, the API returns the exception in the

Cᑍ error code parameter. The bytes available field is set to

Cᑍ zero if no exception occurs and greater than zero if an

Cᑍ exception does occur.

Cᑍ

QUSBAVL > ð

QPRINT

ERRAEPGM

DONE

OPEN

EXCEPT

EXSR

ENDIF

Cᑍ

Cᑍ If the call to retrieve exit program information is successful,

Cᑍ check to see if there are any exit programs to call.

Cᑍ

Cᑍ The receiver variable offers enough room for a minimum of one

Cᑍ exit program entry because the receiver variable was declared

Cᑍ as 35ðð bytes. Therefore, this example only checks the

Cᑍ number of exit programs returned field. If the receiver

Cᑍ variable were not large enough to hold at least one entry,

Cᑍ the bytes available field would need to be checked as well as

Cᑍ the number of exit programs returned field. If the number of

Cᑍ exit programs returned field is set to zero and the bytes

Cᑍ available field is greater than the bytes returned field, the

Cᑍ API had at least one exit program entry to return but was

Cᑍ unable to because the receiver variable was too small.

Cᑍ

EVAL

INFSPCPTR = %ADDR(RCVVAR(QUSOPGME+1))

QUSNBRPRðð

Cᑍ

Cᑍ Get the exit program name and library

Cᑍ

B-84 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

EVAL

CALL_PGM = %TRIMR(QUSPGML) +

'/' + QUSPGMNðð

Cᑍ

Cᑍ Call the exit program while ignoring failures on the call

Cᑍ

CALL

PARM

CALL_PGM

ð1

Cᑍ

EXIT_PARMS

1ð

Cᑍ Set INFSPCPTR to point to the next exit program entry

Cᑍ

EVAL

ENDDO

ENDSR

INFSPCPTR = %ADDR(RCVVAR(QUSONE+1))

Cᑍ

Cᑍ Return to programs caller

DONE

BEGSR

EVAL

RETURN

ENDSR

ᑍINLR = '1'

Oᑍ

OQPRINT

ERRAEPNT

1 6

'Attempt to retrieve infor-

mation failed: '

QUSEI

OQPRINT

ERRAEPGM

'Attempt to retrieve Exit -

Programs failed: '

QUSEI

Remove Exit Program and Deregister Exit Point—OPM COBOL

Example

Refer to “Remove Exit Program and Deregister Exit Point—ILE C Example” on

page 4-19 for the original example.

IDENTIFICATION DIVISION.

ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

ᑍ

ᑍ Program:

Remove an Exit Program

Deregister an Exit Point

ᑍ

ᑍ Language:

ᑍ

OPM COBOL

ᑍ Description: This program removes an exit program and

ᑍ

deregisters an exit point from the registration

facility.

ᑍ

ᑍ APIs Used:

QUSRMVEP - Remove Exit Program

QUSDRGPT - Deregister Exit Point

ᑍ

ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

ᑍ

ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

PROGRAM-ID. REGFAC1.

ENVIRONMENT DIVISION.

CONFIGURATION SECTION.

SOURCE-COMPUTER. IBM-AS4ðð.

Appendix B. Original Examples in Additional Languages B-85

Download from Www.Somanuals.com. All Manuals Search And Download.

OBJECT-COMPUTER. IBM-AS4ðð.

INPUT-OUTPUT SECTION.

FILE-CONTROL.

SELECT LISTING ASSIGN TO PRINTER-QPRINT

ORGANIZATION IS SEQUENTIAL.

DATA DIVISION.

FILE SECTION.

FD LISTING RECORD CONTAINS 132 CHARACTERS

LABEL RECORDS ARE STANDARD

DATA RECORD IS LIST-LINE.

ð1 LIST-LINE

PIC X(132).

WORKING-STORAGE SECTION.

ᑍ

ᑍ Error Code parameter include. As this sample program

ᑍ uses COPY to include the error code structure, only the first

ᑍ 16 bytes of the error code structure are available. If the

ᑍ application program needs to access the variable length

ᑍ exception data for the error, the developer should physically

ᑍ copy the QSYSINC include and modify the copied include to

ᑍ define additional storage for the exception data.

ᑍ

COPY QUSEC OF QSYSINC-QLBLSRC.

ᑍ

ᑍ Error message text

ᑍ

ð1 BAD-EXIT-POINT.

ð5 TEXT1

PIC X(41)

VALUE "Attempt to deregister exit point failed: ".

ð5 EXCEPTION-ID PIC X(ð7).

ð1 BAD-EXIT-PGM.

ð5 TEXT1

PIC X(39)

VALUE "Attempt to remove exit program failed: ".

ð5 EXCEPTION-ID PIC X(ð7).

ᑍ

ᑍ Miscellaneous elements

ᑍ

ð1 MISC.

ð5 PGM-NBR

PIC S9(ð9) VALUE 1 BINARY.

ð5 EXIT-POINT-NAME PIC X(2ð) VALUE "EXAMPLE_EXIT_POINT".

ð5 FORMAT-NAME PIC X(ð8) VALUE "EXMPð1ðð".

ᑍ

ᑍ Beginning of mainline

ᑍ

PROCEDURE DIVISION.

MAIN-LINE.

ᑍ

ᑍ Remove an exit program from the exit point and then deregister

ᑍ the exit point. It is not necessary to remove exit programs

ᑍ from an exit point before deregistering the exit point. It is

ᑍ done here only for illustrative purposes.

ᑍ

ᑍ Initialize the error code parameter. To signal exceptions to

ᑍ this program by the API, you need to set the bytes provided

ᑍ field of the error code to zero. Because this program has

ᑍ exceptions sent back through the error code parameter, it sets

ᑍ the bytes provided field to the number of bytes it gives the

ᑍ API for the parameter.

ᑍ

B-86 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

MOVE 16 TO BYTES-PROVIDED OF QUS-EC.

ᑍ

ᑍ Call the API to remove the exit program.

ᑍ

CALL "QUSRMVEP" USING EXIT-POINT-NAME, FORMAT-NAME,

PGM-NBR, QUS-EC.

ᑍ

ᑍ If an exception occurs, the API returns the exception in the

ᑍ error code parameter. The bytes available field is set to

ᑍ zero if no exception occurs and greater than zero if an

ᑍ exception does occur.

ᑍ

IF BYTES-AVAILABLE OF QUS-EC > ð

OPEN OUTPUT LISTING,

MOVE EXCEPTION-ID OF QUS-EC

TO EXCEPTION-ID OF BAD-EXIT-POINT,

WRITE LIST-LINE FROM BAD-EXIT-POINT,

STOP RUN.

ᑍ

ᑍ If the call to remove the exit program is successful,

ᑍ deregister the exit point.

ᑍ

ᑍ Call the API to deregister the exit point.

ᑍ

CALL "QUSDRGPT" USING EXIT-POINT-NAME, FORMAT-NAME, QUS-EC.

ᑍ

ᑍ If an exception occurs, the API returns the exception in the

ᑍ error code parameter. The bytes available field is set to

ᑍ zero if no exception occurs and greater than zero if an

ᑍ exception does occur.

ᑍ

IF BYTES-AVAILABLE OF QUS-EC > ð

OPEN OUTPUT LISTING,

MOVE EXCEPTION-ID OF QUS-EC

TO EXCEPTION-ID OF BAD-EXIT-PGM,

WRITE LIST-LINE FROM BAD-EXIT-PGM,

STOP RUN.

ᑍ

STOP RUN.

ᑍ

ᑍ End of MAINLINE

ᑍ

Remove Exit Program and Deregister Exit Point—ILE COBOL Example

Refer to “Remove Exit Program and Deregister Exit Point—ILE C Example” on

page 4-19 for the original example.

IDENTIFICATION DIVISION.

ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

ᑍ

ᑍ Program:

Remove an Exit Program

Deregister an Exit Point

ᑍ

ᑍ Language:

ᑍ

ILE COBOL

ᑍ Description: This program removes an exit program and

Appendix B. Original Examples in Additional Languages B-87

Download from Www.Somanuals.com. All Manuals Search And Download.

ᑍ

deregisters an exit point from the registration

facility.

ᑍ

ᑍ APIs Used:

QusRemoveExitProgram - Remove Exit Program

QusDeregisterExitPoint - Deregister Exit Point

ᑍ

ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

ᑍ

ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

PROGRAM-ID. REGFAC3.

ENVIRONMENT DIVISION.

CONFIGURATION SECTION.

SOURCE-COMPUTER. IBM-AS4ðð.

OBJECT-COMPUTER. IBM-AS4ðð.

INPUT-OUTPUT SECTION.

FILE-CONTROL.

SELECT LISTING ASSIGN TO PRINTER-QPRINT

ORGANIZATION IS SEQUENTIAL.

DATA DIVISION.

FILE SECTION.

FD LISTING RECORD CONTAINS 132 CHARACTERS

LABEL RECORDS ARE STANDARD

DATA RECORD IS LIST-LINE.

ð1 LIST-LINE

PIC X(132).

WORKING-STORAGE SECTION.

ᑍ

ᑍ Error Code parameter include. As this sample program

ᑍ uses COPY to include the error code structure, only the first

ᑍ 16 bytes of the error code structure are available. If the

ᑍ application program needs to access the variable length

ᑍ exception data for the error, the developer should physically

ᑍ copy the QSYSINC include and modify the copied include to

ᑍ define additional storage for the exception data.

ᑍ

COPY QUSEC OF QSYSINC-QLBLSRC.

ᑍ

ᑍ Error message text

ᑍ

ð1 BAD-EXIT-POINT.

ð5 TEXT1

PIC X(41)

VALUE "Attempt to deregister exit point failed: ".

ð5 EXCEPTION-ID PIC X(ð7).

ð1 BAD-EXIT-PGM.

ð5 TEXT1

PIC X(39)

VALUE "Attempt to remove exit program failed: ".

ð5 EXCEPTION-ID PIC X(ð7).

ᑍ

ᑍ Miscellaneous elements

ᑍ

ð1 MISC.

ð5 PGM-NBR

PIC S9(ð9) VALUE 1 BINARY.

ð5 EXIT-POINT-NAME PIC X(2ð) VALUE "EXAMPLE_EXIT_POINT".

ð5 FORMAT-NAME PIC X(ð8) VALUE "EXMPð1ðð".

ᑍ

ᑍ Beginning of mainline

ᑍ

PROCEDURE DIVISION.

MAIN-LINE.

B-88 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

ᑍ

ᑍ Remove an exit program from the exit point and then deregister

ᑍ the exit point. It is not necessary to remove exit programs

ᑍ from an exit point before deregistering the exit point. It is

ᑍ done here only for illustrative purposes.

ᑍ

ᑍ Initialize the error code parameter. To signal exceptions to

ᑍ this program by the API, you need to set the bytes provided

ᑍ field of the error code to zero. Because this program has

ᑍ exceptions sent back through the error code parameter, it sets

ᑍ the bytes provided field to the number of bytes it gives the

ᑍ API for the parameter.

ᑍ

MOVE 16 TO BYTES-PROVIDED OF QUS-EC.

ᑍ

ᑍ Call the API to remove the exit program.

ᑍ

CALL PROCEDURE "QusRemoveExitProgram" USING

EXIT-POINT-NAME, FORMAT-NAME,

PGM-NBR, QUS-EC.

ᑍ

ᑍ If an exception occurs, the API returns the exception in the

ᑍ error code parameter. The bytes available field is set to

ᑍ zero if no exception occurs and greater than zero if an

ᑍ exception does occur.

ᑍ

IF BYTES-AVAILABLE OF QUS-EC > ð

OPEN OUTPUT LISTING,

MOVE EXCEPTION-ID OF QUS-EC

TO EXCEPTION-ID OF BAD-EXIT-POINT,

WRITE LIST-LINE FROM BAD-EXIT-POINT,

STOP RUN.

ᑍ

ᑍ If the call to remove the exit program is successful,

ᑍ deregister the exit point.

ᑍ

ᑍ Call the API to deregister the exit point.

ᑍ

CALL PROCEDURE "QusDeregisterExitPoint" USING

EXIT-POINT-NAME, FORMAT-NAME, QUS-EC.

ᑍ

ᑍ If an exception occurs, the API returns the exception in the

ᑍ error code parameter. The bytes available field is set to

ᑍ zero if no exception occurs and greater than zero if an

ᑍ exception does occur.

ᑍ

IF BYTES-AVAILABLE OF QUS-EC > ð

OPEN OUTPUT LISTING,

MOVE EXCEPTION-ID OF QUS-EC

TO EXCEPTION-ID OF BAD-EXIT-PGM,

WRITE LIST-LINE FROM BAD-EXIT-PGM,

STOP RUN.

ᑍ

STOP RUN.

ᑍ

ᑍ End of MAINLINE

ᑍ

Appendix B. Original Examples in Additional Languages B-89

Download from Www.Somanuals.com. All Manuals Search And Download.

Remove Exit Program and Deregister Exit Point—OPM RPG Example

Refer to “Remove Exit Program and Deregister Exit Point—ILE C Example” on

page 4-19 for the original example.

Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Fᑍ

Fᑍ Program:

Remove an Exit Program

Deregister an Exit Point

Fᑍ

Fᑍ Language:

Fᑍ

OPM RPG

Fᑍ Description: This program removes an exit program and

Fᑍ

deregisters an exit point from the registration

facility.

Fᑍ

Fᑍ APIs Used:

QUSRMVEP - Remove Exit Program

QUSDRGPT - Deregister Exit Point

Fᑍ

Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Fᑍ

FQPRINT O F

Iᑍ

132

PRINTER

Iᑍ Error Code parameter include. As this sample program

Iᑍ uses /COPY to include the error code structure, only the first

Iᑍ 16 bytes of the error code structure are available. If the

Iᑍ application program needs to access the variable length

Iᑍ exception data for the error, the developer should physically

Iᑍ copy the QSYSINC include and modify the copied include to

Iᑍ define additional storage for the exception data.

Iᑍ

I/COPY QSYSINC/QRPGSRC,QUSEC

Iᑍ

Iᑍ Miscellaneous data

Iᑍ

B 1 4ðPGMNBR

'EXAMPLE_EXIT_POINT ' 5 24 EPNTNM

I I

Cᑍ

Cᑍ Beginning of mainline

Cᑍ

Cᑍ Remove an exit program from the exit point and then deregister

Cᑍ the exit point. It is not necessary to remove exit programs

Cᑍ from an exit point before deregistering the exit point. It is

Cᑍ done here only for illustrative purposes.

Cᑍ

Cᑍ Initialize the error code parameter. To signal exceptions to

Cᑍ this program by the API, you need to set the bytes provided

Cᑍ field of the error code to zero. Because this program has

Cᑍ exceptions sent back through the error code parameter, it sets

Cᑍ the bytes provided field to the number of bytes it gives the

Cᑍ API for the parameter.

Cᑍ

Z-ADD16

QUSBNB

Cᑍ

Cᑍ Call the API to remove the exit program.

B-90 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Cᑍ

CALL 'QUSRMVEP'

PARM

EPNTNM

PARM 'EXMPð1ðð'FORMAT 8

PARM 1

PARM

PGMNBR

QUSBN

Cᑍ

Cᑍ If an exception occurs, the API returns the exception in the

Cᑍ error code parameter. The bytes available field is set to

Cᑍ zero if no exception occurs and greater than zero if an

Cᑍ exception does occur.

Cᑍ

QUSBNC

IFGT ð

OPEN QPRINT

EXCPTERRPGM

EXSR DONE

ENDIF

Cᑍ

Cᑍ If the call to remove the exit program is successful,

Cᑍ deregister the exit point.

Cᑍ

Cᑍ Call the API to deregister the exit point.

Cᑍ

CALL 'QUSDRGPT'

PARM

PARM 'EXMPð1ðð'FORMAT

PARM QUSBN

EPNTNM

Cᑍ

Cᑍ If an exception occurs, the API returns the exception in the

Cᑍ error code parameter. The bytes available field is set to

Cᑍ zero if no exception occurs and greater than zero if an

Cᑍ exception does occur.

Cᑍ

QUSBNC

IFGT ð

OPEN QPRINT

EXCPTERREPT

EXSR DONE

ENDIF

EXSR DONE

Cᑍ

Cᑍ End of MAINLINE

Cᑍ

Cᑍ Return to programs caller

DONE

BEGSR

SETON

RETRN

ENDSR

Oᑍ

OQPRINT E 1ð6

ERREPT

'Attempt to deregister '

'exit point failed: '

QUSBND

ERRPGM

OQPRINT E 1ð6

'Attempt to remove exit '

'program failed: '

QUSBND

Appendix B. Original Examples in Additional Languages B-91

Download from Www.Somanuals.com. All Manuals Search And Download.

Remove Exit Program and Deregister Exit Point—ILE RPG Example

Refer to “Remove Exit Program and Deregister Exit Point—ILE C Example” on

page 4-19 for the original example.

Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Fᑍ

Fᑍ Program:

Remove an Exit Program

Deregister an Exit Point

Fᑍ

Fᑍ Language:

Fᑍ

ILE RPG

Fᑍ Description: This program removes an exit program and

Fᑍ

deregisters an exit point from the registration

facility.

Fᑍ

Fᑍ APIs Used:

QusRemoveExitProgram - Remove Exit Program

QusDeregisterExitPoint - Deregister Exit Point

Fᑍ

Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Fᑍ

FQPRINT

Dᑍ

F 132

PRINTER OFLIND(ᑍINOF) USROPN

Dᑍ Error Code parameter include. As this sample program

Dᑍ uses /COPY to include the error code structure, only the first

Dᑍ 16 bytes of the error code structure are available. If the

Dᑍ application program needs to access the variable length

Dᑍ exception data for the error, the developer should physically

Dᑍ copy the QSYSINC include and modify the copied include to

Dᑍ define additional storage for the exception data.

Dᑍ

D/COPY QSYSINC/QRPGLESRC,QUSEC

Dᑍ

Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

DᑍPrototype for calling Deregister Exit Point API.

Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

D QUSDEP

'QusDeregisterExitPoint'

Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

DᑍPrototype for calling Remove Exit Program API.

Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

D QUSREPGM

Dᑍ

'QusRemoveExitProgram'

Dᑍ Miscellaneous data

Dᑍ

DPGM_NBR

DEPNTNAME

Cᑍ

9B ð

2ð

INZ('EXAMPLE_EXIT_POINT')

Cᑍ Beginning of mainline

Cᑍ

Cᑍ Remove an exit program from the exit point and then deregister

Cᑍ the exit point. It is not necessary to remove exit programs

Cᑍ from an exit point before deregistering the exit point. It is

Cᑍ done here only for illustrative purposes.

Cᑍ

Cᑍ Initialize the error code parameter. To signal exceptions to

Cᑍ this program by the API, you need to set the bytes provided

Cᑍ field of the error code to zero. Because this program has

B-92 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Cᑍ exceptions sent back through the error code parameter, it sets

Cᑍ the bytes provided field to the number of bytes it gives the

Cᑍ API for the parameter.

Cᑍ

EVAL

QUSBPRV = %SIZE(QUSEC)

Cᑍ

Cᑍ Call the API to remove the exit program.

Cᑍ

CALLB

PARM

QUSREPGM

EPNTNAME

FORMAT

PGM_NBR

QUSEC

'EXMPð1ðð'

Cᑍ

Cᑍ If an exception occurs, the API returns the exception in the

Cᑍ error code parameter. The bytes available field is set to

Cᑍ zero if no exception occurs and greater than zero if an

Cᑍ exception does occur.

Cᑍ

QUSBAVL > ð

QPRINT

ERRAEPGM

DONE

OPEN

EXCEPT

EXSR

ENDIF

Cᑍ

Cᑍ If the call to remove the exit program is successful,

Cᑍ deregister the exit point.

Cᑍ

Cᑍ Call the API to deregister the exit point.

Cᑍ

CALLB

PARM

QUSDEP

EPNTNAME

FORMAT

QUSEC

'EXMPð1ðð'

Cᑍ

Cᑍ If an exception occurs, the API returns the exception in the

Cᑍ error code parameter. The bytes available field is set to

Cᑍ zero if no exception occurs and greater than zero if an

Cᑍ exception does occur.

Cᑍ

QUSBAVL > ð

QPRINT

ERRAEPNT

DONE

OPEN

EXCEPT

EXSR

ENDIF

EXSR

DONE

Cᑍ

Cᑍ End of MAINLINE

Cᑍ

Cᑍ Return to programs caller

DONE

BEGSR

EVAL

RETURN

ENDSR

ᑍINLR = '1'

Oᑍ

OQPRINT

ERRAEPNT

1 6

'Attempt to deregister -

Appendix B. Original Examples in Additional Languages B-93

Download from Www.Somanuals.com. All Manuals Search And Download.

exit point failed: '

QUSEI

ERRAEPGM

OQPRINT

1 6

'Attempt to remove exit -

program failed: '

QUSEI

List Object API—Examples

This section includes the examples in “List Object API—OPM RPG Example” on

page 5-4.

List Object API—ILE C Example

Refer to “List Object API—OPM RPG Example” on page 5-4 for the original

example. This example uses includes from the QSYSINC library.

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ

ᑍ/

/ᑍ Program:

List objects that adopt owner authority

ILE C

/ᑍ

/ᑍ Language:

/ᑍ

/ᑍ Description: This program prints a report showing all objects

/ᑍ

that adopt owner authority. The two parameters

passed to the program are the profile to be

checked and the type of objects to be listed.

The parameter values are the same as those

accepted by the QSYLOBJP API.

/ᑍ

/ᑍ APIs Used:

QSYLOBJP - List Objects that Adopt Owner Authority ᑍ/

QUSCRTUS - Create User Space

QUSPTRUS - Retrieve Pointer to User Space

QUSROBJD - Retrieve Object Description

/ᑍ

ᑍ/

#include <stdio.h>

#include <string.h>

#include <qsylobjp.h>

#include <quscrtus.h>

#include <qusptrus.h>

#include <qusrobjd.h>

#include <qusgen.h>

#include <qusec.h>

/ᑍ QSYLOBJP API Header

ᑍ/

/ᑍ QUSCRTUS API Header

/ᑍ QUSPTRUS API Header

/ᑍ QUSROBJD API Header

/ᑍ Format Structures for User Space

/ᑍ Error Code Parameter Include for the APIs ᑍ/

/ᑍ Entry Point Table Include

#include <qliept.h>

ᑍ/

/ᑍ Error Code Structure

/ᑍ

ᑍ/

/ᑍ This shows how the user can define the variable length portion of ᑍ/

/ᑍ error code for the exception data.

/ᑍ

ᑍ/

typedef struct {

Qus_EC_t ec_fields;

B-94 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

char

Exception_Data[1ðð];

} error_code_t;

/ᑍ Global Variables ᑍ/

char

int

api_name[1ð];

cont_hdl[2ð];

ext_attr[1ð];

list_status;

mbr_list[8];

obj_type[1ð];

rcvvar[8];

rjobd_fmt[8];

space_auth[1ð];

space_dmn[1ð];

space_init;

space_name[2ð];

space_rep[1ð];

space_text[5ð];

space_type[1ð];

usr_prf[1ð];

ᑍusrspc_ptr, ᑍusrspc_base;

rcvlen = 8;

size_entry;

space_size = 1;

int

error_code_t error_code;

FILE

ᑍrecord;

/ᑍ Function:

/ᑍ

done

ᑍ/

/ᑍ Description: This function prints the end of listing print line ᑍ/

/ᑍ

and returns to the caller.

ᑍ/

void done()

{

char command_string[32];

fwrite("ᑍᑍᑍ End of List",1, 15, record);

fclose(record);

exit();

} /ᑍ done ᑍ/

/ᑍ Function:

/ᑍ

apierr

ᑍ/

/ᑍ Description: This function prints the API name, and exception

/ᑍ

identifier of an error that occurred.

void apierr()

{

printf("API: %.1ðs\n", api_name);

printf("Failed with exception: %.7s\n",

error_code.ec_fields.Exception_Id);

done();

Appendix B. Original Examples in Additional Languages B-95

Download from Www.Somanuals.com. All Manuals Search And Download.

} /ᑍ apierr ᑍ/

/ᑍ Function:

/ᑍ

getlst

ᑍ/

/ᑍ Description: This function calls QSYLOBJP to build a list.

/ᑍ

void getlst()

{

memcpy(mbr_list, "OBJPð2ðð", 8);

/ᑍ Call QSYLOBJP API to generate a list. The continuation handle ᑍ/

/ᑍ is set by the caller of this function.

ᑍ/

QSYLOBJP(space_name,

mbr_list,

/ᑍ User space and library

/ᑍ Member list

ᑍ/

usr_prf,

/ᑍ User profile

obj_type,

cont_hdl,

&error_code);

/ᑍ Object type

/ᑍ Continuation handle .3/

/ᑍ Error code

/ᑍ Check for errors on QSYLOBJP.

ᑍ/

if(error_code.ec_fields.Bytes_Available > ð)

{

memcpy(api_name, "QSYLOBJP ", 1ð);

apierr();

}

} /ᑍ getlst ᑍ/

/ᑍ Function:

/ᑍ

init

ᑍ/

/ᑍ Description: This function does all the necessary initialization ᑍ/

/ᑍ

for this program.

ᑍ/

void init()

{

memcpy(space_name, "ADOPTS

space_init = ðxðð;

QTEMP

", 2ð);

memcpy(mbr_list, "OBJPð2ðð", 8);

memcpy(rjobd_fmt, "OBJDð1ðð", 8);

memcpy(space_type, "ᑍUSRSPC ", 1ð);

memcpy(ext_attr, "QSYLOBJP ", 1ð);

memcpy(space_auth, "ᑍALL

memcpy(space_rep, "ᑍYES

memcpy(space_dmn, "ᑍUSER

", 1ð);

/ᑍ Open QPRINT file so that data can be written to it. If the file ᑍ/

/ᑍ cannot be opened, print a message and exit.

ᑍ/

if((record = fopen("QPRINT", "wb, lrecl=132, type=record")) == NULL)

B-96 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

{

}

printf("File could not be opened\n");

exit(1);

error_code.ec_fields.Bytes_Provided = sizeof(error_code_t);

/ᑍ Call QUSROBJD to see if the user space was previously created in ᑍ/

/ᑍ QTEMP. If it was, simply reuse it.

ᑍ/

QUSROBJD(rcvvar,

rcvlen,

/ᑍ Receiver variable

/ᑍ Receiver variable length

/ᑍ Format

/ᑍ User space name and library

/ᑍ User object type

/ᑍ Error code

ᑍ/

rjobd_fmt,

space_name,

space_type,

&error_code);

if(error_code.ec_fields.Bytes_Available > ð)

{

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ If a CPF98ð1 error was received, then the user space was not ᑍ/

/ᑍ found.

ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

if(memcmp(error_code.ec_fields.Exception_Id, "CPF98ð1", 7) == ð)

{

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ Create a user space for the list generated by QSYLOBJP.

ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

QUSCRTUS(space_name,

ext_attr,

/ᑍ User space name and library

/ᑍ Extended attribute

/ᑍ Size of the user space

/ᑍ Space initialization

/ᑍ Public authority to user space ᑍ/

/ᑍ User space text ᑍ/

/ᑍ Replace existing user space? ᑍ/

/ᑍ Error Code ᑍ/

/ᑍ Domain of created user space ᑍ/

ᑍ/

space_size,

&space_init,

space_auth,

space_text,

space_rep,

&error_code,

space_dmn);

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ Check for errors on QUSCRTUS.

ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

if(error_code.ec_fields.Bytes_Available > ð)

{

memcpy(api_name, "QUSCRTUS ", 1ð);

apierr();

}

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ An error occurred accessing the user space.

ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

else

{

memcpy(api_name, "QUSRJOBD ", 1ð);

apierr();

}

Appendix B. Original Examples in Additional Languages B-97

Download from Www.Somanuals.com. All Manuals Search And Download.

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ Set QSYLOBJP (via GETLST) to start a new list.

ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

memset(cont_hdl, ' ', 2ð);

getlst();

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ Get a resolved pointer to the user space for performance.

ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

QUSPTRUS(space_name,

&usrspc_ptr,

/ᑍ User space name and library

/ᑍ User space pointer

/ᑍ Error Code

ᑍ/

&error_code);

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ Check for errors on QUSPTRUS.

ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

if(error_code.ec_fields.Bytes_Available > ð)

{

memcpy(api_name, "QUSPTRUS ", 1ð);

apierr();

}

usrspc_base = usrspc_ptr;

} /ᑍ init ᑍ/

/ᑍ Function:

/ᑍ

proces2

ᑍ/

/ᑍ Description: This function processes each entry returned by

/ᑍ

QSYLOBJP.

void proces2()

{

char obj_type[112];

sprintf(obj_type, "Object: %.1ðs Library: %.1ðs Type: %.1ðs Text: %.5ðs\n",

((Qsy_OBJPð2ðð_List_T ᑍ)usrspc_ptr)->Object.Name,

((Qsy_OBJPð2ðð_List_T ᑍ)usrspc_ptr)->Object.Library,

((Qsy_OBJPð2ðð_List_T ᑍ)usrspc_ptr)->Object_Type,

((Qsy_OBJPð2ðð_List_T ᑍ)usrspc_ptr)->Object_Text);

fwrite(obj_type, 1, 112, record);

/ᑍ After each entry, increment to the next entry.

ᑍ/

usrspc_ptr += size_entry;

.7/

} /ᑍ proces2 ᑍ/

/ᑍ Function:

/ᑍ

proces1

ᑍ/

/ᑍ Description: This function processes each entry returned by

/ᑍ

QSYLOBJP.

B-98 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

void proces1()

{

int i;

int num_entries;

int offset;

num_entries = ((Qus_Generic_Header_ð1ðð_t ᑍ)\

usrspc_ptr)->Number_List_Entries;

/ᑍ If valid information was returned. .1/

ᑍ/

if((((Qus_Generic_Header_ð1ðð_t ᑍ)usrspc_ptr)->Information_Status == 'C') ||

(((Qus_Generic_Header_ð1ðð_t ᑍ)usrspc_ptr)->Information_Status == 'P'))

{

if(num_entries > ð)

{

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ Get the size of each entry to use later. .4/

ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

size_entry = ((Qus_Generic_Header_ð1ðð_t ᑍ)usrspc_ptr)->Size_Each_Entry;

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ Increment to the first list entry.

ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

offset = ((Qus_Generic_Header_ð1ðð_t ᑍ)usrspc_ptr)->Offset_List_Data; .5/

usrspc_ptr += offset;

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ Process all of the entries.

ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

for(i=ð; i<num_entries; i++)

proces2();

.6/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ Reset the user space pointer to the beginning. ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

usrspc_ptr = usrspc_base;

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ If all entries in this user space have been processed, check ᑍ/

/ᑍ if more entries exist than can fit in one user space.

ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

if(((Qus_Generic_Header_ð1ðð_t ᑍ)usrspc_ptr)->Information_Status == 'P')

{

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ Address the input parameter header.

ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

offset = ((Qus_Generic_Header_ð1ðð_t ᑍ)\

usrspc_ptr)->Offset_Input_Parameter;

usrspc_ptr += offset;

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ If the continuation handle in the input parameter header ᑍ/

/ᑍ is blank, then set the list status to complete.

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

if(memcmp(((Qsy_OBJP_Input_T ᑍ)usrspc_ptr)->Continuation_Handle,

", 2ð) == ð)

Appendix B. Original Examples in Additional Languages B-99

Download from Www.Somanuals.com. All Manuals Search And Download.

{

}

list_status = 'C';

else

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ Else, call QSYLOBJP reusing the user space to get more

/ᑍ list entries.

ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

{

memcpy(cont_hdl, ((Qsy_OBJP_Input_T ᑍ)\

usrspc_ptr)->Continuation_Handle, 2ð);

.2/

getlst();

list_status = ((Qus_Generic_Header_ð1ðð_t ᑍ)\

usrspc_ptr)->Information_Status;

}

else

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ If there exists an unexpected status, log an error (not shown) ᑍ/

/ᑍ and exit.

ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

{

done();

}

} /ᑍ proces1 ᑍ/

/ᑍ Function:

/ᑍ

proces

ᑍ/

/ᑍ Description: Processes entries until they are complete.

/ᑍ

void proces()

{

list_status = ((Qus_Generic_Header_ð1ðð_t ᑍ)usrspc_ptr)->Information_Status;

{

proces1();

} while (list_status != 'C');

} /ᑍ proces ᑍ/

/ᑍ main

ᑍ/

main(int argc, char ᑍargv[])

{

/ᑍ Make sure we received the correct number of parameters. The argc ᑍ/

/ᑍ parameter will contain the number of parameters that was passed ᑍ/

/ᑍ to this program. This number also includes the program itself, ᑍ/

/ᑍ so we need to evaluate argc-1.

ᑍ/

B-100 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

if (((argc - 1) < 2) || ((argc - 1 > 2)))

/ᑍ We did not receive all of the required parameters so exit the

/ᑍ program.

ᑍ/

{

exit(1);

}

else

/ᑍ Copy parameters into local variables.

ᑍ/

{

memcpy(usr_prf, argv[1], 1ð);

memcpy(obj_type, argv[2], 1ð);

}

init();

proces();

done();

} /ᑍ main ᑍ/

List Object API—ILE COBOL Example

Refer to “List Object API—OPM RPG Example” on page 5-4 for the original

example. The following program also works for OPM COBOL.

IDENTIFICATION DIVISION.

ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

ᑍ

ᑍ Program:

List objects that adopt owner authority

ᑍ

ᑍ Language:

ᑍ

COBOL

ᑍ Description: This program prints a report showing all objects

ᑍ

that adopt owner authority. The two parameters

passed to the program are the profile to be

checked and the type of objects to be listed.

The parameter values are the same as those

accepted by the QSYLOBJP API.

ᑍ

ᑍ APIs Used:

QSYLOBJP - List Objects that Adopt Owner Authority

QUSCRTUS - Create User Space

QUSPTRUS - Retrieve Pointer to User Space

QUSROBJD - Retrieve Object Description

ᑍ

ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

ᑍ

PROGRAM-ID. LISTADOPT.

ENVIRONMENT DIVISION.

CONFIGURATION SECTION.

SOURCE-COMPUTER. IBM-AS4ðð.

OBJECT-COMPUTER. IBM-AS4ðð.

INPUT-OUTPUT SECTION.

Appendix B. Original Examples in Additional Languages B-101

Download from Www.Somanuals.com. All Manuals Search And Download.

FILE-CONTROL.

SELECT LISTING ASSIGN TO PRINTER-QPRINT

ORGANIZATION IS SEQUENTIAL.

DATA DIVISION.

FILE SECTION.

FD LISTING RECORD CONTAINS 132 CHARACTERS

LABEL RECORDS ARE STANDARD

DATA RECORD IS LIST-LINE.

ð1 LIST-LINE

PIC X(132).

ᑍ

WORKING-STORAGE SECTION.

ᑍ Error Code parameter include. As this sample program

ᑍ uses COPY to include the error code structure, only the first

ᑍ 16 bytes of the error code structure are available. If the

ᑍ application program needs to access the variable length

ᑍ exception data for the error, the developer should physically

ᑍ copy the QSYSINC include and modify the copied include to

ᑍ define additional storage for the exception data.

ᑍ

COPY QUSEC OF QSYSINC-QLBLSRC.

ᑍ

ᑍ Listing text

ᑍ

ð1 OBJ-ENTRY.

ð5 OBJECT.

ð9 TEXT1

ð9 NAME

PIC X(ð8) VALUE "Object: ".

PIC X(1ð).

ð9 TEXT2

ð9 LIBRARY

PIC X(1ð) VALUE " Library: ".

PIC X(1ð).

ð5 TEXT3

PIC X(ð7) VALUE " Type: ".

ð5 OBJECT-TYPE PIC X(1ð).

ð5 TEXT4

PIC X(ð7) VALUE " Text: ".

ð5 OBJECT-TEXT PIC X(5ð).

ð1 END-LIST.

ð5 TEXT1

PIC X(15) VALUE "ᑍᑍᑍ End of List".

ᑍ

ð1 MISC.

ð5 SPC-NAME

ð5 SPC-SIZE

ð5 SPC-INIT

ð5 SPCPTR

PIC X(2ð) VALUE "ADOPTS

PIC S9(ð9) VALUE 1 BINARY.

PIC X(ð1) VALUE X"ðð".

POINTER.

QTEMP

ð5 RCVVAR

PIC X(ð8).

ð5 RCVVARSIZ

ð5 LST-STATUS

ð5 MBR-LIST

ð5 CONTIN-HDL

ð5 APINAM

ð5 ROBJD-FMT

ð5 SPC-TYPE

ð5 EXT-ATTR

ð5 SPC-AUT

PIC S9(ð9) VALUE 8 BINARY.

PIC X(ð1).

PIC X(ð8) VALUE "OBJPð2ðð".

PIC X(2ð).

PIC X(1ð).

PIC X(ð8) VALUE "OBJDð1ðð".

PIC X(1ð) VALUE "ᑍUSRSPC".

PIC X(1ð) VALUE "QSYLOBJP".

PIC X(1ð) VALUE "ᑍALL".

PIC X(5ð).

PIC X(1ð) VALUE "ᑍYES".

PIC X(1ð) VALUE "ᑍUSER".

ð5 SPC-TEXT

ð5 SPC-REPLAC

ð5 SPC-DOMAIN

ᑍ

LINKAGE SECTION.

B-102 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

ᑍ Input parameters.

ᑍ

ð1 USR-PRF

ð1 OBJ-TYPE

ᑍ

PIC X(1ð).

ᑍ String to map User Space offsets into

ᑍ

ð1 STRING-SPACE

PIC X(32ððð).

ᑍ

ᑍ User Space Generic Header include. These includes will be

ᑍ mapped over a User Space.

ᑍ

COPY QUSGEN OF QSYSINC-QLBLSRC.

ᑍ

ᑍ List Objects that Adopt API include. These includes will be

ᑍ mapped over a User Space.

ᑍ

COPY QSYLOBJP OF QSYSINC-QLBLSRC.

ᑍ

ᑍ Beginning of mainline

ᑍ

PROCEDURE DIVISION USING USR-PRF, OBJ-TYPE.

MAIN-LINE.

PERFORM INIT.

PERFORM PROCES.

PERFORM DONE.

ᑍ

ᑍ Start of subroutines

ᑍ

ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

PROCES.

ᑍ

ᑍ Do until the list is complete

ᑍ

MOVE INFORMATION-STATUS OF QUS-GENERIC-HEADER-ð1ðð TO

LST-STATUS.

ᑍ

PERFORM PROCES1 WITH TEST AFTER UNTIL LST-STATUS = "C".

ᑍ

PROCES1.

ᑍ

ᑍ This subroutine processes each entry returned by QSYLOBJP

ᑍ

ᑍ If valid information was returned

ᑍ

IF (INFORMATION-STATUS OF QUS-GENERIC-HEADER-ð1ðð = "C"

OR INFORMATION-STATUS OF QUS-GENERIC-HEADER-ð1ðð = "P")

IF NUMBER-LIST-ENTRIES OF QUS-GENERIC-HEADER-ð1ðð > ð

ᑍ

ᑍ increment to the first list entry

ᑍ

SET ADDRESS OF QSY-OBJPð2ðð-LIST TO

ADDRESS OF STRING-SPACE(

(OFFSET-LIST-DATA OF QUS-GENERIC-HEADER-ð1ðð + 1):1), .5/

SET ADDRESS OF STRING-SPACE TO ADDRESS OF

QSY-OBJPð2ðð-LIST,

ᑍ

Appendix B. Original Examples in Additional Languages B-103

Download from Www.Somanuals.com. All Manuals Search And Download.

ᑍ and process all of the entries

ᑍ

PERFORM PROCES2

NUMBER-LIST-ENTRIES OF QUS-GENERIC-HEADER-ð1ðð TIMES, .6/

ᑍ

ᑍ If all entries in this User Space have been processed, check

ᑍ if more entries exist than can fit in one User Space

ᑍ

IF INFORMATION-STATUS OF QUS-GENERIC-HEADER-ð1ðð = "P"

ᑍ

ᑍ by addressing the input parameter header

ᑍ

SET ADDRESS OF STRING-SPACE TO SPCPTR,

SET ADDRESS OF QSY-OBJP-INPUT TO

ADDRESS OF STRING-SPACE((OFFSET-INPUT-PARAMETER

OF QUS-GENERIC-HEADER-ð1ðð + 1):1),

ᑍ

ᑍ If the continuation handle in the Input Parameter Header is

ᑍ blank, then set the List status to Complete

ᑍ

IF CONTINUATION-HANDLE OF QSY-OBJP-INPUT = SPACES

MOVE "C" TO LST-STATUS

ELSE

ᑍ

ᑍ Else, call QSYLOBJP reusing the User Space to get more

ᑍ List entries

ᑍ

MOVE CONTINUATION-HANDLE OF QSY-OBJP-INPUT

TO CONTIN-HDL OF MISC,

PERFORM GETLST,

.2/

MOVE INFORMATION-STATUS OF QUS-GENERIC-HEADER-ð1ðð

TO LST-STATUS,

END-IF,

ELSE

ᑍ

ᑍ And if an unexpected status, log an error (not shown) and exit

ᑍ

PERFORM DONE,

END-IF.

ᑍ

PROCES2.

MOVE CORRESPONDING QSY-OBJPð2ðð-LIST TO OBJ-ENTRY.

WRITE LIST-LINE FROM OBJ-ENTRY.

ᑍ

ᑍ after each entry, increment to the next entry

ᑍ

SET ADDRESS OF QSY-OBJPð2ðð-LIST TO ADDRESS OF

STRING-SPACE(

(SIZE-EACH-ENTRY OF QUS-GENERIC-HEADER-ð1ðð + 1):1). .7/

SET ADDRESS OF STRING-SPACE TO ADDRESS OF QSY-OBJPð2ðð-LIST.

ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

GETLST.

ᑍ

ᑍ Call QSYLOBJP to generate a list

ᑍ The continuation handle is set by the caller of this

ᑍ subroutine.

B-104 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

MOVE "OBJPð2ðð" TO MBR-LIST.

ᑍ

CALL "QSYLOBJP" USING SPC-NAME, MBR-LIST, USR-PRF,

OBJ-TYPE, CONTIN-HDL, QUS-EC. .3/

ᑍ Check for errors on QSYLOBJP

ᑍ

IF BYTES-AVAILABLE OF QUS-EC > ð

MOVE "QSYLOBJP" TO APINAM,

PERFORM APIERR.

ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

INIT.

ᑍ

ᑍ One time initialization code for this program

ᑍ

ᑍ Open LISTING file

ᑍ

OPEN OUTPUT LISTING.

ᑍ

ᑍ Set Error Code structure to not use exceptions

ᑍ

MOVE LENGTH OF QUS-EC TO BYTES-PROVIDED OF QUS-EC.

ᑍ

ᑍ Check to see if the User Space was previously created in

ᑍ QTEMP. If it was, simply reuse it.

ᑍ

CALL "QUSROBJD" USING RCVVAR, RCVVARSIZ, ROBJD-FMT,

SPC-NAME, SPC-TYPE, QUS-EC.

ᑍ

ᑍ Check for errors on QUSROBJD

ᑍ

IF BYTES-AVAILABLE OF QUS-EC > ð

ᑍ

ᑍ If CPF98ð1, then User Space was not found

ᑍ

IF EXCEPTION-ID OF QUS-EC = "CPF98ð1"

ᑍ

ᑍ So create a User Space for the List generated by QSYLOBJP

ᑍ

CALL "QUSCRTUS" USING SPC-NAME, EXT-ATTR, SPC-SIZE,

SPC-INIT, SPC-AUT, SPC-TEXT,

SPC-REPLAC, QUS-EC, SPC-DOMAIN

ᑍ

ᑍ Check for errors on QUSCRTUS

ᑍ

IF BYTES-AVAILABLE OF QUS-EC > ð

MOVE "QUSCRTUS" TO APINAM,

PERFORM APIERR,

ELSE

CONTINUE,

ELSE

ᑍ

ᑍ Else, an error occurred accessing the User Space

ᑍ

MOVE "QUSROBJD" TO APINAM,

PERFORM APIERR.

ᑍ

ᑍ Set QSYLOBJP (via GETLST) to start a new list

Appendix B. Original Examples in Additional Languages B-105

Download from Www.Somanuals.com. All Manuals Search And Download.

ᑍ

MOVE SPACES TO CONTIN-HDL.

PERFORM GETLST.

ᑍ Get a resolved pointer to the User Space for performance

ᑍ

CALL "QUSPTRUS" USING SPC-NAME, SPCPTR, QUS-EC.

ᑍ

ᑍ Check for errors on QUSPTRUS

ᑍ

IF BYTES-AVAILABLE OF QUS-EC > ð

MOVE "QUSPTRUS" TO APINAM,

PERFORM APIERR.

ᑍ

ᑍ If no error, then set addressability to User Space

ᑍ

SET ADDRESS OF QUS-GENERIC-HEADER-ð1ðð TO SPCPTR.

SET ADDRESS OF STRING-SPACE TO SPCPTR.

ᑍ

ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

APIERR.

ᑍ

ᑍ Log any error encountered, and exit the program

ᑍ

DISPLAY APINAM.

DISPLAY EXCEPTION-ID OF QUS-EC.

PERFORM DONE.

ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

DONE.

ᑍ

ᑍ Exit the program

ᑍ

WRITE LIST-LINE FROM END-LIST.

STOP RUN.

List Object API—ILE RPG Example

Refer to “List Object API—OPM RPG Example” on page 5-4 for the original

example.

Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Fᑍ

Fᑍ Program:

List objects that adopt owner authority

Fᑍ

Fᑍ Language:

Fᑍ

ILE RPG

Fᑍ Description: This program prints a report showing all objects

Fᑍ

that adopt owner authority. The two parameters

passed to the program are the profile to be

checked and the type of objects to be listed.

The parameter values are the same as those

accepted by the QSYLOBJP API.

Fᑍ

Fᑍ APIs Used:

QSYLOBJP - List Objects that Adopt Owner Authority

QUSCRTUS - Create User Space

QUSPTRUS - Retrieve Pointer to User Space

QUSROBJD - Retrieve Object Description

Fᑍ

B-106 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Fᑍ

Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Fᑍ

FQPRINT

Dᑍ

F 132

PRINTER OFLIND(ᑍINOF)

Dᑍ Error Code parameter include

Dᑍ

D/COPY QSYSINC/QRPGLESRC,QUSEC

Dᑍ

DSPC_NAME

DSPC_SIZE

DSPC_INIT

DLSTPTR

2ð

INZ('ADOPTS

INZ(X'ðð')

QTEMP

9B ð INZ(1)

ᑍ

DSPCPTR

DARR

DRCVVAR

DRCVVARSIZ

BASED(LSTPTR) DIM(32767)

9B ð INZ(8)

Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Dᑍ

Dᑍ The following QUSGEN include from QSYSINC is copied into

Dᑍ this program so that it can be declared as BASED on SPCPTR

Dᑍ

Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

DQUSHð1ðð

Dᑍ

D QUSUA

Dᑍ

D QUSSGH

Dᑍ

D QUSSRL

Dᑍ

D QUSFN

Dᑍ

D QUSAU

Dᑍ

D QUSDTC

Dᑍ

D QUSIS

Dᑍ

D QUSSUS

Dᑍ

D QUSOIP

Dᑍ

D QUSSIP

Dᑍ

D QUSOHS

Dᑍ

D QUSSHS

Dᑍ

D QUSOLD

Dᑍ

D QUSSLD

Dᑍ

D QUSNBRLE

Dᑍ

BASED(SPCPTR)

Qus Generic Header ð1ðð

User Area

68B ð

Size Generic Header

Structure Release Level

Format Name

8ð

9ð

API Used

1ð3

Date Time Created

Information Status

Size User Space

1ð4

1ð5

1ð9

113

117

121

125

129

133

137

1ð4

1ð8B ð

112B ð

116B ð

12ðB ð

124B ð

128B ð

132B ð

136B ð

14ðB ð

Offset Input Parameter

Size Input Parameter

Offset Header Section

Size Header Section

Offset List Data

Size List Data

Number List Entries

Size Each Entry

D QUSSEE

Dᑍ

Appendix B. Original Examples in Additional Languages B-107

Download from Www.Somanuals.com. All Manuals Search And Download.

D QUSSIDLE

141

145

147

15ð

151

144B ð

146

Dᑍ

CCSID List Ent

Country ID

D QUSCID

Dᑍ

D QUSLID

149

Dᑍ

Language ID

D QUSSLI

15ð

Dᑍ

Subset List Indicator

Reserved

D QUSERVEDðð

Dᑍ

192

Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Dᑍ

Dᑍ The following QSYLOBJP include from QSYSINC is copied into

Dᑍ this program so that it can be declared as BASED on LSTPTR

Dᑍ

Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

D QSYLOBJP

'QSYLOBJP'

Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

DᑍHeader structure for QSYLOBJP

Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

DQSYOBJPH

Dᑍ

D QSYUNðð

Dᑍ

D QSYCVðð

Dᑍ

BASED(LSTPTR)

Qsy OBJP Header

1ð

User name

3ð

Continuation Value

Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

DᑍRecord structure for OBJPð2ðð format

Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

DQSYð2ððLð2

BASED(LSTPTR)

Qsy OBJPð2ðð List

Dᑍ

D QSYNAMEð6

1ð

2ð

3ð

Dᑍ

Name

D QSYBRARYð6

Dᑍ

Library

D QSYOBJT13

Dᑍ

Object Type

Object In Use

Object Attribute

Object Text

D QSYOBJIUðð

Dᑍ

D QSYOBJA11

Dᑍ

D QSYOBJT14

Dᑍ

Cᑍ

Cᑍ Start of mainline

Cᑍ

ᑍENTRY

PLIST

PARM

EXSR

USR_PRF

OBJ_TYPE

1ð

INIT

PROCES

DONE

Cᑍ

Cᑍ Start of subroutines

Cᑍ

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Cᑍ

PROCES

BEGSR

B-108 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Cᑍ This subroutine processes each entry returned by QSYLOBJP

Cᑍ

Cᑍ Do until the list is complete

Cᑍ

MOVE

QUSIS

LST_STATUS

Cᑍ

LST_STATUS

DOUEQ

'C'

Cᑍ If valid information was returned

Cᑍ

QUSIS

IFEQ

OREQ

'C'

'P'

Cᑍ

Cᑍ and list entries were found

Cᑍ

QUSNBRLE

IFGT

Cᑍ

Cᑍ set LSTPTR to the first byte of the User Space

Cᑍ

EVAL

LSTPTR = SPCPTR

Cᑍ increment LSTPTR to the first List entry

Cᑍ

EVAL

LSTPTR = %ADDR(ARR(QUSOLD + 1)) .5/

Cᑍ and process all of the entries

Cᑍ

QUSNBRLE

.6/

EXCEPT

OBJ_ENTRY

Cᑍ

Cᑍ after each entry, increment LSTPTR to the next entry

Cᑍ

EVAL

END

LSTPTR = %ADDR(ARR(QUSSEE + 1)) .7/

END

Cᑍ

Cᑍ If all entries in this User Space have been processed, check

Cᑍ if more entries exist than can fit in one User Space

Cᑍ

QUSIS

IFEQ

'P'

Cᑍ by resetting LSTPTR to the start of the User Space

Cᑍ

EVAL

LSTPTR = SPCPTR

Cᑍ and then incrementing LSTPTR to the Input Parameter Header

Cᑍ

EVAL

LSTPTR = %ADDR(ARR(QUSOIP + 1))

Cᑍ

Cᑍ If the continuation handle in the Input Parameter Header is

Cᑍ blank, then set the List status to Complete

Cᑍ

QSYCVðð

IFEQ

MOVE

ELSE

ᑍBLANKS

'C'

LST_STATUS

Cᑍ

Cᑍ Else, call QSYLOBJP reusing the User Space to get more

Appendix B. Original Examples in Additional Languages B-109

Download from Www.Somanuals.com. All Manuals Search And Download.

Cᑍ List entries

Cᑍ

MOVE

EXSR

MOVE

END

QSYCVðð

GETLST

QUSIS

CONTIN_HDL .2/

LST_STATUS

END

ELSE

Cᑍ

Cᑍ And if an unexpected status, log an error (not shown) and exit

Cᑍ

EXSR

END

DONE

END

ENDSR

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Cᑍ

GETLST

BEGSR

Cᑍ Call QSYLOBJP to generate a list

Cᑍ The continuation handle is set by the caller of this

Cᑍ subroutine.

Cᑍ

CALL

PARM

QSYLOBJP

SPC_NAME

MBR_LIST

USR_PRF

OBJ_TYPE

CONTIN_HDL

QUSEC

'OBJPð2ðð'

2ð .3/

Cᑍ

Cᑍ Check for errors on QSYLOBJP

Cᑍ

QUSBAVL

IFGT

MOVEL

EXSR

END

'QSYLOBJP'

APIERR

APINAM

1ð

ENDSR

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

INIT

BEGSR

Cᑍ

Cᑍ One time initialization code for this program

Cᑍ

Cᑍ Set Error Code structure not to use exceptions

Cᑍ

Z-ADD

QUSBPRV

Cᑍ

Cᑍ Check to see if the User Space was previously created in

Cᑍ QTEMP. If it was, simply reuse it.

Cᑍ

CALL

PARM

'QUSROBJD'

RCVVAR

RCVVARSIZ

ROBJD_FMT

SPC_NAME

SPC_TYPE

QUSEC

'OBJDð1ðð'

'ᑍUSRSPC'

1ð

Cᑍ

Cᑍ Check for errors on QUSROBJD

B-110 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Cᑍ

QUSBAVL

IFGT

Cᑍ If CPF98ð1, then User Space was not found

Cᑍ

QUSEI

IFEQ

'CPF98ð1'

Cᑍ So create a User Space for the List generated by QSYLOBJP

Cᑍ

CALL

PARM

'QUSCRTUS'

SPC_NAME

'QSYLOBJP ' EXT_ATTR

SPC_SIZE

1ð

SPC_INIT

SPC_AUT

'ᑍALL'

ᑍBLANKS

'ᑍYES'

1ð

5ð

1ð

SPC_TEXT

SPC_REPLAC

QUSEC

'ᑍUSER'

SPC_DOMAIN

1ð

Cᑍ Check for errors on QUSCRTUS

Cᑍ

QUSBAVL

IFGT

MOVEL

EXSR

END

'QUSCRTUS'

APIERR

APINAM

1ð

Cᑍ

Cᑍ Else, an error occurred accessing the User Space

Cᑍ

ELSE

MOVEL

EXSR

END

'QUSROBJD'

APIERR

APINAM

1ð

END

Cᑍ

Cᑍ Set QSYLOBJP (via GETLST) to start a new list

Cᑍ

MOVE

EXSR

ᑍBLANKS

GETLST

CONTIN_HDL

Cᑍ

Cᑍ Get a resolved pointer to the User Space for performance

Cᑍ

CALL

PARM

'QUSPTRUS'

SPC_NAME

SPCPTR

QUSEC

Cᑍ

Cᑍ Check for errors on QUSPTRUS

Cᑍ

QUSBAVL

IFGT

MOVEL

EXSR

END

'QUSPTRUS'

APIERR

APINAM

1ð

ENDSR

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

APIERR

BEGSR

Cᑍ

Cᑍ Log any error encountered, and exit the program

Appendix B. Original Examples in Additional Languages B-111

Download from Www.Somanuals.com. All Manuals Search And Download.

Cᑍ

APINAM

QUSEI

DSPLY

EXSR

DONE

ENDSR

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

DONE

BEGSR

Cᑍ

Cᑍ Exit the program

Cᑍ

EXCEPT

EVAL

RETURN

ENDSR

END_LIST

ᑍINLR = '1'

OQPRINT

OBJ_ENTRY

'Object: '

' Library: '

' Type: '

QSYNAMEð6

QSYBRARYð6

QSYOBJT13

' Text: '

QSYOBJT14

END_LIST

OQPRINT

'ᑍᑍᑍ End of List'

OPM API without Pointers—Examples

This section includes the examples in “Reporting Software Error (ILE API with

Pointers)—ILE C Example” on page 6-7.

Logging Software Error (OPM API without Pointers)—OPM COBOL

Example

Refer to “Logging Software Error (OPM API without Pointers)—ILE C Example” on

page 6-2 for the original example. This example uses two programs: CBLERR1

causes the error, and ERRHDL1 shows how to log the software error using the

QPDLOGER API.

CBLERR1 Program

IDENTIFICATION DIVISION.

ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

ᑍ

ᑍ Program:

Cause a data decimal exception to demonstrate

logging of software errors

ᑍ

ᑍ Language:

ᑍ

COBOL

ᑍ Description: This program registers an OPM COBOL Error

ᑍ

Handler. After the successful completion of

the registration of the error handler, this

program creates a data decimal error. This

exception causes the error handler to be

called which then logs the software error.

B-112 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

ᑍ

ᑍ APIs Used:

ᑍ

QLRSETCE - Set COBOL Error Handler

ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

ᑍ

ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

PROGRAM-ID. CBLERR1.

ENVIRONMENT DIVISION.

CONFIGURATION SECTION.

SOURCE-COMPUTER. IBM-AS4ðð.

OBJECT-COMPUTER. IBM-AS4ðð.

INPUT-OUTPUT SECTION.

DATA DIVISION.

WORKING-STORAGE SECTION.

ᑍ

ᑍ Error Code parameter include. As this sample program

ᑍ uses COPY to include the error code structure, only the first

ᑍ 16 bytes of the error code structure are available. If the

ᑍ application program needs to access the variable length

ᑍ exception data for the error, the developer should physically

ᑍ copy the QSYSINC include and modify the copied include to

ᑍ define additional storage for the exception data.

ᑍ

COPY QUSEC OF QSYSINC-QLBLSRC.

ᑍ

ᑍ Miscellaneous elements

ᑍ

ð1 MISC.

ð5 Y

ð5 ERROR-HANDLER PIC X(2ð) VALUE "ERRHDL1 ᑍLIBL

ð5 SCOPE PIC X(ð1) VALUE "C".

PIC S9(ð9) VALUE ð.

ð5 ERROR-HANDLER-LIBRARY PIC X(1ð).

ð5 PRIOR-ERROR-HANDLER PIC X(2ð).

ð1 NUMERIC-GROUP.

ð5 X

PIC 9(ð3).

ᑍ

ᑍ Beginning of mainline

ᑍ

PROCEDURE DIVISION.

MAIN-LINE.

ᑍ

ᑍ Register the COBOL Error Handler.

ᑍ

ᑍ Initialize the error code parameter. To signal exceptions to

ᑍ this program by the API, you need to set the bytes provided

ᑍ field of the error code to zero. Because this program has

ᑍ exceptions sent back through the error code parameter, it sets

ᑍ the bytes provided field to the number of bytes it gives the

ᑍ API for the parameter.

ᑍ

MOVE 16 TO BYTES-PROVIDED.

ᑍ

ᑍ Call the API to register the exit point.

ᑍ

CALL "QLRSETCE" USING ERROR-HANDLER OF MISC,

SCOPE OF MISC,

ERROR-HANDLER-LIBRARY OF MISC,

Appendix B. Original Examples in Additional Languages B-113

Download from Www.Somanuals.com. All Manuals Search And Download.

PRIOR-ERROR-HANDLER OF MISC,

QUS-EC.

ᑍ

ᑍ If an exception occurs, the API returns the exception in the

ᑍ error code parameter. The bytes available field is set to

ᑍ zero if no exception occurs and greater than zero if an

ᑍ exception does occur.

ᑍ

IF BYTES-AVAILABLE OF QUS-EC > ð

DISPLAY "Error setting handler",

STOP RUN.

ᑍ

ᑍ If the call to register an error handler is successful, then

ᑍ cause a the data decimal error (X is initialized to blanks).

ᑍ

ADD X TO Y.

ᑍ

ᑍ Should not get here due to data decimal error

ᑍ

STOP RUN.

ᑍ

ᑍ End of MAINLINE

ᑍ

ERRHDL1 Program

IDENTIFICATION DIVISION.

ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

ᑍ

ᑍ Program:

Log a software error

ᑍ

ᑍ Language:

ᑍ

COBOL

ᑍ Description: This program receives control for exceptions

ᑍ

within a COBOL run unit. This program is used

in conjunction with CBLERR1.

Any exception causes this error handler to be

called which then logs the software error.

ᑍ

ᑍ APIs Used:

ᑍ

QPDLOGER - Log Software Error

ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

ᑍ

ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

PROGRAM-ID. ERRHDL1.

ENVIRONMENT DIVISION.

CONFIGURATION SECTION.

SOURCE-COMPUTER. IBM-AS4ðð.

OBJECT-COMPUTER. IBM-AS4ðð.

INPUT-OUTPUT SECTION.

DATA DIVISION.

WORKING-STORAGE SECTION.

ᑍ

ᑍ Error Code parameter include. As this sample program

ᑍ uses COPY to include the error code structure, only the first

ᑍ 16 bytes of the error code structure are available. If the

ᑍ application program needs to access the variable length

B-114 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

ᑍ exception data for the error, the developer should physically

ᑍ copy the QSYSINC include and modify the copied include to

ᑍ define additional storage for the exception data.

ᑍ

COPY QUSEC OF QSYSINC-QLBLSRC.

ᑍ

ᑍ Miscellaneous elements

ᑍ

ð1 MISC.

ð5 LOG-EXCEPTION-ID PIC X(12).

ð5 MESSAGE-KEY

PIC X(ð4).

ð5 POINT-OF-FAILURE PIC S9(ð9) BINARY VALUE 1.

ð5 PRINT-JOBLOG PIC X(ð1) VALUE "Y".

ð5 NBR-OF-ENTRIES PIC S9(ð9) BINARY.

ð5 NBR-OF-OBJECTS PIC S9(ð9) BINARY VALUE 1.

ð1 MESSAGE-INFO.

ð5 MSG-OFFSET

ð5 MSG-LENGTH

PIC S9(ð9) BINARY.

ð1 OBJECT-LIST.

ð5 OBJECT-NAME

ð5 LIBRARY-NAME

ð5 OBJECT-TYPE

LINKAGE SECTION.

ð1 CBL-EXCEPTION-ID

ð1 VALID-RESPONSES

ð1 PGM-IN-ERROR.

ð5 PGM-NAME

PIC X(3ð).

PIC X(1ð) VALUE "ᑍPGM

PIC X(ð7).

PIC X(ð6).

PIC X(1ð).

ð5 LIB-NAME

PIC X(1ð).

ð1 SYS-EXCEPTION-ID

ð1 MESSAGE-TEXT

ð1 MESSAGE-LENGTH

ð1 SYS-OPTION

PIC X(ð7).

PIC X(ð1).

PIC S9(ð9) BINARY.

PIC X(ð1).

ᑍ

ᑍ Beginning of mainline

ᑍ

PROCEDURE DIVISION USING CBL-EXCEPTION-ID,

VALID-RESPONSES,

PGM-IN-ERROR,

SYS-EXCEPTION-ID,

MESSAGE-TEXT,

MESSAGE-LENGTH,

SYS-OPTION.

MAIN-LINE.

ᑍ

ᑍ Initialize the error code parameter. To signal exceptions to

ᑍ this program by the API, you need to set the bytes provided

ᑍ field of the error code to zero. Because this program has

ᑍ exceptions sent back through the error code parameter, it sets

ᑍ the bytes provided field to the number of bytes it gives the

ᑍ API for the parameter.

ᑍ

MOVE 16 TO BYTES-PROVIDED.

ᑍ

ᑍ Record the COBOL Exception id

ᑍ

MOVE SYS-EXCEPTION-ID TO LOG-EXCEPTION-ID.

ᑍ

ᑍ Record the length of the message replacement data (if any)

Appendix B. Original Examples in Additional Languages B-115

Download from Www.Somanuals.com. All Manuals Search And Download.

ᑍ

IF MESSAGE-LENGTH > ð

MOVE 1 TO MSG-OFFSET,

MOVE MESSAGE-LENGTH TO MSG-LENGTH,

MOVE 1 TO NBR-OF-ENTRIES,

ELSE

MOVE ð TO MSG-OFFSET,

MOVE ð TO MSG-LENGTH,

MOVE ð TO NBR-OF-ENTRIES.

ᑍ For illustration purposes, dump the program object

ᑍ

MOVE PGM-NAME TO OBJECT-NAME.

MOVE LIB-NAME TO LIBRARY-NAME.

.1/

ᑍ

ᑍ Call the API to log the software error.

ᑍ

CALL "QPDLOGER" USING PGM-NAME,

LOG-EXCEPTION-ID,

MESSAGE-KEY,

POINT-OF-FAILURE,

PRINT-JOBLOG,

MESSAGE-TEXT,

MESSAGE-INFO,

NBR-OF-ENTRIES,

OBJECT-LIST,

NBR-OF-OBJECTS,

QUS-EC.

ᑍ

ᑍ If an exception occurs, the API returns the exception in the

ᑍ error code parameter. The bytes available field is set to

ᑍ zero if no exception occurs and greater than zero if an

ᑍ exception does occur.

ᑍ

IF BYTES-AVAILABLE OF QUS-EC > ð

DISPLAY "Cannot log error".

ᑍ

ᑍ End the current run unit

ᑍ

MOVE "C" TO SYS-OPTION.

STOP RUN.

ᑍ

ᑍ End of MAINLINE

ᑍ

Logging Software Error (OPM API without Pointers)—OPM RPG

Example

Refer to “Logging Software Error (OPM API without Pointers)—ILE C Example” on

page 6-2 for the original example.

Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Fᑍ

Fᑍ Program:

Fᑍ

Fᑍ Language:

Demonstrate use of OPM-based Log Software Error

OPM RPG

B-116 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Fᑍ

Fᑍ Description:

This program performs a divide-by-ð operation

to cause an exception. This exception is

caught using RPG ᑍPSSR support,

and the exception is then logged as a

software error.

Fᑍ

Fᑍ APIs used:

Fᑍ

QPDLOGER

Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Eᑍ

Eᑍ Arrays used to extract source line number where error happened

Eᑍ

SRC

TGT

8 1

Iᑍ

Iᑍ Error Code parameter include. As this sample program uses

Iᑍ /COPY to include the error code structure, only the first

Iᑍ 16 bytes of the error code structure are available. If the

Iᑍ application program needs to access the variable length

Iᑍ exception data for the error, the developer should physically

Iᑍ copy the QSYSINC include and modify the copied include to

Iᑍ define additional storage for the exception data.

Iᑍ

I/COPY QSYSINC/QRPGSRC,QUSEC

Iᑍ

Iᑍ Define Program Status Data Structure

Iᑍ

IPSDS

SDS

1 1ð PGMNAM

11 15ðSTATUS

21 28 SRC

4ð 46 EXCPID

81 9ð LIBNAM

Iᑍ

Iᑍ Some miscellaneous fields

Iᑍ

IMISC

B 1 4ðFAILPT

B 5 8ðDATA#

B 9 12ðOBJS#

13 2ð TGT

13 2ððLIN#C

Iᑍ

Iᑍ DATA represents the data items to report as part of problem

Iᑍ

IDATA

Iᑍ

4ð96

Iᑍ DATAPT defines (via offset and length values) how to read DATA

Iᑍ

IDATAPT

256

B 1 4ðDTAOFF

B 5 8ðDTALEN

Iᑍ

Iᑍ OBJS represents the list of objects to spool as part of problem

Iᑍ

IOBJS

259ð

1 3ð OBJ1N

Appendix B. Original Examples in Additional Languages B-117

Download from Www.Somanuals.com. All Manuals Search And Download.

31 6ð OBJ1L

61 7ð OBJ1T

Cᑍ

Cᑍ Prepare for divide-by-zero situation

Cᑍ

Z-ADD1ð

Z-ADDð

FACT1 5ð

FACT2 5ð

Cᑍ

Cᑍ and divide by ð

Cᑍ

FACT1

DIV FACT2

RESULT 5ð

Cᑍ

Cᑍ should not get here due to divide-by-ð exception

Cᑍ

MOVE '1'

RETRN

ᑍINLR

Cᑍ

Cᑍ Program exception subroutine:

Cᑍ

ᑍPSSR

BEGSR

Cᑍ Make sure we are not catching an exception due to the ᑍPSSR

Cᑍ subroutine itself

Cᑍ

SWITCH

IFEQ ' '

MOVE '1'

Cᑍ

SWITCH 1

Cᑍ Set API error code to work in nonexception mode

Cᑍ

Z-ADD16

QUSBNB

Cᑍ Record the source listing line number that caused the failure

Cᑍ

First, extract the numeric portion of the PSDS line number

Z-ADD8

Z-ADDð

DOWEQ' '

SUB 1

END

DOWGTð

MOVE SRC,X

SUB 1

END

1ð

LIN#C

SRC,X

TGT,Y

Cᑍ

Then record it:

Z-ADDLIN#C

FAILPT

Cᑍ

Cᑍ Record the status code for the failure

Cᑍ

MOVELSTATUS

DATA

Cᑍ Record where to find the status data within DATA

Cᑍ

Z-ADDð

DTAOFF

B-118 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Z-ADD5

Z-ADD1

DTALEN

DATA#

Cᑍ

Cᑍ For illustration purposes also dump the program object as

Cᑍ part of logging the software error

Cᑍ

MOVELPGMNAM

MOVELLIBNAM

MOVEL'ᑍPGM'

Z-ADD1

OBJ1N

OBJ1L

OBJ1T

OBJS#

.1/

Cᑍ

Cᑍ Call the Log Software Error API

Cᑍ

CALL 'QPDLOGER'

PARM

PARM EXCPID

PARM

PGMNAM

MSGID 12

MSGKEY 4

FAILPT

JOBLOG 1

DATA

PARM 'Y'

PARM

DATAPT

DATA#

PARM

OBJS

PARM

OBJS#

PARM

QUSBN

Cᑍ If an error on the API call, then indicate a terminal error

Cᑍ

QUSBNC

IFGT ð

'TERM ERR'DSPLY

END

ELSE

Cᑍ

Cᑍ If error within ᑍPSSR, then indicate ᑍPSSR error

Cᑍ

'ᑍPSSR 'DSPLY

END

Cᑍ

Cᑍ No matter how the program got to the ᑍPPSR, end the program

Cᑍ

MOVE '1'

RETRN

ENDSR

ᑍINLR

Logging Software Error (OPM API without Pointers)—ILE RPG Example

Refer to “Logging Software Error (OPM API without Pointers)—ILE C Example” on

page 6-2 for the original example.

Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Fᑍ

Fᑍ Program:

Demonstrate use of OPM based Log Software Error

Fᑍ

Fᑍ Language:

Fᑍ

ILE RPG

Fᑍ Description: This program performs a divide by ð operation to

Fᑍ

cause an exception. This exception is caught using

RPG's ᑍPSSR support, and the exception is then

Appendix B. Original Examples in Additional Languages B-119

Download from Www.Somanuals.com. All Manuals Search And Download.

Fᑍ

logged as a software error.

Fᑍ APIs used: QPDLOGER

Fᑍ

Dᑍ

Dᑍ Include Error Code Parameter

Dᑍ

D/COPY QSYSINC/QRPGLESRC,QUSEC

Dᑍ

Dᑍ Misc. data elements

Dᑍ

Dfactor1

Dfactor2

Dresult

Dline_nbr

Ddata

Ddatapt

D data_off

D data_len

Ddata#

5B ð INZ(1ð)

5B ð INZ(ð)

5B ð

9B ð

4ð96

9B ð

Dobjl

Dobjl#

259ð

9B ð

Dᑍ

Dᑍ Program status data structure

Dᑍ

DPSDS

SDS

D pgm_name

D status

D src_line

D exception

D lib_name

Cᑍ

4ð

1ð

15 ð

9ð

Cᑍ Attempt to divide by ð

Cᑍ

factor1

div

factor2

result

Cᑍ

Cᑍ Should not get here due to divide by ð exception

Cᑍ

move

return

'1'

ᑍINLR

Cᑍ

Cᑍ Program exception subroutine:

Cᑍ

ᑍPSSR

BEGSR

Cᑍ Make sure we are not catching an exception due to the ᑍPSSR

Cᑍ subroutine itself

Cᑍ

switch

ifeq

move

' '

'1'

Cᑍ

switch

Cᑍ Set API error code to work in non-exception mode

Cᑍ

eval

qusbprv = %size(qusec)

Cᑍ Record line number where error happened

Cᑍ

B-120 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

move

src_line

line_nbr

data

Cᑍ

Cᑍ Record the status code as data

Cᑍ

movel

status

Cᑍ Record where status located in data

Cᑍ

eval

data_off = 1

data_len = 5

data# = 1

Cᑍ

Cᑍ For illustration purposes, dump the program object

Cᑍ

eval

%SUBST(objl:1:3ð) = pgm_name .1/

%SUBST(objl:31:3ð) = lib_name

%SUBST(objl:61:1ð) = 'ᑍPGM'

objl# = 1

Cᑍ

Cᑍ Call the Report Software Error API

Cᑍ

call

parm

'QPDLOGER'

pgm_name

msgid

msgkey

line_nbr

joblog

data

exception

'Y'

datapt

data#

objl

objl#

qusec

Cᑍ If an error on the API call, then indicate a terminal error

Cᑍ

qusbavl

ifgt

'Terminal err'dsply

end

else

Cᑍ

Cᑍ If error within ᑍPSSR, then indicate ᑍPSSR error

Cᑍ

'ᑍPSSR error' dsply

end

Cᑍ

Cᑍ No matter how the program got to the ᑍPSSR, end the program

Cᑍ

move

return

endsr

'1'

ᑍinlr

Appendix B. Original Examples in Additional Languages B-121

Download from Www.Somanuals.com. All Manuals Search And Download.

ILE API with Pointers—Examples

This section includes the examples in “Reporting Software Error (ILE API with

Pointers)—ILE C Example” on page 6-7.

Reporting Software Error (ILE API with Pointers)—ILE COBOL Example

Refer to “Reporting Software Error (ILE API with Pointers)—ILE C Example” on

page 6-7 for the original example. This example uses two programs: CBLERR2

causes the error, and ERRHDL2 shows how to report the software error using the

QPDLOGER API.

CBLERR2 Program

PROCESS NOMONOPRC.

IDENTIFICATION DIVISION.

ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

ᑍ

ᑍ Program:

Cause a decimal data exception to demonstrate

logging of software errors

ᑍ

ᑍ Language:

ᑍ

ILE COBOL

ᑍ Description: This program registers an ILE COBOL Error

ᑍ

Handler. After the successful completion of

the registration of the error handler, this

program creates a decimal data error. This

exception causes the error handler to be

called which then logs the software error.

ᑍ

ᑍ APIs Used:

QlnSetCobolErrorHandler

ᑍ

ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

ᑍ

ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

PROGRAM-ID. CBLERR2.

ENVIRONMENT DIVISION.

CONFIGURATION SECTION.

SOURCE-COMPUTER. IBM-AS4ðð.

OBJECT-COMPUTER. IBM-AS4ðð.

SPECIAL-NAMES.

LINKAGE TYPE PROCEDURE FOR "QlnSetCobolErrorHandler".

INPUT-OUTPUT SECTION.

FILE-CONTROL.

DATA DIVISION.

WORKING-STORAGE SECTION.

ᑍ

ᑍ Error Code parameter include. As this sample program

ᑍ uses COPY to include the error code structure, only the first

ᑍ 16 bytes of the error code structure are available. If the

ᑍ application program needs to access the variable length

ᑍ exception data for the error, the developer should physically

ᑍ copy the QSYSINC include and modify the copied include to

ᑍ define additional storage for the exception data.

ᑍ

B-122 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

COPY QUSEC OF QSYSINC-QCBLLESRC.

ᑍ

ᑍ Miscellaneous elements

ᑍ

ð1 MISC.

ð5 Y

PIC S9(ð9) VALUE ð.

PROCEDURE-POINTER.

ð1 ERROR-HANDLER

ð1 OLD-ERROR-HANDLER PROCEDURE-POINTER.

ð1 NUMERIC-GROUP.

ð5 X

PIC 9(ð3).

ᑍ

ᑍ Beginning of mainline

ᑍ

PROCEDURE DIVISION.

MAIN-LINE.

ᑍ

ᑍ Register the COBOL Error Handler.

ᑍ

ᑍ Initialize the error code parameter. To signal exceptions to

ᑍ this program by the API, you need to set the bytes provided

ᑍ field of the error code to zero. Because this program has

ᑍ exceptions sent back through the error code parameter, it sets

ᑍ the bytes provided field to the number of bytes it gives the

ᑍ API for the parameter.

ᑍ

MOVE 16 TO BYTES-PROVIDED.

ᑍ

ᑍ Set ERROR-HANDLER procedure pointer to entry point of

ᑍ ERRHDL1 ᑍPGM

ᑍ

SET ERROR-HANDLER TO ENTRY LINKAGE PROGRAM "ERRHDL2".

ᑍ

ᑍ Call the API to register the exit point.

ᑍ

CALL "QlnSetCobolErrorHandler" USING ERROR-HANDLER,

OLD-ERROR-HANDLER,

QUS-EC.

ᑍ

ᑍ If an exception occurs, the API returns the exception in the

ᑍ error code parameter. The bytes available field is set to

ᑍ zero if no exception occurs and greater than zero if an

ᑍ exception does occur.

ᑍ

IF BYTES-AVAILABLE > ð

DISPLAY "Error setting handler",

STOP RUN.

ᑍ

ᑍ If the call to register an error handler is successful, then

ᑍ cause a the data decimal error (X is initialized to blanks).

ᑍ

ADD X TO Y.

ᑍ

ᑍ Should not get here due to data decimal error

ᑍ

STOP RUN.

ᑍ

ᑍ End of MAINLINE

Appendix B. Original Examples in Additional Languages B-123

Download from Www.Somanuals.com. All Manuals Search And Download.

ᑍ

ERRHDL2 Program

PROCESS NOMONOPRC.

IDENTIFICATION DIVISION.

ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

ᑍ

ᑍ Program:

Log a software error

ᑍ

ᑍ Language:

ᑍ

ILE COBOL

ᑍ Description: This program receives control for exceptions

ᑍ

within a COBOL run unit. This program is used

in conjunction with CBLERR2.

Any exception causes this error handler to be

called which then logs the software error.

ᑍ

ᑍ APIs Used:

ᑍ

QpdReportSoftwareError

ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

ᑍ

ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

PROGRAM-ID. ERRHDL2.

ENVIRONMENT DIVISION.

CONFIGURATION SECTION.

SOURCE-COMPUTER. IBM-AS4ðð.

OBJECT-COMPUTER. IBM-AS4ðð.

SPECIAL-NAMES.

LINKAGE TYPE PROCEDURE FOR "QpdReportSoftwareError".

INPUT-OUTPUT SECTION.

FILE-CONTROL.

DATA DIVISION.

WORKING-STORAGE SECTION.

ᑍ

ᑍ Error Code parameter include. As this sample program

ᑍ uses COPY to include the error code structure, only the first

ᑍ 16 bytes of the error code structure are available. If the

ᑍ application program needs to access the variable length

ᑍ exception data for the error, the developer should physically

ᑍ copy the QSYSINC include and modify the copied include to

ᑍ define additional storage for the exception data.

ᑍ

COPY QUSEC OF QSYSINC-QCBLLESRC.

ᑍ

ᑍ QpdReportSoftwareError include

ᑍ

COPY QPDSRVPG OF QSYSINC-QCBLLESRC.

ᑍ

ᑍ Miscellaneous elements

ᑍ

ð1 MISC.

ð5 NBR-OF-RECORDS PIC S9(ð9) BINARY VALUE ð.

ð5 MSG-KEYWORD

PIC X(ð3) VALUE "MSG".

ð1 PROBLEM-RECORDS.

ð5 PROBLEM-POINTER POINTER OCCURS 1ðð TIMES.

LINKAGE SECTION.

B-124 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

ð1 CBL-EXCEPTION-ID

ð1 VALID-RESPONSES

ð1 PGM-IN-ERROR.

ð5 PGM-NAME

PIC X(ð7).

PIC X(ð6).

PIC X(1ð).

PIC X(ð7).

PIC X(ð1).

PIC S9(ð9) BINARY.

PIC X(ð1).

PIC X(1ð).

PIC X(256).

ð5 LIB-NAME

ð1 SYS-EXCEPTION-ID

ð1 MESSAGE-TEXT

ð1 MESSAGE-LENGTH

ð1 SYS-OPTION

ð1 ERR-MODULE-NAME

ð1 CBL-PGM-NAME

ᑍ

ᑍ Beginning of mainline

ᑍ

PROCEDURE DIVISION USING CBL-EXCEPTION-ID,

VALID-RESPONSES,

PGM-IN-ERROR,

SYS-EXCEPTION-ID,

MESSAGE-LENGTH,

SYS-OPTION,

MESSAGE-TEXT,

ERR-MODULE-NAME,

CBL-PGM-NAME.

MAIN-LINE.

ᑍ

ᑍ Initialize the error code parameter. To signal exceptions to

ᑍ this program by the API, you need to set the bytes provided

ᑍ field of the error code to zero. Because this program has

ᑍ exceptions sent back through the error code parameter, it sets

ᑍ the bytes provided field to the number of bytes it gives the

ᑍ API for the parameter.

ᑍ

MOVE 16 TO BYTES-PROVIDED.

ᑍ

ᑍ Record the COBOL Program and Library names

ᑍ

MOVE 1ð1 TO KEY-FIELD OF QPD-SUSPECTED-PROGRAM.

MOVE 1ð TO PROGRAM-NAME-LENGTH OF QPD-SUSPECTED-PROGRAM.

MOVE 1ð TO LIBRARY-NAME-LENGTH OF QPD-SUSPECTED-PROGRAM.

SET PROGRAM-NAME OF QPD-SUSPECTED-PROGRAM

TO ADDRESS OF PGM-NAME OF PGM-IN-ERROR.

SET LIBRARY-NAME OF QPD-SUSPECTED-PROGRAM

TO ADDRESS OF LIB-NAME OF PGM-IN-ERROR.

ADD 1 TO NBR-OF-RECORDS.

SET PROBLEM-POINTER (NBR-OF-RECORDS) TO

ADDRESS OF QPD-SUSPECTED-PROGRAM.

.2/

ᑍ

ᑍ Record the message id

ᑍ

MOVE 2ðð TO KEY-FIELD OF QPD-SYMPTOM.

MOVE 3 TO KEYWORD-LENGTH OF QPD-SYMPTOM.

MOVE 7 TO DATA-LENGTH OF QPD-SYMPTOM.

MOVE "C" TO DATA-TYPE OF QPD-SYMPTOM.

SET KEYWORD OF QPD-SYMPTOM TO ADDRESS OF MSG-KEYWORD.

SET DATA-FIELD OF QPD-SYMPTOM TO ADDRESS OF SYS-EXCEPTION-ID.

ADD 1 TO NBR-OF-RECORDS.

SET PROBLEM-POINTER (NBR-OF-RECORDS) TO

ADDRESS OF QPD-SYMPTOM.

Appendix B. Original Examples in Additional Languages B-125

Download from Www.Somanuals.com. All Manuals Search And Download.

ᑍ

ᑍ For illustration purposes, dump the program object

ᑍ

MOVE 3ð2 TO KEY-FIELD OF QPD-NAMED-SYSTEM-OBJECT.

MOVE PGM-NAME OF PGM-IN-ERROR

TO OBJECT-NAME OF QPD-NAMED-SYSTEM-OBJECT.

MOVE LIB-NAME OF PGM-IN-ERROR

TO OBJECT-LIBRARY OF QPD-NAMED-SYSTEM-OBJECT.

MOVE "ᑍPGM" TO OBJECT-TYPE OF QPD-NAMED-SYSTEM-OBJECT.

ADD 1 TO NBR-OF-RECORDS.

SET PROBLEM-POINTER (NBR-OF-RECORDS) TO

ADDRESS OF QPD-NAMED-SYSTEM-OBJECT.

ᑍ

ᑍ Call the API to log the software error.

ᑍ

CALL "QpdReportSoftwareError" USING PROBLEM-RECORDS,

NBR-OF-RECORDS,

QUS-EC.

ᑍ

ᑍ If an exception occurs, the API returns the exception in the

ᑍ error code parameter. The bytes available field is set to

ᑍ zero if no exception occurs and greater than zero if an

ᑍ exception does occur.

ᑍ

IF BYTES-AVAILABLE > ð DISPLAY "Cannot log error".

ᑍ

ᑍ End the current run unit

ᑍ

MOVE "C" TO SYS-OPTION.

STOP RUN.

ᑍ

ᑍ End of MAINLINE

ᑍ

Reporting Software Error (ILE API with Pointers)—ILE RPG Example

Refer to “Reporting Software Error (ILE API with Pointers)—ILE C Example” on

page 6-7 for the original example.

Fᑍ

Fᑍ Program:

Demonstrate use of ILE-based Report Software Error

Fᑍ

Fᑍ Language:

Fᑍ

ILE RPG

Fᑍ Description: This program performs a divide-by-ð operation to

Fᑍ

cause an exception. This exception is caught using

RPGs ᑍPSSR support, and the exception is then logged

as a software error.

Fᑍ APIs used: QpdReportSoftwareError

Fᑍ

Dᑍ

Dᑍ Include Error Code Parameter

Dᑍ

D/COPY QSYSINC/QRPGLESRC,QUSEC

Dᑍ

B-126 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Dᑍ Include API structures and constants

Dᑍ

D/COPY QSYSINC/QRPGLESRC,QPDSRVPG

Dᑍ

Dᑍ Array of problem record description pointers and index to array

Dᑍ

Dpdr

Dᑍ

ᑍ dim(2ð)

5B ð INZ(1)

Dᑍ Misc. data elements

Dᑍ

Dfactor1

Dfactor2

Dresult

Drc

5B ð INZ(1ð)

5B ð INZ(ð)

5B ð

INZ('RC')

Dᑍ

Dᑍ Program status data structure

Dᑍ

DPSDS

SDS

D pgm_name

D status

D src_line

D exception

D lib_name

Cᑍ

4ð

1ð

15 ð

9ð

Cᑍ Attempt to divide by ð

Cᑍ

factor1

div

factor2

result

Cᑍ

Cᑍ Should not get here due to divide-by-ð exception

Cᑍ

move

return

'1'

ᑍINLR

Cᑍ

Cᑍ Program exception subroutine:

Cᑍ

ᑍPSSR

BEGSR

Cᑍ Make sure we are not catching an exception due to the ᑍPSSR

Cᑍ subroutine itself

Cᑍ

switch

ifeq

move

' '

'1'

Cᑍ

switch

Cᑍ Set API error code to work in nonexception mode

Cᑍ

eval

qusbprv = %size(qusec)

Cᑍ Record the suspected program and library name

Cᑍ

eval

qpdkð1 = 1ð1

qpdpgmnl = %SIZE(pgm_name)

qpdlibnl = %SIZE(lib_name)

qpdpgmn = %ADDR(pgm_name) .2/

qpdlibn = %ADDR(lib_name)

Cᑍ

and record the key:

Appendix B. Original Examples in Additional Languages B-127

Download from Www.Somanuals.com. All Manuals Search And Download.

eval

pdr(x) = %addr(qpdspgm)

x = x + 1

Cᑍ

Cᑍ Record the failing source statement number

Cᑍ

eval

qpdkð7 = 2ðð

qpdkl = %SIZE(rc)

qpddl = %SIZE(src_line)

qpddt = 'C'

qpdkð8 = %ADDR(rc)

qpdd = %ADDR(src_line)

Cᑍ

and record the key:

eval

pdr(x) = %addr(qpds)

x = x + 1

Cᑍ

Cᑍ Record the status code as data

Cᑍ

eval

qpdk11 = 3ð1

qpddlðð = %SIZE(status)

qpddi = 1

qpddðð = %ADDR(status)

Cᑍ

and record the key:

eval

pdr(x) = %addr(qpds)

x = x + 1

Cᑍ

Cᑍ For illustration purposes, dump the program object

Cᑍ

eval

qpdk12 = 3ð2

qpdobjn = pgm_name

qpdobjlib = lib_name

qpdobjt = 'ᑍPGM'

Cᑍ

and record the key:

eval

pdr(x) = %addr(qpdnsot)

x = x + 1

Cᑍ

Cᑍ Call the Report Software Error API

Cᑍ

callb

parm

qpdrse

pdr

qusec

Cᑍ

Cᑍ If an error on the API call, then indicate a terminal error

Cᑍ

qusbavl

ifgt

'Terminal err'dsply

Cᑍ

end

else

Cᑍ If error within ᑍPSSR, then indicate ᑍPSSR error

Cᑍ

'ᑍPSSR error' dsply

B-128 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Cᑍ

end

Cᑍ No matter how the program got to the ᑍPSSR, end the program

Cᑍ

move

return

endsr

'1'

ᑍinlr

Program for Packaging a Product—Examples

This section includes the examples in “Packaging Your Own Software Products” on

page A-1.

Program for Packaging a Product—ILE C Example

Refer to “Program for Packaging a Product—OPM RPG Example” on page A-3 for

the original example.

/ᑍ Program Name:

SFTWPRDEX

ᑍ/

/ᑍ

/ᑍ Program Language:

ILE C

/ᑍ

/ᑍ Description:

This example shows you the steps necessaryᑍ/

to package your product like IBM's.

/ᑍ

ᑍ/

/ᑍ Header Files Included: <stdlib.h>

/ᑍ

<signal.h>

<string.h>

<stdio.h>

/ᑍ

<qszcrtpd.h>

<qszcrtpl.h>

<qszpkgpo.h>

<qlicobjd.h>

<qusec.h>

/ᑍ

<qliept.h>

/ᑍ

/ᑍ APIs Used:

QSZCRTPD - Create Product Definition

QSZCRTPL - Create Product Load

QSZPKGPO - Package Product Option

QLICOBJD - Change Object Description

/ᑍ

#include <stdlib.h>

#include <signal.h>

#include <string.h>

#include <stdio.h>

#include <qszcrtpd.h>

#include <qszcrtpl.h>

#include <qszpkgpo.h>

#include <qlicobjd.h>

#include <qusec.h>

#include <qliept.h>

/ᑍ Function:

Create_Prod_Def_Obj

ᑍ/

/ᑍ Description: Create the product definition ABCðð5ð for product ᑍ/

/ᑍ

ABC.

ᑍ/

Appendix B. Original Examples in Additional Languages B-129

Download from Www.Somanuals.com. All Manuals Search And Download.

void Create_Prod_Def_Obj()

{

Qsz_Prd_Inf_t prod_info;

Qsz_Prd_Opt_t prod_opt_list;

Qsz_Lng_Lod_t prod_lang_load;

Qus_EC_t error_code;

char text_desc[5ð];

/ᑍ Product information

/ᑍ Product option list

ᑍ/

/ᑍ Product language load list ᑍ/

/ᑍ Error code parameter

/ᑍ Text description

ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ Fill in the product information. ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

memset(&prod_info,' ',sizeof(prod_info));

memcpy(prod_info.PID,"ðABCABC",7);

memcpy(prod_info.Rls_Lvl,"V3R1Mð",6);

memcpy(prod_info.Msg_File,"ABCMSG

",1ð);

memcpy(prod_info.Fst_Cpyrt,"ᑍCURRENT ",1ð);

memcpy(prod_info.Cur_Cpyrt,"ᑍCURRENT ",1ð);

memcpy(prod_info.Rls_Date,"9412ð1",6);

memcpy(prod_info.Alw_Mult_Rls,"ᑍNO ",4);

memcpy(prod_info.Reg_ID_Type,"ᑍPHONE

memcpy(prod_info.Reg_ID_Val,"5ð7253ð927

",1ð);

",14);

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ Fill in the product option list. ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

memset(&prod_opt_list,' ',sizeof(prod_opt_list));

memcpy(prod_opt_list.Opt,"ðððð",4);

memcpy(prod_opt_list.Msg_ID,"ABCððð1",7);

memcpy(prod_opt_list.Alw_Dyn_Nam,"ᑍNODYNNAM ",1ð);

memcpy(prod_opt_list.Cod_Lod,"5ðð1",4);

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ Fill in the product language load list.

ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

memset(&prod_lang_load,' ',sizeof(prod_lang_load));

memcpy(prod_lang_load.Lng_Lod,"2924

memcpy(prod_lang_load.Opt,"ðððð",4);

",8);

memset(text_desc,' ',5ð);

memcpy(text_desc,"Product ABC",11);

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ Initialize the error code to have the API send errors through ᑍ/

/ᑍ the error code parameter.

ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

error_code.Bytes_Provided=sizeof(error_code);

QSZCRTPD("ABCðð5ð ABC

&prod_info,

&prod_opt_list,

", /ᑍ Product definition name

/ᑍ Product definition info

/ᑍ Product option list

/ᑍ Number of options

/ᑍ Language load list

/ᑍ Number languages

ᑍ/

&prod_lang_load,

text_desc,

/ᑍ Text description

"ᑍUSE

/ᑍ Public authority

/ᑍ Error code

&error_code);

if (error_code.Bytes_Available > ð)

{

printf("Failed in QSZCRTPD API with error: %.7s",

error_code.Exception_Id);

B-130 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

exit(1);

}

/ᑍ Function: Create_Prod_Load_Obj ᑍ/

/ᑍ Description: Create the product loads ABCðð5ð (MRM object) and ᑍ/

/ᑍ

ABCðð29 (MRI object) for product ABC.

ᑍ/

void Create_Prod_Load_Obj()

{

Qsz_Lod_Inf_t prod_load_info;

Qsz_Lib_Inf_t prin_lib_info;

Qsz_Add_Lib_t add_libs;

Qsz_Pre_Ext_t preop_expgm;

Qsz_Flr_Lst_t folder_list;

Qus_EC_t error_code;

/ᑍ Product load information

/ᑍ Principal library info

/ᑍ Additional library list

ᑍ/

/ᑍ Preoperational exit program ᑍ/

/ᑍ Folder list

/ᑍ Error code parameter

/ᑍ Text description

ᑍ/

char text_desc[5ð];

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ Fill in the product load information. ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

memset(&prod_load_info,' ',sizeof(prod_load_info));

memcpy(prod_load_info.PID,"ðABCABC",7);

memcpy(prod_load_info.Rls_Lvl,"V3R1Mð",6);

memcpy(prod_load_info.Opt,"ðððð",4);

memcpy(prod_load_info.Lod_Type,"ᑍCODE

",1ð);

memcpy(prod_load_info.Lod_ID,"ᑍCODEDFT",8);

memcpy(prod_load_info.Reg_ID_Type,"ᑍPRDDFN ",1ð);

memcpy(prod_load_info.Min_Tgt_Rls,"ᑍCURRENT ",1ð);

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ Fill in the principal library information. There are no

/ᑍ additional libraries.

ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

memcpy(prin_lib_info.Dev_Lib,"ABC

memcpy(prin_lib_info.Prim_Lib,"ABC

",1ð);

memcpy(prin_lib_info.Post_Exit_Pgm,"ABCPGMMRM2",1ð);

memset(&add_libs,' ',sizeof(add_libs));

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ Fill in the preoperational exit program.

ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

memcpy(preop_expgm.Pre_Ext_Pgm,"ABCPGMMRM1",1ð);

memcpy(preop_expgm.Dev_Lib,"ABC

",1ð);

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ There are no folders. ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

memset(&folder_list,' ',sizeof(folder_list));

memset(text_desc,' ',5ð);

memcpy(text_desc,"Product ABC",11);

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ Initialize the error code to have the API send errors through ᑍ/

Appendix B. Original Examples in Additional Languages B-131

Download from Www.Somanuals.com. All Manuals Search And Download.

/ᑍ the error code parameter.

ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

error_code.Bytes_Provided=sizeof(error_code);

QSZCRTPL("ABCðð5ð ",

&prod_load_info,

/ᑍ Product load name

ᑍ/

/ᑍ Product load information

/ᑍ Secondary language lib name ᑍ/

/ᑍ Principal library

/ᑍ Additional libraries

&prin_lib_info,

&add_libs,

ð,

&preop_expgm,

&folder_list,

ð,

ᑍ/

/ᑍ Number of additional libs ᑍ/

/ᑍ Preoperational exit program ᑍ/

/ᑍ Number of preop exit pgms ᑍ/

/ᑍ Folder list

ᑍ/

/ᑍ Number of folders

/ᑍ Text description

/ᑍ Public authority

/ᑍ Error code

text_desc,

"ᑍUSE

&error_code);

if (error_code.Bytes_Available > ð)

{

printf("Failed in QSZCRTPL API with error: %.7s",

error_code.Exception_Id);

exit(1);

}

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ Fill in the product load information. ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

memcpy(prod_load_info.Lod_Type,"ᑍLNG

memcpy(prod_load_info.Lod_ID,"2924

",1ð);

",8);

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ Fill in the principal library information. There are no

/ᑍ additional libraries.

ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

memcpy(prin_lib_info.Post_Exit_Pgm,"ABCPGMMRI2",1ð);

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ Fill in the preoperational exit program.

ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

memcpy(preop_expgm.Pre_Ext_Pgm,"ABCPGMMRI1",1ð);

QSZCRTPL("ABCðð29 ",

&prod_load_info,

"ABC2924 ",

&prin_lib_info,

&add_libs,

ð,

/ᑍ Product load name

ᑍ/

/ᑍ Product load information

/ᑍ Secondary language lib name ᑍ/

/ᑍ Principal library

/ᑍ Additional libraries

ᑍ/

/ᑍ Number of additional libs ᑍ/

/ᑍ Preoperational exit program ᑍ/

/ᑍ Number of preop exit pgms ᑍ/

&preop_expgm,

&folder_list,

ð,

/ᑍ Folder list

ᑍ/

/ᑍ Number of folders

/ᑍ Text description

/ᑍ Public authority

/ᑍ Error code

text_desc,

"ᑍUSE

&error_code);

if (error_code.Bytes_Available > ð)

{

printf("Failed in QSZCRTPL API with error: %.7s",

B-132 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

error_code.Exception_Id);

exit(1);

}

/ᑍ Function:

Change_Obj_Descr

ᑍ/

/ᑍ Description: Change object descriptions for all objects

/ᑍ

that make up Product ABC. Currently there are 15 ᑍ/

objects. ᑍ/

void Change_Obj_Descr()

{

typedef struct {

char obj_name_lib[21];

char obj_type[11];

char prd_opt_id[5];

char prd_opt_ld[5];

char lp_id[4];

} obj_info_t;

typedef struct {

int numkey;

Qus_Vlen_Rec_3_t PID_rec;

char PID[4];

Qus_Vlen_Rec_3_t LID_rec;

char LID[4];

Qus_Vlen_Rec_3_t LP_rec;

char LP[13];

} change_obj_info_t;

int i;

obj_info_t obj_info[15] = {"ABCPGMMRM1ABC

","ᑍPGM

"ðððð","5ðð1","ðABCABCV3R1Mð",

"ABCPGMMRM2ABC ","ᑍPGM

"ðððð","5ðð1","ðABCABCV3R1Mð",

"ABCPGMMRI1ABC ","ᑍPGM

"ðððð","2924","ðABCABCV3R1Mð",

"ABCPGMMRI2ABC ","ᑍPGM

"ðððð","2924","ðABCABCV3R1Mð",

"ABCPGM ABC ","ᑍPGM

"ðððð","5ðð1","ðABCABCV3R1Mð",

"QCLSRC ABC ","ᑍFILE

"ðððð","2924","ðABCABCV3R1Mð",

"ABCDSPF ABC ","ᑍFILE

"ðððð","2924","ðABCABCV3R1Mð",

"ABCPF ABC ","ᑍFILE

"ðððð","2924","ðABCABCV3R1Mð",

"ABCMSG ABC ","ᑍMSGF

"ðððð","2924","ðABCABCV3R1Mð",

"ABC ABC ","ᑍCMD

"ðððð","2924","ðABCABCV3R1Mð",

"ABCPNLGRP ABC ","ᑍPNLGRP ",

"ðððð","2924","ðABCABCV3R1Mð",

"ABCðð5ð ABC

","ᑍPRDDFN ",

"ðððð","5ðð1","ðABCABCV3R1Mð",

"ABCðð5ð ABC

","ᑍPRDLOD ",

Appendix B. Original Examples in Additional Languages B-133

Download from Www.Somanuals.com. All Manuals Search And Download.

"ðððð","5ðð1","ðABCABCV3R1Mð",

"ABCðð29 ABC

","ᑍPRDLOD ",

"ðððð","2924","ðABCABCV3R1Mð",

"ABC

ABC

","ᑍLIB

"ðððð","5ðð1","ðABCABCV3R1Mð"};

/ᑍ Change object information ᑍ/

change_obj_info_t cobji;

Qus_EC_t error_code;

char rtn_lib[1ð];

/ᑍ Error code parameter

/ᑍ Return library

ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ Fill in the changed object information. ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

cobji.numkey=3;

cobji.PID_rec.Key=13;

cobji.PID_rec.Length_Vlen_Record=4;

cobji.LID_rec.Key=12;

cobji.LID_rec.Length_Vlen_Record=4;

cobji.LP_rec.Key=5;

cobji.LP_rec.Length_Vlen_Record=13;

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ Initialize the error code to have the API send errors through ᑍ/

/ᑍ the error code parameter.

ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

error_code.Bytes_Provided=sizeof(error_code);

for (i=ð; i<15; i++)

{

memcpy(cobji.PID,obj_info[i].prd_opt_id,4);

memcpy(cobji.LID,obj_info[i].prd_opt_ld,4);

memcpy(cobji.LP,obj_info[i].lp_id,13);

QLICOBJD(rtn_lib,

/ᑍ Return library

ᑍ/

obj_info[i].obj_name_lib, /ᑍ Object name

obj_info[i].obj_type,

&cobji,

&error_code);

/ᑍ Object type

/ᑍ Changed object informationᑍ/

/ᑍ Error code ᑍ/

if (error_code.Bytes_Available > ð)

{

printf("Failed in QLICOBJD API with error: %.7s",

error_code.Exception_Id);

exit(1);

}

/ᑍ Function:

Package_Prod

ᑍ/

/ᑍ Description: Package Product ABC so that all the SAVLICPGM,

/ᑍ

RSTLICPGM and DLTLICPGM commands work with the

product.

void Package_Prod()

{

Qsz_Prd_Opt_Inf_t prod_opt_info; /ᑍ Product option information ᑍ/

Qus_EC_t error_code;

/ᑍ Error code parameter

ᑍ/

B-134 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ Fill in the product option information. ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

memset(&prod_opt_info,' ',sizeof(prod_opt_info));

memcpy(prod_opt_info.Opt,"ðððð",4);

memcpy(prod_opt_info.PID,"ðABCABC",7);

memcpy(prod_opt_info.Rls_Lvl,"V3R1Mð",6);

memcpy(prod_opt_info.Lod_ID,"ᑍALL

",8);

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ Initialize the error code to have the API send errors through ᑍ/

/ᑍ the error code parameter.

ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

error_code.Bytes_Provided=sizeof(error_code);

QSZPKGPO(&prod_opt_info,

"ᑍYES",

/ᑍ Product option information ᑍ/

/ᑍ Repackage

ᑍ/

"ᑍNO ",

/ᑍ Allow object change

/ᑍ Error code

&error_code);

if (error_code.Bytes_Available > ð)

{

printf("Failed in QSZPKGPO API with error: %.7s",

error_code.Exception_Id);

exit(1);

}

/ᑍ Start of main procedure

ᑍ/

void main()

{

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ Create Product Definition Object

ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

Create_Prod_Def_Obj();

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ Create Product Load Objects

ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

Create_Prod_Load_Obj();

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ Change Object Description

ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

Change_Obj_Descr();

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

/ᑍ Package Product ABC

ᑍ/

/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/

Package_Prod();

}

Appendix B. Original Examples in Additional Languages B-135

Download from Www.Somanuals.com. All Manuals Search And Download.

Program for Packaging a Product—ILE COBOL Example

Refer to “Program for Packaging a Product—OPM RPG Example” on page A-3 for

the original example. The following program also works for OPM COBOL.

IDENTIFICATION DIVISION.

ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

ᑍ

ᑍProgram Name: SFTWPRDEX

ᑍ

ᑍLanguage: COBOL

ᑍ

ᑍDescriptive Name: Software Product Example

ᑍ

ᑍDescription: This example shows you the steps necessary to

ᑍ

package your product like IBM products.

ᑍHeader Files Included: QUSEC

- Error Code Parameter

ᑍ

QSZCRTPD - Create Product Definition API

QSZCRTPL - Create Product Load API

QSZPKGPO - Package Product Option API

ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

ᑍ

PROGRAM-ID. SFTWPRDEX.

ENVIRONMENT DIVISION.

CONFIGURATION SECTION.

SOURCE-COMPUTER. IBM-AS4ðð.

OBJECT-COMPUTER. IBM-AS4ðð.

INPUT-OUTPUT SECTION.

FILE-CONTROL.

SELECT LISTING ASSIGN TO PRINTER-QPRINT

ORGANIZATION IS SEQUENTIAL.

DATA DIVISION.

FILE SECTION.

FD LISTING RECORD CONTAINS 132 CHARACTERS

LABEL RECORDS ARE STANDARD

DATA RECORD IS LIST-LINE.

ð1 LIST-LINE

PIC X(132).

ᑍ

WORKING-STORAGE SECTION.

ᑍ Error Code parameter include. As this sample program

ᑍ uses COPY to include the error code structure, only the first

ᑍ 16 bytes of the error code structure are available. If the

ᑍ application program needs to access the variable length

ᑍ exception data for the error, the developer should physically

ᑍ copy the QSYSINC include and modify the copied include to

ᑍ define additional storage for the exception data.

ᑍ

COPY QUSEC OF QSYSINC-QLBLSRC.

ᑍ

ᑍ Create Product Definition API Include

ᑍ

B-136 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

COPY QSZCRTPD OF QSYSINC-QLBLSRC.

ᑍ

ᑍ Create Product Load API Include

ᑍ

COPY QSZCRTPL OF QSYSINC-QLBLSRC.

ᑍ

ᑍ Package Product Option API Include

ᑍ

COPY QSZPKGPO OF QSYSINC-QLBLSRC.

ᑍ

ᑍ Error message text

ᑍ

ð1 BAD-NEWS.

ð5 TEXT1

PIC X(14) VALUE "Failed in API ".

ð5 API-NAME

ð5 TEXT2

ð5 EXCEPTION-ID PIC X(ð7).

PIC X(1ð).

PIC X(11) VALUE "with error ".

ᑍ

ᑍ Compile Time Array

ᑍ

ð1 OBJ-INFO.

ð5 ELEMENT-ð1 PIC X(41)

VALUE "ABCPGMMRM1ᑍPGM

ð5 ELEMENT-ð2 PIC X(41)

VALUE "ABCPGMMRM2ᑍPGM

ð5 ELEMENT-ð3 PIC X(41)

VALUE "ABCPGMMRI1ᑍPGM

ð5 ELEMENT-ð4 PIC X(41)

VALUE "ABCPGMMRI2ᑍPGM

ðððð5ðð1ðABCABCV3R1Mð".

ðððð2924ðABCABCV3R1Mð".

ðððð5ðð1ðABCABCV3R1Mð".

ðððð2924ðABCABCV3R1Mð".

ð5 ELEMENT-ð5 PIC X(41)

VALUE "ABCPGM

ᑍPGM

ð5 ELEMENT-ð6 PIC X(41)

VALUE "QCLSRC

ᑍFILE

ð5 ELEMENT-ð7 PIC X(41)

VALUE "ABCDSPF ᑍFILE

ð5 ELEMENT-ð8 PIC X(41)

VALUE "ABCPF

ð5 ELEMENT-ð9 PIC X(41)

VALUE "ABCMSG

ð5 ELEMENT-1ð PIC X(41)

VALUE "ABC

ð5 ELEMENT-11 PIC X(41)

ᑍFILE

ᑍMSGF

ᑍCMD

VALUE "ABCPNLGRP ᑍPNLGRP ðððð2924ðABCABCV3R1Mð".

ð5 ELEMENT-12 PIC X(41)

VALUE "ABCðð5ð ᑍPRDDFN ðððð5ðð1ðABCABCV3R1Mð".

ð5 ELEMENT-13 PIC X(41)

VALUE "ABCðð5ð ᑍPRDLOD ðððð5ðð1ðABCABCV3R1Mð".

ð5 ELEMENT-14 PIC X(41)

VALUE "ABCðð29 ᑍPRDLOD ðððð2924ðABCABCV3R1Mð".

ð5 ELEMENT-15 PIC X(41)

VALUE "ABC

ᑍLIB

ðððð5ðð1ðABCABCV3R1Mð".

ᑍ

ð1 OBJECT-TABLE REDEFINES OBJ-INFO.

ð5 OBJ-INFO-I OCCURS 15 TIMES.

1ð OBJ-NAME

1ð OBJ-TYPE

1ð PRD-OPT-ID

1ð PRD-OPT-LD

PIC X(1ð).

PIC X(ð4).

Appendix B. Original Examples in Additional Languages B-137

Download from Www.Somanuals.com. All Manuals Search And Download.

1ð LP-ID

PIC X(13).

ᑍ

ᑍ Change Object Information parameter

ᑍ

ð1 COBJI.

ð5 NUMKEY

ð5 KEY13

ð5 LEN13

ð5 PID13

ð5 KEY12

ð5 LEN12

ð5 LID12

ð5 KEY5

ð5 LEN5

ð5 LP5

PIC S9(ð9) VALUE 3 BINARY.

PIC S9(ð9) VALUE 13 BINARY.

PIC S9(ð9) VALUE 4 BINARY.

PIC X(ð4).

PIC S9(ð9) VALUE 12 BINARY.

PIC S9(ð9) VALUE 4 BINARY.

PIC X(ð4).

PIC S9(ð9) VALUE 5 BINARY.

PIC S9(ð9) VALUE 13 BINARY.

PIC X(13).

ᑍ

ᑍ Miscellaneous data

ᑍ

ð1 MISC.

ð5 FIRST-ERR

ð5 PROD-ID

ð5 PROD-NAME

ð5 RLS-LVL

ð5 NBR-OPTS

ð5 NBR-LANGS

ð5 TEXT-DESC

ð5 PUB-AUT

ð5 NBR-ADD-LB

ð5 NBR-PE

ð5 NBR-FLDRS

ð5 OBJNAM

ð5 PROD-ID-NM

ð5 SEC-LANG

ð5 I

PIC X(ð1) VALUE "ð".

PIC X(ð7) VALUE "ðABCABC".

PIC X(2ð) VALUE "ABCðð5ð ABC".

PIC X(ð6) VALUE "V3R1Mð".

PIC S9(ð9) VALUE 1 BINARY.

PIC X(5ð) VALUE "ABC Product".

PIC X(1ð) VALUE "ᑍUSE".

PIC S9(ð9) VALUE ð BINARY.

PIC S9(ð9) VALUE 1 BINARY.

PIC S9(ð9) VALUE ð BINARY.

PIC X(2ð).

PIC X(1ð).

PIC S9(ð9) BINARY.

PIC X(1ð).

PIC X(ð4) VALUE "ᑍYES".

PIC X(ð5) VALUE "ᑍNO".

ð5 RTN-LIB

ð5 OBJ-TYPE-2

ð5 REPKG

ð5 ALWCHG

ᑍ

ᑍ Beginning of Mainline

ᑍ

PROCEDURE DIVISION.

MAIN-LINE.

ᑍ

ᑍ Initialize the error code parameter. To signal exceptions to

ᑍ this program by the API, you need to set the bytes provided

ᑍ field of the error code to zero. Because this program has

ᑍ exceptions sent back through the error code parameter, it sets

ᑍ the bytes provided field to the number of bytes it gives the

ᑍ API for the parameter.

ᑍ

MOVE LENGTH OF QUS-EC TO BYTES-PROVIDED OF QUS-EC.

ᑍ

ᑍ Create Product Definition Object - ABCðð5ð

ᑍ

PERFORM PRDDFN. .1/

ᑍ

ᑍ Create Product Load Objects - ABCðð5ð (MRM) and ABCðð29 (MRI)

B-138 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

ᑍ

PERFORM PRDLOD. .2/

ᑍ Change Object Description for all objects associated with

ᑍ ABC Product.

ᑍ

PERFORM COBJD. .3/

ᑍ

ᑍ Package the ABC Product so that all the SAVLICPGM, RSTLIBPGM,

ᑍ and DLTLICPGM commands work with the product.

ᑍ

PERFORM PKGPO. .4/

ᑍ

ᑍ All done, product is ready to ship.

ᑍ

STOP RUN.

ᑍ

ᑍ End of MAINLINE

ᑍ

ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

ᑍ

ᑍ Subroutine: PRDDFN

ᑍ

ᑍ Descriptive Name: Create product definitions.

ᑍ

ᑍ Description: This subroutine will create the product definition

ᑍ

ABCðð5ð for the ABC Product.

ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

ᑍ

PRDDFN.

ᑍ

ᑍ Setup for Product Definition

ᑍ Fill Product Definition Information Parameter

ᑍ

MOVE PROD-ID OF MISC TO PID OF QSZ-PRD-INF.

MOVE RLS-LVL OF MISC TO RLS-LVL OF QSZ-PRD-INF.

MOVE "ABCMSG" TO MSG-FILE OF QSZ-PRD-INF.

MOVE "ᑍCURRENT" TO FST-CPYRT OF QSZ-PRD-INF.

MOVE "ᑍCURRENT" TO CUR-CPYRT OF QSZ-PRD-INF.

MOVE "9412ð1" TO RLS-DATE OF QSZ-PRD-INF.

MOVE "ᑍNO" TO ALW-MULT-RLS OF QSZ-PRD-INF.

MOVE "ᑍPHONE" TO REG-ID-TYPE OF QSZ-PRD-INF.

MOVE "5ð72535ð1ð" TO REG-ID-VAL OF QSZ-PRD-INF.

ᑍ

ᑍ Fill Product Load Parameter

ᑍ

MOVE "ðððð" TO OPT OF QSZ-PRD-OPT.

MOVE "ABCððð1" TO MSG-ID OF QSZ-PRD-OPT.

MOVE "ᑍNODYNNAM" TO ALW-DYN-NAM OF QSZ-PRD-OPT.

MOVE "5ðð1" TO COD-LOD OF QSZ-PRD-OPT.

MOVE SPACES TO RESERVED OF QSZ-PRD-OPT.

ᑍ

ᑍ Fill Language Load List Parameter

ᑍ

MOVE "2924" TO LNG-LOD OF QSZ-LNG-LOD.

Appendix B. Original Examples in Additional Languages B-139

Download from Www.Somanuals.com. All Manuals Search And Download.

MOVE "ðððð" TO OPT OF QSZ-LNG-LOD.

MOVE SPACES TO RESERVED OF QSZ-LNG-LOD.

ᑍ

ᑍ Create the Product Definition for the ABC Product

ᑍ

MOVE 1 TO NBR-OPTS.

MOVE 1 TO NBR-LANGS.

CALL "QSZCRTPD" USING PROD-NAME, QSZ-PRD-INF, QSZ-PRD-OPT,

NBR-OPTS, QSZ-LNG-LOD, NBR-LANGS,

TEXT-DESC, PUB-AUT, QUS-EC.

ᑍ

ᑍ If an exception occurs, the API returns the exception in the

ᑍ error code parameter. The bytes available field is set to

ᑍ zero if no exception occurs and greater than zero if an

ᑍ exception does occur.

ᑍ

IF BYTES-AVAILABLE OF QUS-EC > ð

MOVE "QSZCRTPD" TO API-NAME,

PERFORM ERRCOD.

ᑍ

ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

ᑍ

ᑍ Subroutine: PRDLOD

ᑍ

ᑍ Descriptive Name: Create product loads.

ᑍ

ᑍ Description: This subroutine will create the product loads,

ᑍ

ABCðð5ð and ABCðð29, for the ABC Product.

ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

ᑍ

PRDLOD.

ᑍ

ᑍ Setup for Product Load for MRM Objects

ᑍ Fill Product Load Information Parameter

ᑍ

MOVE PROD-ID OF MISC TO PID OF QSZ-LOD-INF.

MOVE RLS-LVL OF MISC TO RLS-LVL OF QSZ-LOD-INF.

MOVE "ðððð" TO OPT OF QSZ-LOD-INF.

MOVE "ᑍCODE" TO LOD-TYPE OF QSZ-LOD-INF.

MOVE "ᑍCODEDFT" TO LOD-ID OF QSZ-LOD-INF.

MOVE "ᑍPRDDFN" TO REG-ID-TYPE OF QSZ-LOD-INF.

MOVE SPACES TO REG-ID-VAL OF QSZ-LOD-INF.

MOVE "ᑍCURRENT" TO MIN-TGT-RLS OF QSZ-LOD-INF.

MOVE SPACES TO RESERVED OF QSZ-LOD-INF.

ᑍ

ᑍ Fill Principal Library Information Parameter

ᑍ

MOVE "ABC" TO DEV-LIB OF QSZ-LIB-INF.

MOVE "ABC" TO PRIM-LIB OF QSZ-LIB-INF.

MOVE "ABCPGMMRM2" TO POST-EXIT-PGM OF QSZ-LIB-INF.

ᑍ

ᑍ Fill Preoperation Exit Programs Parameter

ᑍ

MOVE "ABCPGMMRM1" TO PRE-EXT-PGM OF QSZ-PRE-EXT.

MOVE "ABC" TO DEV-LIB OF QSZ-PRE-EXT.

B-140 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

ᑍ

ᑍ Fill Additional Library List Parameter

ᑍ

None

ᑍ Fill Folder List Parameter

ᑍ

None

ᑍ Let's create the product load for the ABC Product - MRM Objects

ᑍ

MOVE "ABCðð5ð" TO PROD-ID-NM.

MOVE SPACES TO SEC-LANG.

ᑍ

CALL "QSZCRTPL" USING PROD-ID-NM, QSZ-LOD-INF, SEC-LANG,

QSZ-LIB-INF, QSZ-ADD-LIB,

NBR-ADD-LB, QSZ-PRE-EXT, NBR-PE,

QSZ-FLR-LST, NBR-FLDRS, TEXT-DESC,

PUB-AUT, QUS-EC.

ᑍ

ᑍ If an exception occurs, the API returns the exception in the

ᑍ error code parameter. The bytes available field is set to

ᑍ zero if no exception occurs and greater than zero if an

ᑍ exception does occur.

ᑍ

IF BYTES-AVAILABLE OF QUS-EC > ð

MOVE "QSZCRTPL" TO API-NAME,

PERFORM ERRCOD.

ᑍ

ᑍ Setup for Product Load for MRI Objects

ᑍ Fill Product Load Information Parameter

ᑍ

MOVE "ᑍLNG" TO LOD-TYPE OF QSZ-LOD-INF.

MOVE "2924" TO LOD-ID OF QSZ-LOD-INF.

ᑍ

ᑍ Fill Principal Library Information Parameter

ᑍ

MOVE "ABCPGMMRI2" TO POST-EXIT-PGM OF QSZ-LIB-INF.

ᑍ

ᑍ Fill Preoperation Exit Programs Parameter

ᑍ

MOVE "ABCPGMMRI1" TO PRE-EXT-PGM OF QSZ-PRE-EXT.

ᑍ

ᑍ Fill Additional Library List Parameter

ᑍ

None

ᑍ Fill Folder List Parameter

ᑍ

None

ᑍ Let's create the product load for the ABC Product - MRI Objects

ᑍ

MOVE "ABCðð29" TO PROD-ID-NM.

MOVE "ABC2924" TO SEC-LANG.

ᑍ

CALL "QSZCRTPL" USING PROD-ID-NM, QSZ-LOD-INF, SEC-LANG,

QSZ-LIB-INF, QSZ-ADD-LIB,

NBR-ADD-LB, QSZ-PRE-EXT, NBR-PE,

QSZ-FLR-LST, NBR-FLDRS, TEXT-DESC,

PUB-AUT, QUS-EC.

ᑍ

Appendix B. Original Examples in Additional Languages B-141

Download from Www.Somanuals.com. All Manuals Search And Download.

ᑍ If an exception occurs, the API returns the exception in the

ᑍ error code parameter. The bytes available field is set to

ᑍ zero if no exception occurs and greater than zero if an

ᑍ exception does occur.

ᑍ

IF BYTES-AVAILABLE OF QUS-EC > ð

MOVE "QSZCRTPL" TO API-NAME,

PERFORM ERRCOD.

ᑍ

ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

ᑍ

ᑍ Subroutine: COBJD

ᑍ

ᑍ Descriptive Name: Change object descriptions for ABC Product.

ᑍ

ᑍ Description: This subroutine will change the object

ᑍ

descriptions for all objects that make up the

ABC Product. Currently that is 15 objects. They

are listed at the end of this program.

ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

ᑍ

COBJD.

ᑍ

ᑍ Need to associate all objects with the ABC Product

ᑍ

PERFORM CHG-OBJD VARYING I FROM 1 BY 1 UNTIL I > 15.

ᑍ

CHG-OBJD.

STRING OBJ-NAME(I), "ABC" DELIMITED BY SIZE INTO OBJNAM.

MOVE LP-ID(I) TO LP5.

MOVE PRD-OPT-ID(I) TO PID13.

MOVE PRD-OPT-LD(I) TO LID12.

MOVE OBJ-TYPE(I) TO OBJ-TYPE-2.

ᑍ

CALL "QLICOBJD" USING RTN-LIB, OBJNAM, OBJ-TYPE-2,

COBJI, QUS-EC.

ᑍ

ᑍ If an exception occurs, the API returns the exception in the

ᑍ error code parameter. The bytes available field is set to

ᑍ zero if no exception occurs and greater than zero if an

ᑍ exception does occur.

ᑍ

IF BYTES-AVAILABLE OF QUS-EC > ð

MOVE "QLICOBJD" TO API-NAME,

PERFORM ERRCOD.

ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

ᑍ

ᑍ Subroutine: PKGPO

ᑍ

ᑍ Descriptive Name: Package software ABC Product.

ᑍ

ᑍ Description: This subroutine will package the ABC Product.

ᑍ

It makes sure that all objects exist that are

associated with the product.

B-142 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

ᑍ

ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

ᑍ

PKGPO.

ᑍ

ᑍ Setup for packing the ABC Product.

ᑍ Fill Product Option Information Parameter

ᑍ

MOVE "ðððð" TO OPT OF QSZ-PRD-OPT-INF.

MOVE PROD-ID OF MISC TO PID OF QSZ-PRD-OPT-INF.

MOVE RLS-LVL OF MISC TO RLS-LVL OF QSZ-PRD-OPT-INF.

MOVE "ᑍALL" TO LOD-ID OF QSZ-PRD-OPT-INF.

MOVE SPACES TO RESERVED OF QSZ-PRD-OPT-INF.

ᑍ

ᑍ Let's package the ABC Product.

ᑍ

CALL "QSZPKGPO" USING QSZ-PRD-OPT-INF, REPKG,

ALWCHG, QUS-EC.

ᑍ

ᑍ If an exception occurs, the API returns the exception in the

ᑍ error code parameter. The bytes available field is set to

ᑍ zero if no exception occurs and greater than zero if an

ᑍ exception does occur.

ᑍ

IF BYTES-AVAILABLE OF QUS-EC > ð

MOVE "QSZPKGPO" TO API-NAME,

PERFORM ERRCOD.

ᑍ

ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

ᑍ

ᑍ Subroutine: ERRCOD

ᑍ

ᑍ Descriptive Name: Process API errors.

ᑍ

ᑍ Description: This subroutine will print a line to a spooled

ᑍ

file if any errors are returned in the error code

parameter.

ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

ᑍ

ERRCOD.

ᑍ

ᑍ Process errors returned from the API.

ᑍ

ᑍ If first error found, then open QPRINT ᑍPRTF

ᑍ

IF FIRST-ERR = "ð"

OPEN OUTPUT LISTING,

MOVE "1" TO FIRST-ERR.

ᑍ

ᑍ Output the error and the API that received the error

ᑍ

MOVE EXCEPTION-ID OF QUS-EC TO EXCEPTION-ID OF BAD-NEWS.

WRITE LIST-LINE FROM BAD-NEWS.

Appendix B. Original Examples in Additional Languages B-143

Download from Www.Somanuals.com. All Manuals Search And Download.

Program for Packaging a Product—ILE RPG Example

Refer to “Program for Packaging a Product—OPM RPG Example” on page A-3 for

the original example.

Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Fᑍ

FᑍProgram Name: SFTWPRDEX

Fᑍ

FᑍLanguage: ILE RPG

Fᑍ

FᑍDescriptive Name: Software Product Example

Fᑍ

FᑍDescription: This example shows you the steps necessary to

Fᑍ

package your product like IBM products.

FᑍHeader Files Included: QUSEC

- Error Code Parameter

Fᑍ

QSZCRTPD - Create Product Definition API

QSZCRTPL - Create Product Load API

QSZPKGPO - Package Product Option API

Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Fᑍ

FQPRINT

Dᑍ

F 132

PRINTER OFLIND(ᑍINOF) USROPN

Dᑍ Error Code parameter include. As this sample program

Dᑍ uses /COPY to include the error code structure, only the first

Dᑍ 16 bytes of the error code structure are available. If the

Dᑍ application program needs to access the variable length

Dᑍ exception data for the error, the developer should physically

Dᑍ copy the QSYSINC include and modify the copied include to

Dᑍ define additional storage for the exception data.

Dᑍ

D/COPY QSYSINC/QRPGLESRC,QUSEC

Dᑍ

Dᑍ Create Product Definition API Include

Dᑍ

D/COPY QSYSINC/QRPGLESRC,QSZCRTPD

Dᑍ

Dᑍ Create Product Load API Include

Dᑍ

D/COPY QSYSINC/QRPGLESRC,QSZCRTPL

Dᑍ

Dᑍ Package Product Option API Include

Dᑍ

D/COPY QSYSINC/QRPGLESRC,QSZPKGPO

Dᑍ

Dᑍ Compile Time Array

Dᑍ

DOBJ_INFO

Dᑍ

DIM(15) CTDATA PERRCD(1)

BASED(OBJ_PTR)

DOBJ_INFO_I

D OBJ_NAME

D OBJ_TYPE

D PRD_OPT_ID

D PRD_OPT_LD

D LP_ID

1ð

B-144 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Dᑍ

Dᑍ Change Object Information parameter

Dᑍ

DCOBJI

D NUMKEY

D KEY13

D LEN13

D PID13

D KEY12

D LEN12

D LID12

D KEY5

D LEN5

D LP5

9B ð INZ(3)

9B ð INZ(13)

9B ð INZ(4)

9B ð INZ(12)

9B ð INZ(4)

9B ð INZ(5)

9B ð INZ(13)

Dᑍ

Dᑍ Miscellaneous data

Dᑍ

DAPI_NAME

DFIRST_ERR

DPROD_ID

DPROD_NAME

DRLS_LVL

DNBR_OPTS

DNBR_LANGS

DTEXT_DESC

DPUB_AUT

DNBR_ADD_LB

DNBR_PE

1ð

INZ('ð')

INZ('ðABCABC')

INZ('ABCðð5ð ABC

INZ('V3R1Mð')

2ð

9B ð INZ(1)

5ð

1ð

INZ('ABC Product')

INZ('ᑍUSE')

9B ð INZ(ð)

9B ð INZ(1)

9B ð INZ(ð)

DNBR_FLDRS

DOBJNAM

2ð

Cᑍ

Cᑍ Beginning of Mainline

Cᑍ

Cᑍ Initialize the error code parameter. To signal exceptions to

Cᑍ this program by the API, you need to set the bytes provided

Cᑍ field of the error code to zero. Because this program has

Cᑍ exceptions sent back through the error code parameter, it sets

Cᑍ the bytes provided field to the number of bytes it gives the

Cᑍ API for the parameter.

Cᑍ

EVAL

QUSBPRV = %SIZE(QUSEC)

Cᑍ

Cᑍ Create Product Definition Object - ABCðð5ð

Cᑍ

EXSR

PRDDFN

.1/

Cᑍ Create Product Load Objects - ABCðð5ð (MRM) and ABCðð29 (MRI)

Cᑍ

EXSR

PRDLOD

.2/

Cᑍ Change Object Description for all objects associated with

Cᑍ the ABC Product.

Cᑍ

EXSR

COBJD

.3/

Cᑍ

Cᑍ Package the ABC Product so that all the SAVLICPGM, RSTLIBPGM,

Cᑍ and DLTLICPGM commands work with the product.

Cᑍ

Appendix B. Original Examples in Additional Languages B-145

Download from Www.Somanuals.com. All Manuals Search And Download.

Cᑍ

EXSR

PKGPO

.4/

Cᑍ All done, product is ready to ship.

Cᑍ

EVAL

RETURN

ᑍINLR = '1'

Cᑍ

Cᑍ End of MAINLINE

Cᑍ

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Cᑍ

Cᑍ Subroutine: PRDDFN

Cᑍ

Cᑍ Descriptive Name: Create product definitions.

Cᑍ

Cᑍ Description: This subroutine will create the product definition

Cᑍ

ABCðð5ð for the ABC product.

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Cᑍ

PRDDFN

BEGSR

Cᑍ Setup for Product Definition

Cᑍ Fill Product Definition Information Parameter

Cᑍ

EVAL

QSZPID = PROD_ID

QSZRL = RLS_LVL

QSZMFIL = 'ABCMSG'

QSZFC = 'ᑍCURRENT'

QSZCC = 'ᑍCURRENT'

QSZRD = '9412ð1'

QSZAMR = 'ᑍNO'

QSZRIDT = 'ᑍPHONE'

QSZRIDV = '5ð72535ð1ð'

Cᑍ Fill Product Load Parameter

Cᑍ

EVAL

QSZOPT = 'ðððð'

QSZMID = 'ABCððð1'

QSZADN = 'ᑍNODYNNAM'

QSZCL = '5ðð1'

Cᑍ

QSZERVEDðð = ᑍBLANKS

Cᑍ Fill Language Load List Parameter

Cᑍ

EVAL

QSZLLðð = '2924'

QSZOPTðð = 'ðððð'

QSZERVEDð1 = ᑍBLANKS

Cᑍ

Cᑍ Create the Product Definition for the ABC Product

Cᑍ

CALL

PARM

'QSZCRTPD'

PROD_NAME

QSZPI

QSZPO

B-146 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

PARM

NBR_OPTS

QSZLL

NBR_LANGS

TEXT_DESC

PUB_AUT

QUSEC

Cᑍ

Cᑍ If an exception occurs, the API returns the exception in the

Cᑍ error code parameter. The bytes available field is set to

Cᑍ zero if no exception occurs and greater than zero if an

Cᑍ exception does occur.

Cᑍ

QUSBAVL > ð

API_NAME = 'QSZCRTPD'

ERRCOD

EVAL

EXSR

ENDIF

Cᑍ

ENDSR

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Cᑍ

Cᑍ Subroutine: PRDLOD

Cᑍ

Cᑍ Descriptive Name: Create product loads.

Cᑍ

Cᑍ Description: This subroutine will create the product loads,

Cᑍ

ABCðð5ð and ABCðð29, for the ABC product.

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Cᑍ

PRDLOD

BEGSR

Cᑍ Setup for Product Load for MRM Objects

Cᑍ Fill Product Load Information Parameter

Cᑍ

EVAL

QSZPIDðð = PROD_ID

QSZRLðð = RLS_LVL

QSZOPTð1 = 'ðððð'

QSZLT = 'ᑍCODE'

QSZLID = 'ᑍCODEDFT'

QSZRIDTðð = 'ᑍPRDDFN'

QSZRIDVðð = ᑍBLANKS

QSZMTR = 'ᑍCURRENT'

QSZERVEDð2 = ᑍBLANKS

Cᑍ Fill Principal Library Information Parameter

Cᑍ

EVAL

QSZDL = 'ABC'

QSZPL = 'ABC'

QSZPEP = 'ABCPGMMRM2'

Cᑍ

Cᑍ Fill Preoperation Exit Programs Parameter

Cᑍ

EVAL

QSZPEPðð = 'ABCPGMMRM1'

QSZDLðð = 'ABC'

Cᑍ

Appendix B. Original Examples in Additional Languages B-147

Download from Www.Somanuals.com. All Manuals Search And Download.

Cᑍ Fill Additional Library List Parameter

Cᑍ

None

Cᑍ Fill Folder List Parameter

Cᑍ

None

Cᑍ Let's create the product load for the ABC Product - MRM Objects

Cᑍ

CALL

PARM

'QSZCRTPL'

'ABCðð5ð'

PROD_ID_NM

QSZLI

SEC_LANG

QSZLIðð

QSZAL

NBR_ADD_LB

QSZPE

NBR_PE

QSZFL

NBR_FLDRS

TEXT_DESC

PUB_AUT

QUSEC

1ð

ᑍBLANKS

Cᑍ If an exception occurs, the API returns the exception in the

Cᑍ error code parameter. The bytes available field is set to

Cᑍ zero if no exception occurs and greater than zero if an

Cᑍ exception does occur.

Cᑍ

QUSBAVL > ð

API_NAME = 'QSZCRTPL'

ERRCOD

EVAL

EXSR

ENDIF

Cᑍ

Cᑍ Setup for Product Load for MRI Objects

Cᑍ Fill Product Load Information Parameter

Cᑍ

EVAL

QSZLT = 'ᑍLNG'

QSZLID = '2924'

Cᑍ

Cᑍ Fill Principal Library Information Parameter

Cᑍ

EVAL

QSZPEP = 'ABCPGMMRI2'

Cᑍ Fill Preoperation Exit Programs Parameter

Cᑍ

EVAL

QSZPEPðð = 'ABCPGMMRI1'

Cᑍ

Cᑍ Fill Additional Library List Parameter

Cᑍ

Cᑍ Fill Folder List Parameter

Cᑍ

None

Cᑍ Let's create the product load for the ABC Product - MRI Objects

Cᑍ

CALL

PARM

'QSZCRTPL'

'ABCðð29'

PROD_ID_NM

QSZLI

B-148 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Cᑍ

PARM

'ABC2924'

SEC_LANG

QSZLIðð

QSZAL

NBR_ADD_LB

QSZPE

NBR_PE

QSZFL

NBR_FLDRS

TEXT_DESC

PUB_AUT

QUSEC

Cᑍ If an exception occurs, the API returns the exception in the

Cᑍ error code parameter. The bytes available field is set to

Cᑍ zero if no exception occurs and greater than zero if an

Cᑍ exception does occur.

Cᑍ

QUSBAVL > ð

API_NAME = 'QSZCRTPL'

ERRCOD

EVAL

EXSR

ENDIF

Cᑍ

ENDSR

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Cᑍ

Cᑍ Subroutine: COBJD

Cᑍ

Cᑍ Descriptive Name: Change object descriptions for ABC Product.

Cᑍ

Cᑍ Description: This subroutine will change the object

Cᑍ

descriptions for all objects that make up the

ABC Product. Currently that is 15 objects. They

are listed at the end of this program.

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Cᑍ

COBJD

BEGSR

Cᑍ Need to associate all objects with the ABC Product

Cᑍ

3 ð

EVAL

OBJ_PTR = %ADDR(OBJ_INFO(I))

OBJNAM = OBJ_NAME + 'ABC'

LP5 = LP_ID

PID13 = PRD_OPT_ID

LID12 = PRD_OPT_LD

TYPE = OBJ_TYPE

Cᑍ

CALL

PARM

'QLICOBJD'

RTN_LIB

OBJNAM

TYPE

1ð

COBJI

QUSEC

Cᑍ

Appendix B. Original Examples in Additional Languages B-149

Download from Www.Somanuals.com. All Manuals Search And Download.

Cᑍ If an exception occurs, the API returns the exception in the

Cᑍ error code parameter. The bytes available field is set to

Cᑍ zero if no exception occurs and greater than zero if an

Cᑍ exception does occur.

Cᑍ

QUSBAVL > ð

API_NAME = 'QLICOBJD'

ERRCOD

EVAL

EXSR

ENDIF

Cᑍ

ENDDO

ENDSR

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Cᑍ

Cᑍ Subroutine: PKGPO

Cᑍ

Cᑍ Descriptive Name: Package software ABC Product.

Cᑍ

Cᑍ Description: This subroutine will package the ABC Product.

Cᑍ

It makes sure that all objects exist that are

associated with the product.

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Cᑍ

PKGPO

BEGSR

Cᑍ Setup for packing the ABC Product.

Cᑍ Fill Product Option Information Parameter

Cᑍ

EVAL

QSZOPTð2 = 'ðððð'

QSZPIDð1 = PROD_ID

QSZRLð1 = RLS_LVL

QSZLIDðð = 'ᑍALL'

QSZERVEDð3 = ᑍBLANKS

Cᑍ

Cᑍ Let's package the ABC Product.

Cᑍ

CALL

PARM

'QSZPKGPO'

QSZPOI

REPKG

ALWCHG

QUSEC

'ᑍYES'

'ᑍNO'

Cᑍ

Cᑍ If an exception occurs, the API returns the exception in the

Cᑍ error code parameter. The bytes available field is set to

Cᑍ zero if no exception occurs and greater than zero if an

Cᑍ exception does occur.

Cᑍ

QUSBAVL > ð

API_NAME = 'QSZPKGPO'

ERRCOD

EVAL

EXSR

ENDIF

Cᑍ

B-150 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Cᑍ

ENDSR

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Cᑍ

Cᑍ Subroutine: ERROR

Cᑍ

Cᑍ Descriptive Name: Process API errors.

Cᑍ

Cᑍ Description: This subroutine will print a line to a spooled

Cᑍ

file if any errors are returned in the error code

parameter.

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Cᑍ

ERRCOD

BEGSR

Cᑍ Process errors returned from the API.

Cᑍ

Cᑍ If first error found, then open QPRINT ᑍPRTF

Cᑍ

FIRST_ERR = 'ð'

QPRINT

OPEN

EVAL

ENDIF

FIRST_ERR = '1'

Cᑍ

Cᑍ Output the error and the API that received the error

Cᑍ

EXCEPT

BAD_NEWS

Cᑍ

ENDSR

OQPRINT

BAD_NEWS

'Failed in API '

'with error '

API_NAME

QUSEI

ᑍᑍCTDATA OBJ_INFO

ABCPGMMRM1ᑍPGM

ABCPGMMRM2ᑍPGM

ABCPGMMRI1ᑍPGM

ABCPGMMRI2ᑍPGM

ðððð5ðð1ðABCABCV3R1Mð

ðððð2924ðABCABCV3R1Mð

ðððð5ðð1ðABCABCV3R1Mð

ðððð2924ðABCABCV3R1Mð

ABCPGM

QCLSRC

ᑍPGM

ᑍFILE

ABCDSPF ᑍFILE

ABCPF

ABCMSG

ABC

ᑍFILE

ᑍMSGF

ᑍCMD

ABCPNLGRP ᑍPNLGRP ðððð2924ðABCABCV3R1Mð

ABCðð5ð ᑍPRDDFN ðððð5ðð1ðABCABCV3R1Mð

ABCðð5ð ᑍPRDLOD ðððð5ðð1ðABCABCV3R1Mð

ABCðð29 ᑍPRDLOD ðððð2924ðABCABCV3R1Mð

ABC

ᑍLIB

ðððð5ðð1ðABCABCV3R1Mð

Appendix B. Original Examples in Additional Languages B-151

Download from Www.Somanuals.com. All Manuals Search And Download.

Retrieving a File Description to a User Space—Examples

This section includes the examples in “Retrieving a File Description to a User

Space—ILE C Example” on page A-11.

Retrieving a File Description to a User Space—ILE COBOL Example

Refer to “Retrieving a File Description to a User Space—ILE C Example” on

page A-11 for the original example. The following program also works with OPM

COBOL.

IDENTIFICATION DIVISION.

ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

ᑍ

ᑍ Program:

RTVFD

ᑍ

ᑍ Language:

ᑍ

COBOL

ᑍ Description: This program retrieves a file definition

ᑍ

template to a user space.

ᑍ

ᑍ APIs Used:

QDBRTVFD - Retrieve File Description

QUSCRTUS - Create User Space

QUSCUSAT - Change User Space Attributes

QUSPTRUS - Retrieve a pointer to a User Space

ᑍ

ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

PROGRAM-ID. RTVFD.

ENVIRONMENT DIVISION.

CONFIGURATION SECTION.

SOURCE-COMPUTER. IBM-AS4ðð.

OBJECT-COMPUTER. IBM-AS4ðð.

DATA DIVISION.

WORKING-STORAGE SECTION.

ᑍ

ᑍ Error Code parameter include. As this sample program

ᑍ uses COPY to include the error code structure, only the first

ᑍ 16 bytes of the error code structure are available. If the

ᑍ application program needs to access the variable length

ᑍ exception data for the error, the developer should physically

ᑍ copy the QSYSINC include and modify the copied include to

ᑍ define additional storage for the exception data.

ᑍ

COPY QUSEC OF QSYSINC-QLBLSRC.

ᑍ

ᑍ Misc. elements

ᑍ

ð1 MISC.

ð5 EXIT-POINT-NAME PIC X(2ð) VALUE "EXAMPLE_EXIT_POINT".

ð5 EXIT-PGM-NBR

PIC S9(ð9) VALUE -1 BINARY.

ð5 EXIT-PARAMETERS PIC X(1ð).

ð5 FILE-USED

ð5 LIBRARY-NAME

ð5 SPACE-SIZE

ð5 SPACE-INIT

PIC X(2ð).

PIC X(1ð).

PIC S9(ð9) BINARY.

PIC X(ð1) VALUE "X'ðð'".

ð5 SPACE-POINTER POINTER.

B-152 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

ð5 FORMAT-NAME-1 PIC X(ð8).

ð5 OVERRIDES

ð5 SYSTEM

ð5 FORMAT-1

ð5 EXT-ATTR

ð5 SPACE-AUT

ð5 SPACE-TEXT

PIC X(ð1) VALUE "ð".

PIC X(1ð) VALUE "ᑍLCL".

PIC X(1ð) VALUE "ᑍINT".

PIC X(1ð).

PIC X(1ð) VALUE "ᑍCHANGE".

PIC X(5ð) VALUE "QDBRTVFD".

ð5 SPACE-REPLACE PIC X(1ð) VALUE "ᑍYES".

ð5 SPACE-DOMAIN

ð5 API-NAME

PIC X(1ð) VALUE "ᑍUSER".

PIC X(1ð).

ð1 CHG-US-ATTR.

ð5 NBR-OF-ATTR

ð5 ATTR-KEY

ð5 DATA-SIZE

ð5 ATTR-DATA

PIC S9(ð9) VALUE 1 BINARY.

PIC S9(ð9) VALUE 3 BINARY.

PIC S9(ð9) VALUE 1 BINARY.

PIC X(ð1) VALUE "1".

ᑍ

LINKAGE SECTION.

ð1 SPACE-NAME

PIC X(2ð).

PIC X(1ð).

ð1 FILE-NAME

ð1 FORMAT-NAME-PARM

ᑍ Retrieve File Description API include.

ᑍ

COPY QDBRTVFD OF QSYSINC-QLBLSRC.

ᑍ

ᑍ Beginning of mainline

ᑍ

PROCEDURE DIVISION USING SPACE-NAME, FILE-NAME,

FORMAT-NAME-PARM.

MAIN-LINE.

ᑍ

PERFORM INITIALIZE-SPACE.

PERFORM PROCESS-SPACE.

PERFORM PROGRAM-DONE.

ᑍ

ᑍ Start of subroutines

ᑍ

ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

PROCESS-SPACE.

ᑍ

ᑍ The template returned from QDBRTVFD is now addressable by way

ᑍ of SPACE-POINTER; as an example the program will now display

ᑍ the access method for the file:

ᑍ

DISPLAY QDBFPACT OF QDB-QDBFH.

ᑍ

ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

ᑍ

INITIALIZE-SPACE.

ᑍ

ᑍ One time initialization code for this program

ᑍ

ᑍ Set Error Code structure to not use exceptions

ᑍ

MOVE 16 TO BYTES-PROVIDED OF QUS-EC.

ᑍ

ᑍ Create a User Space for QDBRTVFD

ᑍ

Appendix B. Original Examples in Additional Languages B-153

Download from Www.Somanuals.com. All Manuals Search And Download.

MOVE 1ð24 TO SPACE-SIZE.

CALL "QUSCRTUS" USING SPACE-NAME, EXT-ATTR, SPACE-SIZE,

SPACE-INIT, SPACE-AUT, SPACE-TEXT,

SPACE-REPLACE, QUS-EC, SPACE-DOMAIN.

ᑍ

ᑍ Check for errors on QUSCRTUS

ᑍ

IF BYTES-AVAILABLE OF QUS-EC > ð

MOVE "QUSCRTUS" TO API-NAME,

PERFORM API-ERROR-FOUND.

ᑍ

ᑍ Change the User Space so that it is extendable

ᑍ

CALL "QUSCUSAT" USING LIBRARY-NAME, SPACE-NAME,

CHG-US-ATTR, QUS-EC.

ᑍ

ᑍ Check for errors on QUSCUSAT

ᑍ

IF BYTES-AVAILABLE OF QUS-EC > ð

MOVE "QUSCUSAT" TO API-NAME,

PERFORM API-ERROR-FOUND.

ᑍ

ᑍ Get a resolved pointer to the User Space

ᑍ

CALL "QUSPTRUS" USING SPACE-NAME, SPACE-POINTER, QUS-EC.

ᑍ

ᑍ Check for errors on QUSPTRUS

ᑍ

IF BYTES-AVAILABLE OF QUS-EC > ð

MOVE "QUSPTRAT" TO API-NAME,

PERFORM API-ERROR-FOUND.

ᑍ

ᑍ If no errors, then call QDBRTVFD passing the address of the

ᑍ User Space as the receiver variable. To accomplish this,

ᑍ assign the address of QDB-QDBFH to SPACE-POINTER and then

ᑍ pass QDB-QDBFH.

ᑍ

SET ADDRESS OF QDB-QDBFH TO SPACE-POINTER.

ᑍ

MOVE 167767ð4 TO SPACE-SIZE.

MOVE "FILDð1ðð" TO FORMAT-NAME-1.

ᑍ

CALL "QDBRTVFD" USING QDB-QDBFH, SPACE-SIZE, FILE-USED,

FORMAT-NAME-1, FILE-NAME,

FORMAT-NAME-PARM, OVERRIDES,

SYSTEM OF MISC, FORMAT-1, QUS-EC.

ᑍ

ᑍ Check for errors on QDBRTVFD

ᑍ

IF BYTES-AVAILABLE OF QUS-EC > ð

MOVE "QDBRTVFD" TO API-NAME,

PERFORM API-ERROR-FOUND.

ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

API-ERROR-FOUND.

ᑍ

ᑍ Log any error encountered, and exit the program

ᑍ

DISPLAY API-NAME.

B-154 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

DISPLAY EXCEPTION-ID OF QUS-EC.

PERFORM PROGRAM-DONE.

ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

PROGRAM-DONE.

ᑍ

ᑍ Exit the program

ᑍ

STOP RUN.

Retrieving a File Description to a User Space—ILE RPG Example

Refer to “Retrieving a File Description to a User Space—ILE C Example” on

page A-11 for the original example.

Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Dᑍ

Dᑍ Program:

Dᑍ

RTVFD

Dᑍ Language:

Dᑍ

ILE RPG

Dᑍ Description: This program retrieves a file definition

Dᑍ

template to a user space.

Dᑍ

Dᑍ APIs Used:

QDBRTVFD - Retrieve File Description

QUSCRTUS - Create User Space

QUSCUSAT - Change User Space Attributes

QUSPTRUS - Retrieve a pointer to a User Space

Dᑍ

Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Dᑍ

Dᑍ Error Code parameter include

Dᑍ

D/COPY QSYSINC/QRPGLESRC,QUSEC

Dᑍ

Dᑍ Not shown due to its size, this program also includes QDBRTVFD

Dᑍ and defines all of the data structures in QDBRTVFD as being

Dᑍ BASED(SPCPTR). For illustrative purposes, this sample shows

Dᑍ only the first significant data structure.

Dᑍ

Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Dᑍ

DᑍFile Definition Template (FDT) Header

Dᑍ

Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

DᑍThis section is always located at the beginning of the

Dᑍreturned data.

Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

DQDBQ25

BASED(SPCPTR)

Header information - The

FDT starts here

Dᑍ

D QDBFYRET

4B ð

Dᑍ

Bytes returned - The length

of the data returned

8B ð

D QDBFYAVL

Dᑍ

Bytes available - The number

of bytes provided for the

Appendix B. Original Examples in Additional Languages B-155

Download from Www.Somanuals.com. All Manuals Search And Download.

Dᑍ

file definition template

data

Dᑍ

DᑍQDBFHFLG

D QDBBITS27

1ð

Dᑍ QDBRSV1ðð

BITS

Dᑍ QDBFHFPLðð

BIT

Dᑍ QDBRSV2ðð

BIT

Dᑍ QDBFHFSUðð

BIT

Dᑍ QDBRSV3ðð

BIT

Dᑍ QDBFHFKYðð

BIT

Dᑍ QDBRSV4ðð

BIT

Dᑍ QDBFHFLCðð

BIT

Dᑍ QDBFKFSOðð

BIT

Dᑍ QDBRSV5ðð

BIT

Dᑍ QDBFHSHRðð

BIT

Dᑍ QDBRSV6ðð

BITS

Dᑍ QDBFIGCDðð

BIT

Dᑍ QDBFIGCLðð

Dᑍ

Attribute Bytes

D QDBRSV7

Dᑍ

Reserved.

16B ð

Number Of Data Members

1 = Externally described

physical file, or program

described physical file

that is NOT linked to a

Data Dictionary.

1-32 = Number of Data

Dictionary record

D QDBLBNUM

Dᑍ

formats for a program

described physical

file that is linked to

a Data Dictionary.

Dᑍ

1-32 = Number of based-on

physical files for

Dᑍ

a logical file.

DᑍQDBFKDAT

D QDBFKNUMðð

D QDBFKMXLðð

Dᑍ QDBFKFLGðð

D QDBBITS28

Dᑍ QDBRSV8ð2

Dᑍ QDBFKFCSð2

Dᑍ QDBRSV9ð2

Dᑍ QDBFKFRCð2

Dᑍ QDBFKFLTð2

D QDBFKFDMðð

D QDBRSV1ððð

Dᑍ

18B ð

2ðB ð

BIT

BITS

BIT

3ð

Keyed Sequence Access Path

D QDBFHAUT

Dᑍ

4ð

Public Authority (AUT)

'ᑍCHANGE ' = Public change

authority.

Dᑍ

'ᑍALL

' = Public all

authority.

' = Public use

authority.

Dᑍ

'ᑍUSE

Dᑍ

B-156 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Dᑍ

'ᑍEXCLUDE ' = Public exclude

authority.

Dᑍ

'authorization-list-name'

= Name of the

Dᑍ

authorization

Dᑍ

list whose

Dᑍ

authority is

Dᑍ

used for the

Dᑍ

file.

Dᑍ

This is the original public

authority that the file was

created with, NOT the current

public authority for the file.

Dᑍ

D QDBFHUPL

Dᑍ

Preferred Storage Unit (UNIT)

X'ðð' = The storage space for

the file and its

members can be

allocated on any

available auxiliary

storage unit (ᑍANY).

X'ð1'-X'FF' = The unit

identifier (a

Dᑍ

number from 1

to 255 assigned

when the disk

device is

configured) of

a specific

auxiliary

storage unit on

the system.

Dᑍ

D QDBFHMXM

43B ð

Maximum Members (MAXMBRS)

ð = No maximum is specified

for the number of members,

the system maximum of

32,767 members is used

(ᑍNOMAX).

Dᑍ

1-32,767 = The value for the

maximum number of

Dᑍ

members that the

file can have

Dᑍ

(maximum-members).

D QDBFWTFI

45B ð

Dᑍ

Maximum File Wait Time

(WAITFILE)

-1 = The default wait time

specified in the class

description is used as

the wait time for the

file (ᑍCLS).

ð = A program does NOT wait

for the file, an

immediate allocation of

the file is required

(ᑍIMMED).

1-32,767 = The number of

Appendix B. Original Examples in Additional Languages B-157

Download from Www.Somanuals.com. All Manuals Search And Download.

Dᑍ

seconds that a

program waits for

the file (number-

of-seconds).

Dᑍ

D QDBFHFRT

47B ð

Dᑍ

Records To Force A Write

(FRCRATIO)

Dᑍ

ð = There is NO force write

ratio, the system

determines when the

records are written to

auxiliary storage (ᑍNONE).

1-32,767 = The number of

inserted, updated,

or deleted records

that are processed

before they are

Dᑍ

explicitly forced

to auxiliary

storage (number-

of-records-before-

force).

Dᑍ

D QDBHMNUM

49B ð

Dᑍ

Number Of Members

ð-32,767 = The current number

of members for the

file.

Dᑍ

D QDBRSV11

5ð

Dᑍ

Reserved.

D QDBFBRWT

6ðB ð

Dᑍ

Maximum Record Wait Time

Dᑍ

(WAITRCD)

Dᑍ

-2 = The wait time is the

maximum allowed by the

system, 32,767 seconds

(ᑍNOMAX).

-1 = A program does NOT wait

for the record, an

immediate allocation of

the record is required

(ᑍIMMED).

Dᑍ

1-32,767 = The number of

seconds that a

Dᑍ

program waits for

the record

(number-of-

seconds).

Dᑍ

DᑍQDBQAAFðð

D QDBBITS29

Dᑍ QDBRSV12ðð

BITS

BIT

Dᑍ QDBFPGMDðð

Dᑍ

Additional Attribute Flags

D QDBMTNUM

63B ð

Dᑍ

Total Number Of Record

Dᑍ

Formats

Dᑍ

1-32 = Number of record

formats for the file.

Dᑍ

DᑍQDBFHFL2

B-158 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

D QDBBITS3ð

Dᑍ QDBFJNAPðð

BIT

Dᑍ QDBRSV13ðð

BIT

Dᑍ QDBFRDCPðð

BIT

Dᑍ QDBFWTCPðð

BIT

Dᑍ QDBFUPCPðð

BIT

Dᑍ QDBFDLCPðð

BIT

Dᑍ QDBRSV14ðð

BITS

Dᑍ QDBFKFNDðð

BIT

Dᑍ

Additional Attribute Flags

D QDBFVRM

67B ð

First Supported

Dᑍ

Version Release Modification

Level

X'ðððð' = Pre-Version 2

Release 1

Modification ð file.

X'15ðð' = Version 2 Release 1

Modification ð,

Dᑍ

V2R1Mð, file.

Dᑍ

X'15ð1' = Version 2 Release 1

Modification 1,

Dᑍ

V2R1M1, file.

Dᑍ

X'16ðð' = Version 2 Release 2

Modification ð,

Dᑍ

V2R2Mð, file.

Dᑍ

New Database support is used

in the file which will

prevent it from being saved

and restored to a prior

Version Release and

Modification level.

Dᑍ

DᑍQDBQAAF2

D QDBBITS31

Dᑍ QDBFHMCSðð

Dᑍ QDBRSV15ðð

Dᑍ QDBFKNLLðð

Dᑍ QDBFNFLDðð

Dᑍ QDBFVFLDðð

Dᑍ QDBFTFLDðð

Dᑍ QDBFGRPHðð

Dᑍ QDBRSV16ðð

Dᑍ

BIT

Additional Attribute Flags

D QDBRSV17

Dᑍ

7ð

Reserved.

D QDBFHCRT

Dᑍ

File Level Identifier

The date of the file in

internal standard format

(ISF), CYYMMDDHHMMSS.

Dᑍ

DᑍQDBFHTX

D QDBRSV18ðð

D QDBFHTXTðð

Dᑍ

D QDBRSV19

Dᑍ

134

File Text Description

Reserved

135

147

DᑍQDBFSRC

D QDBFSRCFðð

3ð

157

148

Appendix B. Original Examples in Additional Languages B-159

Download from Www.Somanuals.com. All Manuals Search And Download.

D QDBFSRCMðð

158

168

167

177

D QDBFSRCLðð

Dᑍ

Source File Fields

D QDBFKRCV

178

Dᑍ

Access Path Recovery

(RECOVER)

'A' = The file has its access

path built after the

IPL has been completed

(ᑍAFTIPL).

Dᑍ

'N' = The access path of the

file is NOT built

Dᑍ

during or after an IPL

(ᑍNO). The file's

access path is built

when the file is next

opened.

Dᑍ

'S' = The file has its access

path built during the

IPL (ᑍIPL).

Dᑍ

D QDBRSV2ð

179

2ð2

2ð1

Dᑍ

Reserved.

D QDBFTCID

2ð3B ð

Dᑍ

Coded Character Set

Dᑍ

Identifier, CCSID, For

Text Description (TEXT)

ð = There is NO text

description for the file.

1-65,535 = The CCSID for the

file's text

Dᑍ

description.

D QDBFASP

2ð4

2ð5

Dᑍ

Auxiliary Storage Pool (ASP)

X'ðððð' = The file is

located on the

system auxiliary

storage pool.

X'ððð2'-X'ðð1ð' = The user

auxiliary storage

pool the file is

Dᑍ

located on

(asp-identifier).

Dᑍ

D QDBRSV21

2ð6

2ð7

2ð6

Dᑍ

Reserved.

D QDBXFNUM

2ð8B ð

Dᑍ

Maximum Number Of Fields

Dᑍ

1-8ððð = The number of fields

in the file's record

format that contains

the largest number

of fields.

Dᑍ

D QDBRSV22

2ð9

285

284

Dᑍ

Reserved.

D QDBFODIC

288B ð

Dᑍ

Offset from the start of the

FDT header, Qdbfh, to the

IDDU/SQL Data Dictionary

Area, Qdbfdic.

B-160 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

D QDBRSV23

289

3ð3

3ð2

Dᑍ

Reserved.

3ð4B ð

File Generic Key Length

D QDBFFIGL

Dᑍ

ð-2ððð = The length of the

key before the first

ᑍNONE key field for

Dᑍ

the file.

Dᑍ

If this file has an arrival

sequence access path, this

field is NOT applicable.

Dᑍ

D QDBFMXRL

3ð5

3ð6B ð

Dᑍ

Maximum Record Length

1-32766 = The length of the

record in the

Dᑍ

file's record

Dᑍ

format that

Dᑍ

contains the

Dᑍ

largest number of

bytes.

Dᑍ

D QDBRSV24

3ð7

315

314

Dᑍ

Reserved.

D QDBFGKCT

316B ð

Dᑍ

File Generic Key Field Count

Dᑍ

ð-12ð = The count of the

number of key fields

before the first

Dᑍ

ᑍNONE key field for

the file.

If this file has an arrival

sequence access path, this

field is NOT applicable.

Dᑍ

D QDBFOS

317

32ðB ð

Dᑍ

Offset from the start of the

FDT header, Qdbfh, to the

File Scope Array, Qdbfb.

Dᑍ

D QDBRSV25

321

329

328

Dᑍ

Reserved.

D QDBFOCS

332B ð

Dᑍ

Offset from the start of the

Dᑍ

FDT header, Qdbfh, to the

Alternative Collating

Sequence Table section,

Qdbfacs.

Dᑍ

D QDBRSV26

333

337

336

338

Dᑍ

Reserved.

D QDBFPACT

Dᑍ

Access Path Type

'AR' = Arrival sequence

access path.

'KC' = Keyed sequence access

path with duplicate

keys allowed.

Duplicate keys are

accessed in first-

changed-first-out

(FCFO) order.

'KF' = Keyed sequence access

Appendix B. Original Examples in Additional Languages B-161

Download from Www.Somanuals.com. All Manuals Search And Download.

Dᑍ

path with duplicate

keys allowed.

Dᑍ

Duplicate keys are

accessed in first-

in-first-out

Dᑍ

(FIFO) order.

Dᑍ

'KL' = Keyed sequence access

path with duplicate

keys allowed.

Dᑍ

Duplicate keys are

accessed in last-

in-first-out

Dᑍ

(LIFO) order.

Dᑍ

'KN' = Keyed sequence access

path with duplicate

keys allowed.

Dᑍ

No order is guaranteed

when accessing

duplicate keys.

Dᑍ

Duplicate keys are

accessed in one of the

following methods:

(FCFO) (FIFO) (LIFO).

'KU' = Keyed sequence access

path with NO duplicate

keys allowed (UNIQUE).

Dᑍ

D QDBFHRLS

339

344

Dᑍ

File Version Release

Modification Level

'VxRyMz' = Where x is the

Version, y is the

Release, and z is

the Modification

level

Dᑍ

example V2R1M1

Version 2 Release

1 Modification 1

Dᑍ

D QDBRSV27

345

365

364

Dᑍ

Reserved.

D QDBPFOF

368B ð

Dᑍ

Offset from the start of the

Dᑍ

FDT header, Qdbfh, to the

Physical File Specific

Dᑍ

Attributes section, Qdbfphys.

D QDBLFOF

Dᑍ

369

372B ð

Offset from the start of the

FDT header, Qdbfh, to the

Logical File Specific

Dᑍ

Attributes section, Qdbflogl.

DᑍQDBFSSFPðð

Dᑍ QDBFNLSBð1

D QDBBITS58

Dᑍ QDBFSSCSð2

Dᑍ QDBR1ð3ð2

D QDBFLANGð1

D QDBFCNTYð1

Dᑍ

373

BITS

374

377

376

378

Sort Sequence Table

D QDBFJORN

379

382B ð

B-162 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Dᑍ

Offset from the start of the

FDT header, Qdbfh, to the

Journal Section, Qdbfjoal.

Dᑍ

D QDBRSV28

Dᑍ

383

4ðð

Reserved.

Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Dᑍ

DᑍThe FDT header ends here.

Dᑍ

Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Dᑍ

Dᑍ Misc. elements

Dᑍ

DSPC_NAME

DFILE_NAME

DFMT_NAME

DFILE_USED

DLIB_NAME

DSPC_SIZE

DSPC_INIT

DSPCPTR

DFORMAT

DOVERRIDES

DSYSTEM

DFORMAT_1

DCHG_ATTR

D NBR_ATTR

D ATTR_KEY

D DATA_SIZE

D ATTR_DATA

Cᑍ

2ð

1ð

2ð

1ð

9B ð

INZ(X'ðð')

ᑍ

1ð

INZ('ð')

INZ('ᑍLCL')

INZ('ᑍINT')

9B ð INZ(1)

9B ð INZ(3)

9B ð INZ(1)

INZ('1')

Cᑍ Start of mainline

Cᑍ

ᑍENTRY

PLIST

PARM

SPC_NAME

FILE_NAME

FMT_NAME

Cᑍ

EXSR

INIT

PROCES

DONE

Cᑍ

Cᑍ Start of subroutines

Cᑍ

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Cᑍ

PROCES

BEGSR

Cᑍ The template returned from QDBRTVFD is now addressable by way

Cᑍ of SPCPTR; as an example the program will now display the

Cᑍ access method for the file:

Cᑍ

DSPLY

ENDSR

QDBFPACT

Cᑍ

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Cᑍ

INIT

BEGSR

Cᑍ One time initialization code for this program

Appendix B. Original Examples in Additional Languages B-163

Download from Www.Somanuals.com. All Manuals Search And Download.

Cᑍ

Cᑍ Set Error Code structure to not use exceptions

Cᑍ

Z-ADD

QUSBPRV

Cᑍ Create a User Space for QDBRTVFD

Cᑍ

CALL

PARM

'QUSCRTUS'

SPC_NAME

EXT_ATTR

SPC_SIZE

SPC_INIT

SPC_AUT

ᑍBLANKS

1ð24

1ð

'ᑍCHANGE'

'QDBRTVFD'

'ᑍYES'

1ð

5ð

1ð

SPC_TEXT

SPC_REPLAC

QUSEC

'ᑍUSER'

SPC_DOMAIN

1ð

Cᑍ Check for errors on QUSCRTUS

Cᑍ

QUSBAVL

IFGT

MOVEL

EXSR

END

'QUSCRTUS'

APIERR

APINAM

1ð

Cᑍ

Cᑍ Change the User Space so that it is extendable

Cᑍ

CALL

PARM

'QUSCUSAT'

LIB_NAME

SPC_NAME

CHG_ATTR

QUSEC

Cᑍ

Cᑍ Check for errors on QUSCUSAT

Cᑍ

QUSBAVL

IFGT

MOVEL

EXSR

END

'QUSCUSAT'

APIERR

APINAM

1ð

Cᑍ

Cᑍ Get a resolved pointer to the User Space

Cᑍ

CALL

PARM

'QUSPTRUS'

SPC_NAME

SPCPTR

QUSEC

Cᑍ

Cᑍ Check for errors on QUSPTRUS

Cᑍ

QUSBAVL

IFGT

MOVEL

EXSR

END

'QUSPTRUS'

APIERR

APINAM

1ð

Cᑍ

Cᑍ If no errors, then call QDBRTVFD passing the address of the

Cᑍ User Space as the receiver variable. As Data Structure

Cᑍ QDBQ25 is defined as BASED(SPCPTR) and SPCPTR is set to the

Cᑍ first byte of the User Space, simply passing QDBQ25 will cause

B-164 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Cᑍ QDBRTVFD to use the User Space.

Cᑍ

CALL

PARM

'QDBRTVFD'

QDBQ25

167767ð4

SPC_SIZE

FILE_USED

FORMAT

'FILDð1ðð'

FILE_NAME

FMT_NAME

OVERRIDES

SYSTEM

FORMAT_1

QUSEC

Cᑍ Check for errors on QDBRTVFD

Cᑍ

QUSBAVL

IFGT

MOVEL

EXSR

END

'QDBRTVFD'

APIERR

APINAM

1ð

ENDSR

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Cᑍ

APIERR

BEGSR

Cᑍ Log any error encountered, and exit the program

Cᑍ

APINAM

QUSEI

DSPLY

EXSR

DONE

ENDSR

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Cᑍ

DONE

BEGSR

Cᑍ Exit the program

Cᑍ

EVAL

RETURN

ENDSR

ᑍINLR = '1'

Data Queue—Examples

This section includes the examples in “Using Data Queues versus User Queues” on

page A-15.

Data Queue—ILE COBOL Example

Refer to “Data Queue—ILE C Example” on page A-16 for the original example.

The following program also works with OPM COBOL.

IDENTIFICATION DIVISION.

ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

ᑍ

ᑍ Program Name: DQUEUEX

ᑍ

ᑍ Programming Language: COBOL

ᑍ

ᑍ Description: This program illustrates how to use APIs to

Appendix B. Original Examples in Additional Languages B-165

Download from Www.Somanuals.com. All Manuals Search And Download.

ᑍ

create and manipulate a ᑍDTAQ.

ᑍ Header Files Included: QUSEC - Error Code Parameter

ᑍ

QCAPCMD - Process Command API

ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

ᑍ

ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

PROGRAM-ID. DQUEUEX.

ENVIRONMENT DIVISION.

CONFIGURATION SECTION.

SOURCE-COMPUTER. IBM-AS4ðð.

OBJECT-COMPUTER. IBM-AS4ðð.

INPUT-OUTPUT SECTION.

FILE-CONTROL.

SELECT LISTING ASSIGN TO PRINTER-QPRINT

ORGANIZATION IS SEQUENTIAL.

DATA DIVISION.

FILE SECTION.

FD LISTING RECORD CONTAINS 132 CHARACTERS

LABEL RECORDS ARE STANDARD

DATA RECORD IS LIST-LINE.

ð1 LIST-LINE

PIC X(132).

WORKING-STORAGE SECTION.

ᑍ

ᑍ Error Code parameter include

ᑍ

COPY QUSEC OF QSYSINC-QLBLSRC.

ᑍ

ᑍ Process Command API Include

ᑍ

COPY QCAPCMD OF QSYSINC-QLBLSRC.

ᑍ

ᑍ Command strings

ᑍ

ð1 CRTLIB PIC X(5ð) VALUE "CRTLIB QUEUELIB".

ð1 DLTLIB PIC X(5ð) VALUE "DLTLIB QUEUELIB".

ð1 CRTDQ PIC X(5ð)

VALUE "CRTDTAQ QUEUELIB/EXAMPLEQ MAXLEN(1ð)".

ð1 DLTDQ PIC X(5ð) VALUE "DLTDTAQ QUEUELIB/EXAMPLEQ".

ᑍ

ᑍ Error message text

ᑍ

ð1 BAD-NEWS.

ð5 TEXT1

PIC X(14) VALUE "Failed in API ".

PIC X(1ð) VALUE "QCAPCMD".

ð5 API-NAME

ð5 TEXT2

ð5 EXCEPTION-ID PIC X(ð7).

PIC X(11) VALUE "with error ".

ᑍ

ᑍ Miscellaneous elements

ᑍ

ð1 COMMAND-LENGTH PIC S9(ð9) VALUE 5ð BINARY.

ð1 RECEIVER

PIC X(ð1).

ð1 RECEIVER-LENGTH PIC S9(ð9) VALUE ð BINARY.

ð1 OPTIONS-SIZE

ð1 FORMAT-NAME

ð1 FIRST-ERROR

PIC S9(ð9) VALUE 2ð BINARY.

PIC X(ð8) VALUE "CPOPð1ðð".

PIC X(ð1) VALUE "ð".

ð1 NAME-OF-QUEUE PIC X(1ð) VALUE "EXAMPLEQ".

B-166 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

ð1 NAME-OF-LIBRARY PIC X(1ð) VALUE "QUEUELIB".

ð1 SIZE-OF-MSG

ð1 WAIT-TIME

ð1 MSG

PIC S9(ð5) VALUE 1ð PACKED-DECIMAL.

PIC S9(ð5) VALUE ð PACKED-DECIMAL.

PIC X(1ð) VALUE "EXAMPLE".

PIC X(1ð).

ð1 MSG-BACK

ᑍ

ᑍ Beginning of mainline

ᑍ

PROCEDURE DIVISION.

MAIN-LINE.

ᑍ

ᑍ Initialize the error code parameter. To signal exceptions to

ᑍ this program by the API, you need to set the bytes provided

ᑍ field of the error code to zero. Because this program has

ᑍ exceptions sent back through the error code parameter, it sets

ᑍ the bytes provided field to the number of bytes it gives the

ᑍ API for the parameter.

ᑍ

MOVE 16 TO BYTES-PROVIDED.

ᑍ

ᑍ Initialize QCAPCMD options control block for CL processing

ᑍ

MOVE ð TO COMMAND-PROCESS-TYPE.

MOVE "ð" TO DBCS-DATA-HANDLING.

MOVE "ð" TO PROMPTER-ACTION.

MOVE "ð" TO COMMAND-STRING-SYNTAX.

MOVE SPACES TO MESSAGE-KEY.

MOVE LOW-VALUES TO RESERVED OF QCA-PCMD-CPOPð1ðð.

ᑍ

ᑍ Create library QUEUELIB

ᑍ

CALL QCAPCMD USING CRTLIB, COMMAND-LENGTH, QCA-PCMD-CPOPð1ðð,

OPTIONS-SIZE, FORMAT-NAME, RECEIVER,

RECEIVER-LENGTH, RECEIVER-LENGTH, QUS-EC.

ᑍ

ᑍ If an exception occurs, the API returns the exception in the

ᑍ error code parameter. The bytes available field is set to

ᑍ zero if no exception occurs and greater than zero if an

ᑍ exception does occur.

ᑍ

IF BYTES-AVAILABLE > ð PERFORM ERROR-FOUND.

ᑍ

ᑍ Create a data queue called EXAMPLEQ in library QUEUELIB. The

ᑍ queue will have a maximum entry length set at 1ð, and will be

ᑍ FIFO (first-in first-out).

ᑍ

CALL QCAPCMD USING CRTDQ, COMMAND-LENGTH, QCA-PCMD-CPOPð1ðð,

OPTIONS-SIZE, FORMAT-NAME, RECEIVER,

RECEIVER-LENGTH, RECEIVER-LENGTH, QUS-EC.

ᑍ

ᑍ If an exception occurs, the API returns the exception in the

ᑍ error code parameter. The bytes available field is set to

ᑍ zero if no exception occurs and greater than zero if an

ᑍ exception does occur.

ᑍ

IF BYTES-AVAILABLE > ð PERFORM ERROR-FOUND.

Appendix B. Original Examples in Additional Languages B-167

Download from Www.Somanuals.com. All Manuals Search And Download.

ᑍ

ᑍ Send information to the data queue.

ᑍ

CALL "QSNDDTAQ" USING NAME-OF-QUEUE, NAME-OF-LIBRARY,

SIZE-OF-MSG, MSG.

ᑍ

ᑍ Retrieve information from the data queue.

ᑍ

CALL "QRCVDTAQ" USING NAME-OF-QUEUE, NAME-OF-LIBRARY,

SIZE-OF-MSG, MSG-BACK, WAIT-TIME.

ᑍ

ᑍ Display the returned message

ᑍ

DISPLAY MSG-BACK.

ᑍ

ᑍ Delete the data queue

ᑍ

CALL QCAPCMD USING DLTDQ, COMMAND-LENGTH, QCA-PCMD-CPOPð1ðð,

OPTIONS-SIZE, FORMAT-NAME, RECEIVER,

RECEIVER-LENGTH, RECEIVER-LENGTH, QUS-EC.

ᑍ

ᑍ If an exception occurs, the API returns the exception in the

ᑍ error code parameter. The bytes available field is set to

ᑍ zero if no exception occurs and greater than zero if an

ᑍ exception does occur.

ᑍ

IF BYTES-AVAILABLE > ð PERFORM ERROR-FOUND.

ᑍ

ᑍ Delete the library

ᑍ

CALL QCAPCMD USING DLTLIB, COMMAND-LENGTH, QCA-PCMD-CPOPð1ðð,

OPTIONS-SIZE, FORMAT-NAME, RECEIVER,

RECEIVER-LENGTH, RECEIVER-LENGTH, QUS-EC.

ᑍ

ᑍ If an exception occurs, the API returns the exception in the

ᑍ error code parameter. The bytes available field is set to

ᑍ zero if no exception occurs and greater than zero if an

ᑍ exception does occur.

ᑍ

IF BYTES-AVAILABLE > ð PERFORM ERROR-FOUND.

ᑍ

STOP RUN.

ᑍ

ᑍ End of MAINLINE

ᑍ

ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

ᑍ

ERROR-FOUND.

ᑍ

ᑍ Process errors returned from the API.

ᑍ

ᑍ If first error found, then open QPRINT ᑍPRTF

ᑍ

IF FIRST-ERROR = "ð" OPEN OUTPUT LISTING,

MOVE "1" TO FIRST-ERROR.

ᑍ

B-168 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

ᑍ Print the error and the API that received the error

ᑍ

MOVE EXCEPTION-ID OF QUS-EC TO EXCEPTION-ID OF BAD-NEWS.

WRITE LIST-LINE FROM BAD-NEWS.

Data Queue—OPM RPG Example

Refer to “Data Queue—ILE C Example” on page A-16 for the original example.

Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Fᑍ

Fᑍ Program Name: DQUEUEX

Fᑍ

Fᑍ Programming Language: OPM RPG

Fᑍ

Fᑍ Description: This program illustrates how to use APIs to

Fᑍ

create and manipulate a ᑍDTAQ.

Fᑍ Header Files Included: QUSEC - Error Code Parameter

Fᑍ

QCAPCMD - Process Command API

Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Fᑍ

FQPRINT O F

132

PRINTER

Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Iᑍ

Iᑍ Error Code parameter include

Iᑍ

I/COPY QSYSINC/QRPGSRC,QUSEC

Iᑍ

Iᑍ Process Command API Include

Iᑍ

I/COPY QSYSINC/QRPGSRC,QCAPCMD

Iᑍ

Iᑍ Command strings

Iᑍ

I I

'CRTLIB LIB(QUEUELIB)'

1 2ð CRTLIB

'DLTLIB LIB(QUEUELIB)' 21 4ð DLTLIB

'CRTDTAQ DTAQ(QUEUELI- 41 82 CRTDQ

'B/EXAMPLEQ) MAXLEN(1-

'ð)'

I I

Iᑍ

'DLTDTAQ DTAQ(QUEUELI- 83 113 DLTDQ

'B/EXAMPLEQ)'

Iᑍ Miscellaneous data structure

Iᑍ

1 1ðð CMDSTR

B 1ð1 1ð4ðLENSTR

B 1ð5 1ð8ðSIZE

B 1ð9ð112ðRCVSIZ

113 113 FSTERR

114 123 APINAM

I I

2ð

'ð'

Cᑍ

Cᑍ Beginning of mainline

Cᑍ

Appendix B. Original Examples in Additional Languages B-169

Download from Www.Somanuals.com. All Manuals Search And Download.

Cᑍ Initialize the error code parameter. To signal exceptions to

Cᑍ this program by the API, you need to set the bytes provided

Cᑍ field of the error code to zero. Because this program has

Cᑍ exceptions sent back through the error code parameter, it sets

Cᑍ the bytes provided field to the number of bytes it gives the

Cᑍ API for the parameter.

Cᑍ

Z-ADD16

QUSBNB

Cᑍ

Cᑍ Initialize QCAPCMD options control block for CL processing

Cᑍ

Z-ADDð

QCABCB

QCABCC

QCABCD

QCABCF

MOVE 'ð'

MOVE ᑍBLANKS QCABCG

MOVE ᑍLOVAL

QCABCH

Cᑍ

Cᑍ Create library QUEUELIB

Cᑍ

MOVELCRTLIB

CMDSTR

LENSTR

Z-ADD2ð

Cᑍ

EXSR EXCCMD

Cᑍ Create a data queue called EXAMPLEQ in library QUEUELIB. The

Cᑍ queue will have a maximum entry length set at 1ð, and will be

Cᑍ FIFO (first-in first-out).

Cᑍ

MOVELCRTDQ

Z-ADD42

CMDSTR

LENSTR

Cᑍ

EXSR EXCCMD

Cᑍ Send information to the data queue.

Cᑍ

CALL 'QSNDDTAQ'

PARM 'EXAMPLEQ'QUENAM 1ð

PARM 'QUEUELIB'LIBNAM 1ð

PARM 1ð

PARM 'EXAMPLE' MSG

MSGSZ 5ð

1ð

Cᑍ

Cᑍ Retrieve information from the data queue.

Cᑍ

CALL 'QRCVDTAQ'

PARM 'EXAMPLEQ'QUENAM 1ð

PARM 'QUEUELIB'LIBNAM 1ð

PARM 1ð

PARM

PARM ð

MSGSZ 5ð

MSGBCK 1ð

WAITTM 5ð

Cᑍ

Cᑍ Display the returned message

Cᑍ

DSPLY

MSGBCK

CMDSTR

Cᑍ

Cᑍ Delete the data queue

Cᑍ

MOVELDLTDQ

B-170 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Z-ADD31

LENSTR

Cᑍ

EXSR EXCCMD

Cᑍ Delete the library

Cᑍ

MOVELDLTLIB

Z-ADD2ð

CMDSTR

LENSTR

Cᑍ

EXSR EXCCMD

Cᑍ

SETON

RETRN

Cᑍ

Cᑍ End of MAINLINE

Cᑍ

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Cᑍ

EXCCMD

BEGSR

Cᑍ Process requested CL command

Cᑍ

CALL 'QCAPCMD'

PARM

CMDSTR

LENSTR

QCABC

SIZE

PARM 'CPOPð1ðð'FORMAT 8

PARM

PARM ð

PARM

RCVVAR 1

RCVSIZ

QUSBN

Cᑍ If an exception occurs, the API returns the exception in the

Cᑍ error code parameter. The bytes available field is set to

Cᑍ zero if no exception occurs and greater than zero if an

Cᑍ exception does occur.

Cᑍ

QUSBNC

IFGT ð

MOVEL'QCAPCMD' APINAM

EXSR ERRCOD

ENDIF

ENDSR

Cᑍ

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Cᑍ

ERRCOD

BEGSR

Cᑍ Process errors returned from the API.

Cᑍ

Cᑍ If first error found, then open QPRINT ᑍPRTF

Cᑍ

FSTERR

IFEQ 'ð'

OPEN QPRINT

MOVEL'1'

ENDIF

FSTERR

Cᑍ

Cᑍ Print the error and the API that received the error

Appendix B. Original Examples in Additional Languages B-171

Download from Www.Somanuals.com. All Manuals Search And Download.

Cᑍ

EXCPTBADNEW

Cᑍ

ENDSR

OQPRINT E 1ð6

BADNEW

'Failed in API '

'with error '

APINAM

QUSBND

Data Queue—ILE RPG Example

Refer to “Data Queue—ILE C Example” on page A-16 for the original example.

Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Fᑍ

Fᑍ Program Name: DQUEUEX

Fᑍ

Fᑍ Programming Language: ILE RPG

Fᑍ

Fᑍ Description: This program illustrates how to use APIs to

Fᑍ

create and manipulate a ᑍDTAQ.

Fᑍ Header Files Included: QUSEC - Error Code Parameter

Fᑍ

QCAPCMD - Process Command API

Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Fᑍ

FQPRINT

F 132

PRINTER OFLIND(ᑍINOF) USROPN

Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Dᑍ

Dᑍ Error Code parameter include

Dᑍ

D/COPY QSYSINC/QRPGLESRC,QUSEC

Dᑍ

Dᑍ Process Command API Include

Dᑍ

D/COPY QSYSINC/QRPGLESRC,QCAPCMD

Dᑍ

Dᑍ Command strings

Dᑍ

DCRTLIB

DDLTLIB

DCRTDQ

'CRTLIB LIB(QUEUELIB)'

'DLTLIB LIB(QUEUELIB)'

'CRTDTAQ DTAQ(QUEUELIB/+

EXAMPLEQ) MAXLEN(1ð)'

'DLTDTAQ DTAQ(QUEUELIB/EXAMPLEQ)'

DDLTDQ

Dᑍ

Dᑍ Miscellaneous data structure

Dᑍ

DCMD_STR

DLEN_STR

DCAPð1ðð_SZ

DRCVVAR_SZ

DAPI_NAME

DFIRST_ERR

Cᑍ

1ðð

9B ð

9B ð INZ(%SIZE(QCAPð1ðð))

9B ð INZ(ð)

1ð

INZ('ð')

B-172 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Cᑍ Beginning of mainline

Cᑍ

Cᑍ Initialize the error code parameter. To signal exceptions to

Cᑍ this program by the API, you need to set the bytes provided

Cᑍ field of the error code to zero. Because this program has

Cᑍ exceptions sent back through the error code parameter, it sets

Cᑍ the bytes provided field to the number of bytes it gives the

Cᑍ API for the parameter.

Cᑍ

EVAL

QUSBPRV = %SIZE(QUSEC)

Cᑍ

Cᑍ Initialize QCAPCMD options control block for CL processing

Cᑍ

EVAL

QCACMDPT = ð

QCABCSDH = 'ð'

QCAPA = 'ð'

QCACMDSS = 'ð'

QCAMK = ᑍBLANKS

QCAERVED = ᑍLOVAL

Cᑍ

Cᑍ Create library QUEUELIB

Cᑍ

EVAL

CMD_STR = CRTLIB

LEN_STR = %SIZE(CRTLIB)

Cᑍ

EXSR

EXEC_CMD

Cᑍ Create a data queue called EXAMPLEQ in library QUEUELIB. The

Cᑍ queue will have a maximum entry length set at 1ð, and will be

Cᑍ FIFO (first-in first-out).

Cᑍ

EVAL

CMD_STR = CRTDQ

LEN_STR = %SIZE(CRTDQ)

Cᑍ

EXSR

EXEC_CMD

Cᑍ Send information to the data queue.

Cᑍ

CALL

PARM

'QSNDDTAQ'

'EXAMPLEQ ' NAME_OF_Q

'QUEUELIB ' NAME_OF_LB

1ð

MSG_SZ

5 ð

'EXAMPLE ' MSG

1ð

Cᑍ

Cᑍ Retrieve information from the data queue.

Cᑍ

CALL

PARM

'QRCVDTAQ'

'EXAMPLEQ ' NAME_OF_Q

'QUEUELIB ' NAME_OF_LB

1ð

MSG_SZ

MSG_BACK

WAIT_TIME

1ð

5 ð

Cᑍ

Cᑍ Display the returned message

Cᑍ

DSPLY

MSG_BACK

Cᑍ

Cᑍ Delete the data queue

Appendix B. Original Examples in Additional Languages B-173

Download from Www.Somanuals.com. All Manuals Search And Download.

Cᑍ

EVAL

CMD_STR = DLTDQ

LEN_STR = %SIZE(DLTDQ)

Cᑍ

EXSR

EXEC_CMD

Cᑍ Delete the library

Cᑍ

EVAL

CMD_STR = DLTLIB

EVAL

LEN_STR = %SIZE(DLTLIB)

Cᑍ

EXSR

EXEC_CMD

EVAL

ᑍINLR = '1'

RETURN

Cᑍ

Cᑍ End of MAINLINE

Cᑍ

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Cᑍ

EXEC_CMD

BEGSR

Cᑍ Process the requested CL command

Cᑍ

CALL

PARM

'QCAPCMD'

CMD_STR

LEN_STR

QCAPð1ðð

CAPð1ðð_SZ

FORMAT

'CPOPð1ðð'

RCVVAR

RCVVAR_SZ

QUSEC

Cᑍ If an exception occurs, the API returns the exception in the

Cᑍ error code parameter. The bytes available field is set to

Cᑍ zero if no exception occurs and greater than zero if an

Cᑍ exception does occur.

Cᑍ

QUSBAVL > ð

API_NAME = 'QCAPCMD'

ERRCOD

EVAL

EXSR

ENDIF

ENDSR

Cᑍ

Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

Cᑍ

ERRCOD

BEGSR

Cᑍ Process errors returned from the API.

Cᑍ

Cᑍ If first error found, then open QPRINT ᑍPRTF

Cᑍ

FIRST_ERR = 'ð'

QPRINT

OPEN

EVAL

ENDIF

FIRST_ERR = '1'

B-174 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Cᑍ

Cᑍ Print the error and the API that received the error

Cᑍ

EXCEPT

BAD_NEWS

Cᑍ

ENDSR

OQPRINT

BAD_NEWS

'Failed in API '

'with error '

API_NAME

QUSEI

UNIX-Type APIs—Examples

The simple example program on the following pages illustrates the use of several

integrated file system functions. The program performs the following operations:

.1/ Uses the getuid() function to determine the real user ID (uid).

.2/ Uses the getcwd() function to determine the current directory.

.3/ Uses the open() function to create a file. The owner (the person who created

the file) is given read, write, and execute authority to the file.

.4/ Uses the write() function to write a byte string to the file. The file is identified

by the file descriptor that was provided in the open operation (.3/).

.5/ Uses the close() function to close the file.

.6/ Uses the open() function to open the file for read only.

.7/ Uses the read() function to read a byte string from the file. The file is identi-

fied by the file descriptor that was provided in the open operation (.6/).

.8/ Uses the close() function to close the file.

.9/ Uses the unlink() function to remove the link to the file.

Using the Integrated File System—ILE C Example

This example program uses the integrated file system from ILE C.

/ᑍ

ᑍ/

/ᑍ Language:

ILE C

/ᑍ

/ᑍ Description:

Demonstrate use of integrated file system ᑍ/

from ILE C

/ᑍ

ᑍ/

#include <stdlib.h>

#include <stdio.h>

#include <fcntl.h>

#include <unistd.h>

#include <sys/types.h>

#define BUFFER_SIZE

#define TEST_FILE

2ð48

"test.file"

Appendix B. Original Examples in Additional Languages B-175

Download from Www.Somanuals.com. All Manuals Search And Download.

#define TEST_DATA

#define USER_ID

"Hello World!"

"user_id_"

char InitialFile[BUFFER_SIZE];

char InitialDirectory[BUFFER_SIZE] = ".";

char Buffer[32];

int FilDes = -1;

int BytesRead;

int BytesWritten;

uid_t UserID;

void CleanUpOnError(int level)

{

printf("Error encountered, cleaning up.\n");

switch ( level )

{

case 1:

printf("Could not get current working directory.\n");

break;

case 2:

printf("Could not create file %s.\n",TEST_FILE);

break;

case 3:

printf("Could not write to file %s.\n",TEST_FILE);

close(FilDes);

unlink(TEST_FILE);

break;

case 4:

printf("Could not close file %s.\n",TEST_FILE);

close(FilDes);

unlink(TEST_FILE);

break;

case 5:

printf("Could not open file %s.\n",TEST_FILE);

unlink(TEST_FILE);

break;

case 6:

printf("Could not read file %s.\n",TEST_FILE);

close(FilDes);

unlink(TEST_FILE);

break;

case 7:

printf("Could not close file %s.\n",TEST_FILE);

close(FilDes);

unlink(TEST_FILE);

break;

case 8:

printf("Could not unlink file %s.\n",TEST_FILE);

unlink(TEST_FILE);

break;

default:

break;

}

printf("Program ended with Error.\n"\

"All test files and directories may not have been removed.\n");

}

B-176 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

int main ()

{

.1/

/ᑍ Get and print the real user id with the getuid() function. ᑍ/

UserID = getuid();

printf("The real user id is %u. \n",UserID);

.2/

/ᑍ Get the current working directory and store it in InitialDirectory. ᑍ/

if ( NULL == getcwd(InitialDirectory,BUFFER_SIZE) )

{

perror("getcwd Error");

CleanUpOnError(1);

return ð;

}

printf("The current working directory is %s. \n",InitialDirectory);

.3/

/ᑍ Create the file TEST_FILE for writing, if it does not exist.

Give the owner authority to read, write, and execute. ᑍ/

FilDes = open(TEST_FILE, O_WRONLY | O_CREAT | O_EXCL, S_IRWXU);

if ( -1 == FilDes )

{

perror("open Error");

CleanUpOnError(2);

return ð;

}

printf("Created %s in directory %s.\n",TEST_FILE,InitialDirectory);

.4/

/ᑍ Write TEST_DATA to TEST_FILE via FilDes ᑍ/

BytesWritten = write(FilDes,TEST_DATA,strlen(TEST_DATA));

if ( -1 == BytesWritten )

{

perror("write Error");

CleanUpOnError(3);

return ð;

}

printf("Wrote %s to file %s.\n",TEST_DATA,TEST_FILE);

.5/

/ᑍ Close TEST_FILE via FilDes ᑍ/

if ( -1 == close(FilDes) )

{

perror("close Error");

CleanUpOnError(4);

return ð;

}

FilDes = -1;

printf("File %s closed.\n",TEST_FILE);

.6/

/ᑍ Open the TEST_FILE file for reading only. ᑍ/

if ( -1 == (FilDes = open(TEST_FILE,O_RDONLY)) )

{

Appendix B. Original Examples in Additional Languages B-177

Download from Www.Somanuals.com. All Manuals Search And Download.

perror("open Error");

CleanUpOnError(5);

return ð;

}

printf("Opened %s for reading.\n",TEST_FILE);

.7/

/ᑍ Read from the TEST_FILE file, via FilDes, into Buffer. ᑍ/

BytesRead = read(FilDes,Buffer,sizeof(Buffer));

if ( -1 == BytesRead )

{

perror("read Error");

CleanUpOnError(6);

return ð;

}

printf("Read %s from %s.\n",Buffer,TEST_FILE);

if ( BytesRead != BytesWritten )

{

printf("WARNING: the number of bytes read is "\

"not equal to the number of bytes written.\n");

}

.8/

/ᑍ Close the TEST_FILE file via FilDes. ᑍ/

if ( -1 == close(FilDes) )

{

perror("close Error");

CleanUpOnError(7);

return ð;

}

FilDes = -1;

printf("Closed %s.\n",TEST_FILE);

.9/

/ᑍ Unlink the file TEST_FILE ᑍ/

if ( -1 == unlink(TEST_FILE) )

{

perror("unlink Error");

CleanUpOnError(8);

return ð;

}

printf("Unlinking file %s.\n",TEST_FILE);

printf("Program completed successfully.\n");

return ð;

}

Using the Integrated File System—ILE COBOL Example

This example program uses the integrated file system from ILE COBOL.

PROCESS NOMONOPRC.

IDENTIFICATION DIVISION.

ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

ᑍ

B-178 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

ᑍ Language:

ᑍ

COBOL

ᑍ Description: Demonstrate use of integrated file system

ᑍ

from ILE COBOL

ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

ᑍ

ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ

PROGRAM-ID. IFS.

ENVIRONMENT DIVISION.

CONFIGURATION SECTION.

SOURCE-COMPUTER. IBM-AS4ðð.

OBJECT-COMPUTER. IBM-AS4ðð.

SPECIAL-NAMES.

ᑍ LINKAGE TYPE PROCEDURE FOR "geterrno",

LINKAGE TYPE PROCEDURE FOR "getuid",

LINKAGE TYPE PROCEDURE FOR "getcwd",

LINKAGE TYPE PROCEDURE FOR "open",

LINKAGE TYPE PROCEDURE FOR "write",

LINKAGE TYPE PROCEDURE FOR "close",

LINKAGE TYPE PROCEDURE FOR "read",

LINKAGE TYPE PROCEDURE FOR "unlink".

INPUT-OUTPUT SECTION.

FILE-CONTROL.

SELECT LISTING ASSIGN TO PRINTER-QPRINT

ORGANIZATION IS SEQUENTIAL.

DATA DIVISION.

ᑍ

FILE SECTION.

FD LISTING RECORD CONTAINS 132 CHARACTERS

LABEL RECORDS ARE STANDARD

DATA RECORD IS LIST-LINE.

ð1 LIST-LINE

PIC X(132).

ᑍ

WORKING-STORAGE SECTION.

ᑍ Report lines

ᑍ

ð1 REALID.

ð5 PRT-TEXT

PIC X(2ð) VALUE "The real user id is ".

PIC X(12).

ð5 USER

ð1 CURDIR.

ð5 PRT-TEXT

ð5 INITIALDIR

ð1 NEWFIL.

ð5 PRT-TEXT

ð5 FILENAME

ð1 DATAIN.

PIC X(21) VALUE "Current directory is ".

PIC X(1ðð).

PIC X(2ð) VALUE "Created file:

PIC X(1ðð).

ð5 PRT-TEXT

ð5 DATA-READ

PIC X(2ð) VALUE "Successfully read: ".

PIC X(1ðð).

ð1 ERRLIN.

ð5 PRT-TEXT

ð5 ERRVAL

PIC X(2ð) VALUE "The errno value is: ".

PIC X(12).

ᑍ

ᑍ Miscellaneous elements

ᑍ

ð1 BUFFER

ð1 LENGTH-OF-BUFFER

PIC X(32767).

PIC S9(ð9) BINARY VALUE 32767.

Appendix B. Original Examples in Additional Languages B-179

Download from Www.Somanuals.com. All Manuals Search And Download.

ð1 TESTFILE.

ð5 TEST-FILE

ð5 NULL-TERMINATE PIC X(ð1) VALUE LOW-VALUE.

PIC X(ð9) VALUE "test.file".

ð1 OFLAG

PIC X(ð4) VALUE X"ðððððð1A".

PIC X(ð4) VALUE X"ððððððð1".

PIC X(ð4) VALUE X"ððððð1Cð".

PIC X(12) VALUE "Hello World!".

PIC S9(ð9) BINARY VALUE 12.

PIC S9(ð9) BINARY.

ð1 OFLAG-READ

ð1 OMODE

ð1 TEST-DATA

ð1 SIZE-TEST-DATA

ð1 FILE-DESCRIPTOR

ð1 BYTES-READ

ð1 BYTES-WRITTEN

ð1 RETURN-INT

ð1 RETURN-PTR

PIC S9(ð9) BINARY.

POINTER.

ᑍ

ᑍ Beginning of mainline

ᑍ

PROCEDURE DIVISION.

MAIN-LINE.

OPEN OUTPUT LISTING.

ᑍ

ᑍ Get and print the real user id with the getuid function.

ᑍ

CALL "getuid" GIVING RETURN-INT.

ᑍ

ᑍ Check for error and report status.

ᑍ

IF RETURN-INT = -1 MOVE "Error getting real user id"

TO LIST-LINE,

PERFORM ERROR-FOUND,

ELSE

MOVE RETURN-INT TO USER,

WRITE LIST-LINE FROM REALID.

ᑍ

ᑍ Get the current working directory and store it in BUFFER

ᑍ

CALL "getcwd" USING BY VALUE ADDRESS OF BUFFER,

BY VALUE LENGTH-OF-BUFFER,

GIVING RETURN-PTR.

ᑍ

ᑍ Check for error and report status.

ᑍ

IF RETURN-PTR = NULL MOVE "Error getting real current dir"

TO LIST-LINE,

PERFORM ERROR-FOUND,

MOVE BUFFER TO INITIALDIR,

WRITE LIST-LINE FROM CURDIR.

ELSE

ᑍ

ᑍ Create the file test.file for writing. If it does not exist,

ᑍ give the owner authority to read, write, and execute.

ᑍ

CALL "open" USING BY VALUE ADDRESS OF TESTFILE,

BY VALUE OFLAG,

BY VALUE OMODE,

GIVING FILE-DESCRIPTOR.

ᑍ

ᑍ Check for error and report status.

ᑍ

IF FILE-DESCRIPTOR = -1 MOVE "Could not create file"

TO LIST-LINE,

B-180 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

PERFORM ERROR-FOUND,

MOVE TEST-FILE TO FILENAME,

WRITE LIST-LINE FROM NEWFIL.

ELSE

ᑍ

ᑍ Write TEST-DATA to test.file via file descriptor from open

ᑍ

CALL "write" USING BY VALUE FILE-DESCRIPTOR,

BY VALUE ADDRESS OF TEST-DATA,

BY VALUE SIZE-TEST-DATA,

GIVING BYTES-WRITTEN.

ᑍ

ᑍ Check for error and report status.

ᑍ

IF BYTES-WRITTEN = -1 MOVE "Could not write to file"

TO LIST-LINE,

PERFORM ERROR-FOUND,

ELSE

MOVE "Wrote to file successfully"

TO LIST-LINE,

WRITE LIST-LINE.

ᑍ

ᑍ Close test.file via file descriptor

ᑍ

CALL "close" USING BY VALUE FILE-DESCRIPTOR,

GIVING RETURN-INT.

ᑍ

ᑍ Check for error and report status.

ᑍ

IF RETURN-INT

= -1 MOVE "Could not close file"

TO LIST-LINE,

PERFORM ERROR-FOUND,

MOVE "Successfully closed file"

TO LIST-LINE,

ELSE

WRITE LIST-LINE.

ᑍ

ᑍ Open the file test.file for reading.

ᑍ

CALL "open" USING BY VALUE ADDRESS OF TESTFILE,

BY VALUE OFLAG-READ,

GIVING FILE-DESCRIPTOR.

ᑍ

ᑍ Check for error and report status.

ᑍ

IF FILE-DESCRIPTOR = -1 MOVE "Could not open file"

TO LIST-LINE,

PERFORM ERROR-FOUND,

ELSE

MOVE "File open successful"

TO LIST-LINE,

WRITE LIST-LINE.

ᑍ

ᑍ Read from test.file via file descriptor from open

ᑍ

CALL "read" USING BY VALUE FILE-DESCRIPTOR,

BY VALUE ADDRESS OF BUFFER,

BY VALUE LENGTH-OF-BUFFER,

GIVING BYTES-READ.

ᑍ

ᑍ Check for error and report status.

ᑍ

Appendix B. Original Examples in Additional Languages B-181

Download from Www.Somanuals.com. All Manuals Search And Download.

IF BYTES-READ = -1 MOVE "Read failed"

TO LIST-LINE,

PERFORM ERROR-FOUND,

ELSE IF BYTES-READ = BYTES-WRITTEN

MOVE BUFFER TO DATA-READ,

WRITE LIST-LINE FROM DATAIN,

ELSE MOVE "Data Truncation on Read"

TO LIST-LINE,

PERFORM ERROR-FOUND.

ᑍ

ᑍ Close test.file via file descriptor

ᑍ

CALL "close" USING BY VALUE FILE-DESCRIPTOR,

GIVING RETURN-INT.

ᑍ

ᑍ Check for error and report status.

ᑍ

IF RETURN-INT

= -1 MOVE "Could not close file"

TO LIST-LINE,

PERFORM ERROR-FOUND,

MOVE "Successfully closed file"

TO LIST-LINE,

ELSE

WRITE LIST-LINE.

ᑍ

ᑍ Unlink test.file

ᑍ

CALL "unlink" USING BY VALUE ADDRESS OF TESTFILE,

GIVING RETURN-INT.

ᑍ

ᑍ Check for error and report status.

ᑍ

IF RETURN-INT

= -1 MOVE "Unlink of file failed"

TO LIST-LINE,

PERFORM ERROR-FOUND,

MOVE "Unlink of file successful"

TO LIST-LINE,

ELSE

WRITE LIST-LINE.

ᑍ

MOVE "Program run is successful" TO LIST-LINE.

WRITE LIST-LINE.

STOP RUN.

ᑍ End of MAINLINE

ᑍ

ᑍ Common error reporting subroutine

ᑍ

ᑍ If errors occur, the Integrated File System exports the

ᑍ variable 'errno' to assist in determining the problem. As

ᑍ 'errno' is lowercase, ILE COBOL cannot directly import this

ᑍ variable and must use a C module to access it. If the

ᑍ developer has ILE C available, the following sample C code

ᑍ will import 'errno' and make it available to the COBOL

ᑍ application

ᑍ

#include <errno.h>

int geterrno()

{

B-182 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

ᑍ

return errno;

}

ᑍ To activate this C module remove the comment identifiers

ᑍ following the WRITE statement and remove the comment

ᑍ identifier from the geterrno declaration in the Configuration

ᑍ Section. Definitions for the returned errno are found in

ᑍ file QSYSINC/SYS member ERRNO.

ᑍ

ERROR-FOUND.

WRITE LIST-LINE.

ᑍ

CALL "geterrno" GIVING RETURN-INT.

MOVE RETURN-INT TO ERRVAL.

WRITE LIST-LINE FROM ERRLIN.

STOP RUN.

Using the Integrated File System—ILE RPG Example

This example program uses the integrated file system from ILE RPG.

Fᑍ

Fᑍ Language:

Fᑍ

ILE RPG

Fᑍ Description: Demonstrate use of integrated file system

Fᑍ

from ILE RPG

FQSYSPRT O

Dᑍ

F 132

PRINTER

Dᑍ Prototype the Integrated File System APIs

Dᑍ

Dgetuid

9B ð EXTPROC('getuid')

ᑍ EXTPROC('getcwd')

ᑍ VALUE

Dgetcwd

9B ð VALUE

Dopen

9B ð EXTPROC('open')

ᑍ VALUE

4A VALUE

9B ð EXTPROC('write')

9B ð VALUE

ᑍ VALUE

9B ð VALUE

9B ð EXTPROC('close')

9B ð VALUE

9B ð EXTPROC('open')

ᑍ VALUE

4A VALUE

9B ð EXTPROC('read')

9B ð VALUE

ᑍ VALUE

9B ð VALUE

Dwrite

Dclose

Dopen2

Dread

Dunlink

9B ð EXTPROC('unlink')

ᑍ VALUE

Dᑍ

Dᑍ errno prototype; see error subroutine for further information

Dᑍ

Appendix B. Original Examples in Additional Languages B-183

Download from Www.Somanuals.com. All Manuals Search And Download.

Dᑍerrno

9B ð EXTPROC('geterrno')

12A

32767A

ᑍ

DUser

DBuffer

DReturnPtr

DReturnInt

DFileDesc

Dtest_file

DInitialDir

Dtest_data

DBytesWrt

DBytesRead

DFileName

DPrintLine

DNull

9B ð

2ð48A INZ('test.file')

2ð48A

12A INZ('Hello World!')

9B ð

2ð49A

1ððA

CONST(X'ðð')

Cᑍ

Cᑍ Get and print the real user id with the getuid function.

Cᑍ

eval

ReturnInt = getuid

Cᑍ Check for error and report status.

Cᑍ

ReturnInt = -1

eval

exsr

eval

return

else

move

eval

PrintLine = 'Error getting real user id'

error

ᑍINLR = '1'

ReturnInt

PrintLine = 'The real user id is '

+ %TRIML(User)

User

except

endif

Cᑍ Get the current working directory and store it in Buffer.

Cᑍ

eval

ReturnPtr=getcwd(%ADDR(Buffer)

: %SIZE(Buffer))

Cᑍ Check for error and report status.

Cᑍ

ReturnPtr = ᑍNULL

eval

exsr

eval

return

else

PrintLine = 'Error getting current directory'

error

ᑍINLR = '1'

Cᑍ

Cᑍ Print current directory name remembering to scan for null terminator.

Cᑍ

Null

scan

eval

Buffer

NullFound

5 ð

InitialDir = %SUBST(Buffer:1:NullFound)

PrintLine = 'Current Directory is '

+ InitialDir

except

endif

Cᑍ

Cᑍ Create the file TEST_FILE for writing. If it does not exist,

Cᑍ give the owner authority to read, write, and execute.

B-184 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Cᑍ

eval

FileName = %TRIMR(test_file) + Null

FileDesc = open(%ADDR(FileName)

: x'ðððððð1A' : x'ððððð1Cð')

Cᑍ

Cᑍ Check for error and report status.

Cᑍ

FileDesc = -1

eval

exsr

eval

return

else

eval

PrintLine = 'Could not create file'

error

ᑍINLR = '1'

PrintLine = 'File '

+ %TRIMR(test_file)

+ ' created successfully'

except

end

Cᑍ Write test_data to test_file via FileDesc returned by open

Cᑍ

eval

BytesWrt = write(FileDesc

: %ADDR(Test_Data)

: %SIZE(Test_Data))

Cᑍ

Cᑍ Check for error and report status. If an error occurs,

Cᑍ attempt cleanup.

Cᑍ

BytesWrt = -1

PrintLine = 'Could not write to file'

error

ReturnInt = close(FileDesc)

ReturnInt = unlink(%ADDR(FileName))

ᑍINLR = '1'

eval

exsr

eval

return

else

eval

PrintLine = 'Wrote to '

+ %TRIMR(test_file)

+ ' successfully'

except

endif

Cᑍ Close test_file via FileDesc

Cᑍ

eval

ReturnInt = close(FileDesc)

Cᑍ

Cᑍ Check for error and report status. If an error occurs,

Cᑍ attempt cleanup.

Cᑍ

ReturnInt = -1

PrintLine = 'Could not close file'

error

ReturnInt = close(FileDesc)

ReturnInt = unlink(%ADDR(FileName))

ᑍINLR = '1'

eval

exsr

eval

return

else

eval

PrintLine = 'File '

Appendix B. Original Examples in Additional Languages B-185

Download from Www.Somanuals.com. All Manuals Search And Download.

+ %TRIMR(test_file)

+ ' closed successfully'

Cᑍ

except

endif

Cᑍ Open the file for read only

Cᑍ

eval

FileDesc = open2(%ADDR(FileName)

: x'ððððððð1')

Cᑍ

Cᑍ Check for error and report status. If an error occurs,

Cᑍ attempt cleanup.

Cᑍ

FileDesc = -1

PrintLine = 'Open of file failed'

error

ReturnInt = unlink(%ADDR(FileName))

ᑍINLR = '1'

eval

exsr

eval

return

else

eval

except

endif

PrintLine = 'Open of file successful'

Cᑍ

Cᑍ Read from file

Cᑍ

eval

BytesRead = read(FileDesc

: %ADDR(Buffer) : %SIZE(Buffer))

Cᑍ

Cᑍ Check for error and report status. If an error occurs,

Cᑍ attempt cleanup.

Cᑍ

BytesRead = -1

PrintLine = 'Read failed'

error

ReturnInt = close(FileDesc)

ReturnInt = unlink(%ADDR(FileName))

ᑍINLR = '1'

eval

exsr

eval

return

else

BytesRead = BytesWrt

PrintLine = 'Data successfully read: '

+ %TRIMR(Buffer)

eval

else

eval

endif

except

endif

PrintLine = 'Data truncation on read'

ReturnInt = close(FileDesc)

Cᑍ Close the LinkName file

Cᑍ

eval

Cᑍ

Cᑍ Check for error and report status. If an error occurs,

Cᑍ attempt cleanup.

Cᑍ

eval

ReturnInt = -1

PrintLine = 'Close of link failed'

B-186 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

exsr

error

eval

ReturnInt = close(FileDesc)

ReturnInt = unlink(%ADDR(FileName))

ᑍINLR = '1'

eval

return

else

eval

except

endif

PrintLine = 'Close of link successful'

Cᑍ

Cᑍ Unlink test_file

Cᑍ

eval

ReturnInt = unlink(%ADDR(FileName))

Cᑍ

Cᑍ Check for error and report status. If an error occurs,

Cᑍ attempt cleanup.

Cᑍ

ReturnInt = -1

PrintLine = 'Unlink of file failed'

error

ReturnInt = unlink(%ADDR(FileName))

ᑍINLR = '1'

eval

exsr

eval

return

else

eval

except

endif

PrintLine = 'Unlink of file successful'

Cᑍ End of main program

Cᑍ

eval

PrintLine = 'Program run is successful'

ᑍINLR = '1'

except

eval

return

Cᑍ

Cᑍ Common error reporting subroutine

Cᑍ

Cᑍ If errors occur, the integrated file system exports the variable

Cᑍ 'errno' to assist in determining the problem. As 'errno' is

Cᑍ lowercase, ILE RPG cannot directly import this variable and must

Cᑍ use a C module to access it. If the developer has ILE C

Cᑍ available, the following sample C code will import 'errno' and

Cᑍ make it available to the RPG application.

Cᑍ

#include <errno.h>

int geterrno()

{

return errno;

}

Cᑍ To activate this C module, remove the four comment identifiers

Cᑍ following the 'except' statement and remove the comment identifier

Cᑍ from the errno prototype. Definitions for the returned errno

Cᑍ are found in the file QSYSINC/SYS member ERRNO.

Cᑍ

error

begsr

except

eval

ReturnInt = errno

Appendix B. Original Examples in Additional Languages B-187

Download from Www.Somanuals.com. All Manuals Search And Download.

Cᑍ

move

ReturnInt

Errnoval

Cᑍ

eval

PrintLine = 'Errno is ' + Errnoval

Cᑍ

except

eval

except

endsr

PrintLine = 'Program ended in error'

OQSYSPRT E

PrintLine

1ðð

B-188 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Bibliography

This bibliography lists printed information that you need

to use the OS/400 APIs, background information for the

functions the APIs perform, and other information rele-

vant to specific types of applications. The books are

grouped in these categories:

Ÿ Security – Reference, SC41-5302, provides tech-

nical information about OS/400 security.

Ÿ System Manager Use, SC41-5321, provides infor-

mation about the commands and functions available

when the System Manager for AS/400 licensed

program is installed on one or more AS/400

Ÿ General-purpose books

Ÿ OS/400 API books

Ÿ Programming language books

systems in a network. System Manager Use

describes packaging software products so that they

can be distributed, installed, and serviced the same

way IBM licensed programs are managed.

If you want more information on a topic while you are

using this guide, see the Publications Reference,

SC41-5003, for related AS/400 publications.

OS/400 API Books

General-Purpose Books

These books contain OS/400 APIs:

Ÿ Common Programming APIs Toolkit/400 Reference,

SC41-4802, describes considerations for creating,

running, and debugging Common Programming

APIs Toolkit/400 (CPA) programs and provides

details on APIs supported by CPA. This book also

includes examples of CPA programs. CPA is an

optionally installable feature of OS/400.

These books provide general-purpose and background

information for the OS/400 licensed program:

Ÿ CL Programming, SC41-5721, discusses OS/400

functions and concepts that are relevant to pro-

gramming.

Ÿ CL Reference, SC41-5722, provides a description of

the AS/400 control language (CL) and its com-

mands. Each command description includes a

syntax diagram, parameters, default values,

keywords, and an example.

Ÿ CPI Communications Reference, SC26-4399, pro-

vides information about writing applications that

adhere to the Systems Application Architecture

(SAA) Communications interface. The manual

defines the elements of the SAA Communications

Common Programming Interface (CPI), which pro-

vides a programming interface that allows program-

to-program communications using IBM’s Systems

Network Architecture (SNA) logical unit 6.2 (LU6.2).

Ÿ AS/400 Licensed Internal Code Diagnostic Aids –

Volume 1, LY44-5900, and AS/400 Licensed

Internal Code Diagnostic Aids – Volume 2,

LY44-5901, provide a list of available object types in

hexadecimal format for use with the object APIs.

Ÿ DB2 for AS/400 Query Management Programming,

SC41-5703, provides information on how to deter-

mine database files to be queried for a report,

define a structured query language (SQL) query

definition, define a report form definition, and use

and write procedures that use query management

commands. It also includes information on how to

use the query management global variable support

and understand the relationship between the

OS/400 query management and the Query/400

licensed program.

Ÿ ILE Concepts, SC41-5606, describes the concepts

and terminology of the Integrated Language Envi-

ronment of the OS/400 operating system.

Ÿ Integrated File System Introduction, SC41-5711,

describes the concepts of the integrated file system

and briefly describes the user interfaces and pro-

gramming support for interacting with the integrated

file system.

Ÿ Printer Device Programming, SC41-5713, provides

information to help you understand and control

printing. This book provides specific information on

printing elements and concepts of the AS/400

system, printer file and print spooling support for

printing operations, and printer connectivity.

Ÿ GDDM Programming Guide, SC41-0536, provides

information about using OS/400 graphical data

display manager (GDDM) to write graphics applica-

tion programs.

Ÿ Guide to Enabling C2 Security, SC41-0103, pro-

vides information about planning, installing, setting

up, and managing your AS/400 system to meet the

requirements for C2 security. C2 is a level of secu-

rity defined by the United States Department of

Defense.

Ÿ Machine Interface Functional Reference,

SC41-5810, is a comprehensive reference to

machine interface (MI) instructions.

Ÿ PrintManager API Reference, S544-3699, provides

information the user needs to create and maintain

H-1

Download from Www.Somanuals.com. All Manuals Search And Download.

Bibliography

print descriptors used by the PrintManager inter-

face.

Ÿ ILE COBOL/400 Programmer’s Guide, SC09-2072,

describes how to write, compile, bind, run, debug,

and maintain ILE COBOL programs on the AS/400

system. It provides programming information on

how to call other ILE COBOL and non-ILE COBOL

programs, share data with other programs, use

pointers, and handle exceptions. It also describes

how to perform input/output operations on externally

attached devices, database files, display files, and

ICF files.

Ÿ REXX/400 Programmer’s Guide, SC41-5728,

explains REXX/400 programming concepts and dis-

cusses considerations in using this language on the

AS/400 system. It also describes REXX APIs and

provides examples that you can use to learn

REXX/400.

Ÿ REXX/400 Reference, SC41-5729, provides an

overview of the REXX/400 concepts and includes

information about keyword instruction syntax, func-

tion syntax, numerics, arithmetic, conditions, input

and output streams, testing, and double-byte char-

acter set (DBCS) support. The book also describes

REXX APIs.

Ÿ ILE COBOL/400 Reference, SC09-2073, describes

the ILE COBOL programming language. It provides

information on the structure of the ILE COBOL pro-

gramming language and on the structure of an ILE

COBOL source program. It also describes all Iden-

tification Division paragraphs, Environment Division

clauses, Data Division paragraphs, Procedure Divi-

sion statements, and Compiler-Directing statements.

Ÿ Sockets Programming, SC41-5422, describes the

sockets programming functions available on AS/400

systems and provides reference information on the

sockets programming interface.

Ÿ ILE RPG/400 Programmer’s Guide, SC09-2074, is a

guide for using the ILE RPG programming lan-

guage, which is an implementation of the RPG IV

language in the Integrated Language Environment

(ILE) on the AS/400 system. It includes information

on creating and running programs, with consider-

ations for procedure calls and interlanguage pro-

gramming. The guide also covers debugging and

exception handling and explains how to use AS/400

files and devices in RPG programs. Appendixes

include information on migration to RPG IV and

sample compiler listings. It is intended for people

with a basic understanding of data processing con-

cepts and of the RPG language.

Ÿ System API Reference, SC41-5801, describes

OS/400 APIs. It is intended for experienced appli-

cation programmers who are developing system-

level and other OS/400 applications.

Ÿ Ultimedia System Facilities Programming,

SC41-4652, provides information to programmers

for using Ultimedia System Facilities APIs to add

multimedia interfaces to existing applications and to

develop AS/400 programmable workstation (PWS)

multimedia applications.

Ÿ ILE RPG/400 Reference, SC09-2077, provides

information needed to write programs for the

AS/400 system using the ILE RPG programming

language. This book describes, position by position

and keyword by keyword, the valid entries for all

RPG specifications, and provides a detailed

description of all the operation codes and built-in

functions. This book also contains information on

the RPG logic cycle, arrays and tables, editing func-

tions, and indicators.

Programming Language Books

You might refer to these programming language books

while writing applications with the OS/400 APIs:

Ÿ COBOL/400 User’s Guide, SC09-1812, provides

information needed to design, write, test, and main-

tain COBOL programs on the AS/400 system.

Ÿ ILE C/400 Programmer’s Guide, SC09-2069, pro-

vides information on how to develop applications

using the ILE C language. It includes information

about creating, running, and debugging programs.

It also includes programming considerations for

interlanguage program and procedure calls, locales,

exception handling, database files, externally

described files, and device files. Some perfor-

mance tips are also described. An appendix

includes information on migrating source code from

extended program model (EPM) C/400 or System

C/400 to ILE C.

Ÿ RPG/400 Reference, SC09-1817, provides informa-

tion needed to write programs for the AS/400

system using the RPG programming language.

This book describes, position by position, the valid

entries for all RPG specifications, and provides a

detailed description of all the operation codes. This

book also contains information on the RPG logic

cycle, arrays and tables, editing functions, and indi-

cators.

Ÿ RPG/400 User’s Guide, SC09-1816, provides infor-

mation needed to write, test, and maintain RPG pro-

grams on the AS/400 system. The book provides

information on data organizations, data formats, file

processing, multiple file processing, automatic

Ÿ ILE C/400 Programmer’s Reference, SC09-2070,

provides information about how to write programs

that adhere to the Systems Application Architecture

C Level 2 definition and use ILE C specific functions

such as record I/O. It also provides information on

ILE C machine interface library functions.

report function, RPG command statements, testing

H-2 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Bibliography

and debugging functions, application design tech-

niques, problem analysis, and compiler service

information. The differences between the System/38

RPG III, System/38 compatible RPG, and RPG are

identified.

Bibliography H-3

Download from Www.Somanuals.com. All Manuals Search And Download.

Bibliography

H-4 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Index

Advanced Peer-to-Peer Networking (APPN) topology

information APIs

use of 8-9

AFP documents

AFP to ASCII Transform (QWPZTAFP) API 8-17

AFP to ASCII Transform (QWPZTAFP) API

use of 8-17

Special Characters

*EXT (external) format type

example A-14

*INT (internal) format type

example A-14

AFPDS (Advanced Function Printing data stream)

AFP to ASCII Transform (QWPZTAFP) API

use of 8-17

Numerics

5250 pass-through session 8-29

ALCOBJ (Allocate Object) command 2-16

alert APIs

use of 8-10

Allocate Object (ALCOBJ) command 2-16

allocating

object 2-16

AnyMail/400 Mail Server Framework APIs

use of 8-15

API (application programming interface)

Add Exit Program (QUSADDEP)

OPM COBOL example B-47

OPM RPG example B-54

Add Exit Program (QusAddExitProgram)

example of keyed interface 4-3

ILE C example 4-9

accessing

field value (initial library list)

ILE C example B-22

ILE COBOL example B-25

ILE RPG example B-29

OPM COBOL example B-25

field value in variable-length array

RPG example 3-19

HOLD attribute

ILE C example B-16

ILE COBOL example B-18

ILE RPG example B-21

OPM COBOL example B-18

OPM RPG example 3-17

action of API 1-3

Add Client (QZCAADDC, QzcaAddClient) API

use of 8-2

Add Environment Variable (ADDENVVAR)

command 8-22

Add Exit Program (QUSADDEP) API

OPM COBOL example B-47

OPM RPG example B-54

Add Exit Program (QusAddExitProgram) API

example of keyed interface 4-3

ILE C example 4-9

ILE COBOL example B-50

ILE RPG example B-58

Add Problem Log Entry (QsxAddProblemLogEntry)

API 8-19

ILE COBOL example B-50

ILE RPG example B-58

authorities and locks 3-2

backup and recovery APIs

use of 8-1

benefits of using 1-2

categories 1-3

client support APIs

use of 8-1

common information across APIs

advanced example 4-1

basic example 3-1

communications APIs

use of 8-2

compatibility with future releases 1-1

configuration APIs

use of 8-3

ADDENVVAR (Add Environment Variable)

command 8-22

adding

Create Product Definition (QSZCRTPD)

OPM RPG example A-3

Create Product Load (QSZCRTPL)

OPM RPG example A-3

Create Program (QPRCRTPG) 7-5

Create User Space (QUSCRTUS)

description 2-13

exit program

ILE C example 4-9

ILE COBOL example B-50

ILE RPG example B-58

OPM COBOL example B-47

OPM RPG example B-54

Advanced Function Printing data stream (AFPDS)

AFP to ASCII Transform (QWPZTAFP) API

use of 8-17

example B-66

ILE C example B-94

ILE COBOL example B-101

ILE RPG example B-106

X-1

Download from Www.Somanuals.com. All Manuals Search And Download.

Index

API (application programming interface) (continued)

Create User Space (QUSCRTUS) (continued)

OPM COBOL example B-61, B-101

OPM RPG example 5-4, B-71

debugger APIs

API (application programming interface) (continued)

List Objects That Adopt Owner Authority

(QSYLOBJP)

ILE C example B-94

ILE COBOL example B-101

ILE RPG example B-106

OPM COBOL example B-101

OPM RPG example 5-4

locating field in receiver variable 3-5

locating for use 2-1

Log Software Error (QPDLOGER)

ILE C example 6-2

ILE RPG example B-119

OPM COBOL example B-112

OPM RPG example B-116

message handling APIs

use of 8-8

use of 8-3

definition 1-1

Deregister Exit Point (QusDeregisterExitPoint)

ILE C example 4-19

ILE COBOL example B-87

ILE RPG example B-92

Deregister Exit Point (QUSDRGPT)

OPM COBOL example B-85

OPM RPG example B-90

description

authorities and locks 3-2

error messages 3-5

field descriptions 3-5

format 3-5

miscellaneous APIs

use of 8-29

optional parameter group 3-5

parameters 3-2

name

locating 3-1

required parameter group 3-3

Dynamic Screen Manager (DSM) APIs

use of 8-4

national language support (NLS) APIs

use of 8-9

network management APIs

use of 8-9

edit function APIs

use of 8-5

error messages 3-5

examples B-1

extracting field from format 3-5

field descriptions 3-5

file APIs

network security APIs

NetWare authentication entry APIs 8-20

NetWare connection APIs 8-20

use of 8-20

object APIs

data queue APIs 8-12

object APIs 8-14

use of 8-5

format 3-5

use of 8-11

getting started 2-1

hardware resource APIs

use of 8-6

hierarchical file system (HFS) APIs

use of 8-6

high-level language (HLL) APIs

use of 8-6

user index APIs 8-13

user queue APIs 8-13

user space APIs 8-14

office APIs

AnyMail/400 Mail Server Framework APIs 8-15

SNADS File Server APIs 8-16

use of 8-15

ILE APIs for the CEE environment 2-5

integrated file system 2-6

examples B-175

Operational Assistant APIs

use of 8-17

OptiConnect APIs

Integrated Language Environment (ILE)

error code 4-1

use of 8-3

optional parameter group 3-5

original program model (OPM)

error code 3-1

example 4-1

introduction 2-5, 4-1

registration facility using 4-2

Integrated Language Environment (ILE) CEE APIs

naming conventions 8-7

use of 8-7

example 3-1

introduction 2-4

Package Product Option (QSZPKGPO)

OPM RPG example A-3

parameters 3-2

introduction 2-1

list API example

performance collector APIs

use of 8-17

print APIs

List Objects That Adopt Owner Authority

(QSYLOBJP) 5-12

QSYLOBJP (List Objects That Adopt Owner

Authority) 5-12

use of 8-17

X-2 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Index

API (application programming interface) (continued)

problem management APIs

use of 8-18

API (application programming interface) (continued)

Set COBOL Error Handler (QLRSETCE)

OPM COBOL example B-112

software product APIs

process open list APIs

use of 8-29

use of 8-20

program and CL command APIs

use of 8-19

types of 1-3

UNIX-type APIs 2-6

ILE C example 4-9

use of 8-21

use of 8-1

ILE COBOL example B-50

ILE RPG example B-58

user interface APIs

use of 8-27

OPM COBOL example B-47

OPM RPG example B-54

registration facility APIs

user interface manager APIs

use of 8-27

versus CL commands 1-3

virtual terminal APIs

use of 8-19

use of 8-28

Remove Exit Program (QusRemoveExitProgram)

ILE C example 4-19

work management APIs

use of 8-28

ILE COBOL example B-87

ILE RPG example B-92

work station support APIs

use of 8-28

Remove Exit Program (QUSRMVEP)

OPM COBOL example B-85

OPM RPG example B-90

Report Software Error (QpdReportSoftwareError)

ILE COBOL example B-122

required parameter group 3-3

Retrieve Exit Information

Application Development Manager APIs

use of 8-6

application programming interface (API)

Add Exit Program (QUSADDEP)

OPM COBOL example B-47

OPM RPG example B-54

Add Exit Program (QusAddExitProgram)

example of keyed interface 4-3

ILE C example 4-9

(QusRetrieveExitInformation)

ILE C example 4-13

ILE COBOL example B-66

ILE RPG example B-75

ILE COBOL example B-50

ILE RPG example B-58

authorities and locks 3-2

backup and recovery APIs

use of 8-1

Retrieve Exit Information (QUSRTVEI)

OPM COBOL example B-61

OPM RPG example B-71

Retrieve Job Description Information

(QWDRJOBD) 3-29

benefits of using 1-2

categories 1-3

Retrieve Object Description (QUSROBJD)

ILE C example B-94

client support APIs

use of 8-1

ILE COBOL example B-101

ILE RPG example B-106

OPM COBOL example B-101

OPM RPG example 5-4

common information across APIs

advanced example 4-1

basic example 3-1

communications APIs

Retrieve Pointer to User Space (QUSPTRUS)

example B-66

use of 8-2

compatibility with future releases 1-1

configuration APIs

ILE C example B-94

ILE COBOL example B-101

ILE RPG example B-106

OPM COBOL example B-61, B-101

OPM RPG example 5-4, B-71

Retrieve User Space (QUSRTVUS) 2-13

SAA Common Execution Environment (CEE) 2-5

security APIs

use of 8-3

Create Product Definition (QSZCRTPD)

OPM RPG example A-3

Create Product Load (QSZCRTPL)

OPM RPG example A-3

Create Program (QPRCRTPG) 7-5

Create User Space (QUSCRTUS) B-66

description 2-13

use of 8-20

Set COBOL Error Handler

(QlnSetCobolErrorHandler)

ILE COBOL example B-122

example B-66

ILE C example B-94

ILE COBOL example B-101

ILE RPG example B-106

Index X-3

Download from Www.Somanuals.com. All Manuals Search And Download.

Index

application programming interface (API) (continued)

Create User Space (QUSCRTUS) (continued)

OPM COBOL example B-61, B-101

OPM RPG example 5-4, B-71

debugger APIs

application programming interface (API) (continued)

List Objects That Adopt Owner Authority

(QSYLOBJP)

ILE C example B-94

ILE COBOL example B-101

ILE RPG example B-106

OPM COBOL example B-101

OPM RPG example 5-4

locating field in receiver variable 3-5

locating for use 2-1

use of 8-3

definition 1-1

Deregister Exit Point (QusDeregisterExitPoint)

ILE C example 4-19

ILE COBOL example B-87

ILE RPG example B-92

Deregister Exit Point (QUSDRGPT)

OPM COBOL example B-85

OPM RPG example B-90

description

Log Software Error (QPDLOGER)

ILE C example 6-2

ILE RPG example B-119

OPM COBOL example B-112

OPM RPG example B-116

message handling APIs

use of 8-8

authorities and locks 3-2

error messages 3-5

field descriptions 3-5

format 3-5

miscellaneous APIs

use of 8-29

optional parameter group 3-5

parameters 3-2

name

locating 3-1

required parameter group 3-3

Dynamic Screen Manager (DSM) APIs

use of 8-4

national language support (NLS) APIs

use of 8-9

network management APIs

use of 8-9

edit function APIs

use of 8-5

error handling 2-30

error messages 3-5

examples B-1

network security APIs

NetWare authentication entry APIs 8-20

NetWare connection APIs 8-20

object APIs

extracting field from format 3-5

field descriptions 3-5

file APIs

data queue APIs 8-12

object APIs 8-14

use of 8-11

use of 8-5

format 3-5

getting started 2-1

hardware resource APIs

use of 8-6

user index APIs 8-13

user queue APIs 8-13

user space APIs 8-14

office APIs

AnyMail/400 Mail Server Framework APIs 8-15

SNADS File Server APIs 8-16

use of 8-15

hierarchical file system (HFS) APIs

use of 8-6

high-level language (HLL) APIs

use of 8-6

Operational Assistant APIs

use of 8-17

ILE APIs for the CEE environment 2-5

integrated file system 2-6

examples B-175

Integrated Language Environment (ILE)

error code 4-1

OptiConnect APIs

use of 8-3

optional parameter group 3-5

original program model (OPM)

error code 3-1

example 4-1

example 3-1

introduction 2-5, 4-1

introduction 2-4

registration facility using 4-2

Integrated Language Environment (ILE) CEE APIs

naming conventions 8-7

use of 8-7

Package Product Option (QSZPKGPO)

OPM RPG example A-3

parameter

length 2-17

introduction 2-1

parameters 3-2

list API example

performance 2-31

List Objects That Adopt Owner Authority

(QSYLOBJP) 5-12

performance collector APIs

use of 8-17

QSYLOBJP (List Objects That Adopt Owner

Authority) 5-12

X-4 System API Programming V4R1

Download from Www.Somanuals.com. All Manuals Search And Download.

Index

application programming interface (API) (continued)

print APIs

application programming interface (API) (continued)

Set COBOL Error Handler

(QlnSetCobolErrorHandler)

ILE COBOL example B-122

Set COBOL Error Handler (QLRSETCE)

OPM COBOL example B-112

software product APIs

use of 8-20

use of 8-17

problem management APIs

use of 8-18

process open list APIs

use of 8-29

program and CL command APIs

use of 8-19

types of 1-3

ILE C example 4-9

UNIX-type APIs 2-6

use of 8-21

ILE COBOL example B-50

ILE RPG example B-58

use of 8-1

user interface APIs

OPM COBOL example B-47

OPM RPG example B-54

registration facility APIs

use of 8-27

user interface manager APIs

use of 8-27

versus CL commands 1-3

virtual terminal APIs

use of 8-19

Remove Exit Program (QusRemoveExitProgram)

ILE C example 4-19

use of 8-28

work management APIs

use of 8-28

work station support APIs

use of 8-28

ILE COBOL example B-87

ILE RPG example B-92

Remove Exit Program (QUSRMVEP)

OPM COBOL example B-85

OPM RPG example B-90

Report Software Error (QpdReportSoftwareError)

ILE C example 6-7

APPN (Advanced Peer-to-Peer Networking) topology

information APIs

use of 8-9

array

ILE COBOL example B-122

ILE RPG example B-126

required parameter group 3-3

Retrieve Exit Information

(QusRetrieveExitInformation)

&cx2x. example 4-13

programming language use of 2-3

ASCII printers

AFP to ASCII Transform (QWPZTAFP) API 8-17

asynchronous communications using user

queue 8-13

Attention key buffering

definition 8-28

authorities and locks

description 3-2

ILE COBOL example B-66

ILE RPG example B-75

Retrieve Exit Information (QUSRTVEI)

OPM COBOL example B-61

OPM RPG example B-71

Retrieve Job Description Information

(QWDRJOBD) 3-29

automatic storage 7-36

backup and recovery APIs

List Save File (QSRLSAVF) API

use of 8-1

Retrieve Object Description (QUSROBJD)

ILE C example B-94

ILE COBOL example B-101

ILE RPG example B-106

OPM COBOL example B-101

OPM RPG example 5-4

Open List of Objects to be Backed Up (QEZOLBKL)

API 8-29

use of 8-29

Operational Assistant backup APIs

use of 8-1

Retrieve Device Capabilities (QTARDCAP) API

use of 8-1

Save Object List (QSRSAVO) API

use of 8-1

Retrieve Pointer to User Space (QUSPTRUS)

example B-66

ILE C example B-94

ILE COBOL example B-101

ILE RPG example B-106

OPM COBOL example B-61, B-101

OPM RPG example 5-4, B-71

Retrieve User Space (QUSRTVUS) 2-13

SAA Common Execution Environment (CEE) 2-5

security APIs

use of 8-1

BASIC

data type use 2-3

PRPQ 5799-FPK 2-3

use of 8-20

Index X-5

Download from Www.Somanuals.com. All Manuals Search And Download.

Index

BASIC language

Character Data Representation Architecture (CDRA)

APIs

data type use 2-3, 2-4

beginning

use of 8-9

instruction stream 7-22

benefits of using APIs 1-2

bibliography H-1

CHGENVVAR (Change Environment Variable)

command 8-22

CHGVAR (Change Variable) command 2-3, 2-4

choosing

binary data

programming language use of 2-3

binding directory

high-level language to use 2-3

CL (control language)

definition 4-1