IBM S544-5285-01 User Manual

Download

IBM Print Services Facility IBM

AFP Conversion and Indexing Facility: User’s Guide

S544-5285-01

IBM Print Services Facility IBM

AFP Conversion and Indexing Facility: User’s Guide

S544-5285-01

Note

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

| Second Edition (January 1999) | This edition applies to AFP Conversion and Indexing Facility, which is shipped with Print Services Facility 3.1.0 for OS/390 (program

| number 5655-B17), Print Services Facility/MVS 2.2.0 (program number 5695-040), Print Services Facility/VM 2.1.1 (program number | 5684-141), Print Services Facility/VSE 2.2.1 (program number 5686-040), IBM Print Services Facility for AIX 2.1.0 (program number | 5765-505), and IBM InfoPrint Manager for AIX 3.1.0 (program number 5648-B34). This edition applies to all subsequent releases and | modifications until otherwise indicated in new editions or Technical Newsletters. Be sure to use the correct edition for the level of the | product.

| Order publications through your IBM representative or the IBM branch office serving your locality. Publications are not stocked at the | address given below.

| The IBM Printing Systems Company welcomes your comments. A form for reader's comments is provided at the back of this | publication. If the form has been removed, you may send your comments to the following address:

| If you prefer to send comments electronically, use one of the following methods: |  Internet: printpub@us.ibm.com |  Fax: 1-800-524-1519 or 1-303-924-6873

Internet

| Visit our home page at http://www.printers.ibm.com

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

|  Copyright International Business Machines Corporation 1993, 1999. All rights reserved. | 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.

Contents

Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix

Programming Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix

Disclaimer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix

Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix

| Summary Of Changes ................................. xi

About This Publication ................................ xiii

Why Should I Read This Publication? ........................ xiii

What Do I Need To Know? .............................. xiii

How This Publication Is Organized .......................... xiv

What Terms Are Used In This Publication? ..................... xv

Related Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvi

Understanding Syntax Notation ........................... xvi

Highlighting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvi

Notational Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii

Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviii

Part 1. Information Common to AIX, OS/390, MVS, VM, and VSE Environments 1

Chapter 1. Planning Your AFP Conversion and Indexing Facility (ACIF)

Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

What Can I Do with ACIF? ............................... 3

Using ACIF for Different Tasks ............................. 5

Tasks You Can Do with ACIF ............................ 9

What Other IBM Products are Related to ACIF? .................. 15

The Workbench Viewer ............................... 15

AFP Toolbox for Multiple Operating Systems .................. 16

Document Composition Facility (DCF) ...................... 17

What are the Systems Considerations for ACIF? ................. 17

System Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

System Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Part 2. Using ACIF in the AIX Environment ........................... 21

Chapter 2. Using ACIF Parameters in AIX .................... 23

Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Flags and Values .................................... 27

Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

Implementation Specifics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

NLS Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

Suggested Reading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

Chapter 3. Example of an ACIF Application in AIX .............. 53

The Input File ...................................... 55

Specifying ACIF Processing Parameters for ASCII Input Data .......... 55

 Copyright IBM Corp. 1993, 1999 iii

Using a Parameter File with ASCII Input Data ................. 56

Specifying ACIF Processing Parameters for EBCDIC Input Data ........ 58

Using a Parameter File with EBCDIC Input Data ................ 58

Using the Shell with EBCDIC Literal Values ................... 61

Identifying the Locations of the Resources ..................... 61

Determining the Form Definition and the Page Definition ............. 62

Running the ACIF Job ................................. 62

ACIF Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

Concatenating ACIF Output Files .......................... 62

Accessing the Document File from the Workstation ................ 63

Transferring the Document File to the Workstation ............... 63

Mounting the AIX Directory on the Workstation ................. 64

Chapter 4. User Exits and Attributes of the Input Print File in AIX .... 65

User Programming Exits ................................ 65

Input Record Exit .................................... 66

Using the ACIF User Input Record Exits ..................... 68

Index Record Exit ................................... 69

Output Record Exit ................................... 70

Resource Exit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

Non-Zero Return Codes ................................ 74

Attributes of the Input Print File ............................ 74

Chapter 5. IBM AFP Fonts for ASCII Data .................... 77

Part 3. Using ACIF in the OS/390, MVS, VM, and VSE Environments ........ 79

Chapter 6. Using ACIF in OS/390, MVS, VM, and VSE ............ 81

Using ACIF in the OS/390 and MVS Environments ................ 81

Explaining the JCL Statements .......................... 81

Using ACIF in the VM Environment ......................... 82

Explaining the VM CMS Commands ....................... 83

Using ACIF in the VSE Environment ......................... 84

Explaining the VSE JCL Statements ....................... 85

| Chapter 7. Using ACIF Parameters in OS/390, MVS, VM, and VSE ..... 87

| Syntax Rules for OS/390, MVS, VM, and VSE Parameters ........... 87

Chapter 8. Example: ACIF Application in OS/390, MVS, VM, or VSE .. 113

Input File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

JCL, CMS Commands, and ACIF Processing Parameters ........... 115

OS/390 or MVS JCL to Invoke ACIF ...................... 115

VM CMS Commands to Invoke ACIF ...................... 117

VSE JCL to Invoke ACIF ............................. 117

ACIF Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

Concatenating Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

OS/390 or MVS JCL ............................... 121

VM CMS Commands ............................... 121

Chapter 9. User Exits and Attributes of the Input Print File in OS/390,

MVS, VM, and VSE ................................ 123

User Programming Exits ............................... 123

Input Record Exit ................................. 123

iv ACIF User’s Guide

Index Record Exit ................................. 125

Output Record Exit ................................ 126

Resource Exit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128

User Exit Search Order .............................. 130

Non-Zero Return Codes ............................. 130

Attributes of the Input Print File ........................... 130

Chapter 10. ACIF Messages for OS/390, MVS, VM, and VSE ....... 133

Multiple Message Scenarios ............................ 133

General Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

Part 4. Appendixes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177

Appendix A. Helpful Hints . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179

Working with control statements that contain numbered lines ......... 179

Placing TLEs in named groups ........................... 179

Working with file transfer and AIX ......................... 180

Understanding how ANSI and machine carriage controls are used ...... 181

Understanding common methods of transferring files to AIX from other

systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182

Physical media . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182

PC file transfer program ............................. 182

FTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183

Other Considerations for Transferring Files to AIX .............. 183

Invoke Medium Map (IMM) Structured Field ................... 183

Indexing Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184

Concatenating the Resource Group to the Document .............. 185

Specifying the IMAGEOUT Parameter ....................... 185

Appendix B. Data Stream Information ..................... 187

Tag Logical Element (TLE) Structured Field ................... 187

Format of the Resources File ............................ 188

Begin Resource Group (BRG) Structured Field ................. 189

Begin Resource (BR) Structured Field ....................... 189

End Resource (ER) and End Resource Group (ERG) Structured Fields ... 189

Appendix C. Format of the Index Object File ................. 191

Group-Level Index Element (IEL) Structured Field ................ 191

Page-Level Index Element (IEL) Structured Field ................ 192

Begin Document Index (BDI) Structured Field .................. 193

Index Element (IEL) Structured Field ....................... 193

Tag Logical Element (TLE) Structured Field ................... 194

End Document Index (EDI) Structured Field ................... 194

Appendix D. Format of the Output Document File ............. 195

Page Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198

Begin Document (BDT) Structured Field ..................... 198

Begin Named Group (BNG) Structured Field ................... 198

Tag Logical Element (TLE) Structured Field ................... 199

Begin Page (BPG) Structured Field ........................ 199

End Named Group (ENG), End Document (EDT), and End Page (EPG)

Structured Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199

Output MO:DCA-P Data Stream .......................... 200

Contents v

Composed Text Control (CTC) Structured Field ............... 200

Map Coded Font (MCF) Format 1 Structured Field .............. 200

Map Coded Font (MCF) Format 2 Structured Field .............. 200

Presentation Text Data Descriptor (PTD) Format 1 Structured Field .... 200

Inline Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200

Page Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200

Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201

Source Identifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201

References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201

Bibliography . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207

Print Services Facility (PSF) for OS/390 ..................... 207

Advanced Function Presentation (AFP) ...................... 207

Advanced Function Presentation (AFP) Architecture .............. 208

Advanced Function Presentation for Microfilm .................. 208

Fonts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208

Text Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209

InfoPrint Manager for AIX .............................. 209

Print Services Facility (PSF) for AIX ........................ 209

Print Services Facility for OS/2 (PSF/2) ...................... 209

EDMSuite OnDemand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210

Printers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210

i-data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210

OS/390 Version 2 Release 6 ............................ 211

eNetwork Communications Server ......................... 212

MVS/Enterprise Systems Architecture (ESA) Version 5 ............. 212

TCP/IP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213

TCP/IP for MVS ................................... 213

VTAM and NCP ................................... 213

Systems Network Architecture ........................... 214

AS/400 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214

Information/System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215

vi ACIF User’s Guide

Figures

1. How ACIF Fits into Advanced Function Presentation ............. 4

2. Using ACIF to Prepare Files for Viewing .................... 6

3. Using ACIF to Prepare Files for Distributed Printing ............. 7

4. Using ACIF to Prepare Files for Archiving and Retrieving .......... 8

5. AFP Document with Index Tags and the Index Object File ........ 11

6. Example Bank Statement Input File ...................... 12

7. ACIF Processing Parameters to Index the Bank Statement ........ 13

8. Workbench Viewer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

9. File Extensions for Resources ......................... 26

10. Example of a Customer’s Telephone Bill ................... 54

11. Line-Data Telephone Bill ............................ 55

12. Example of a Parameter File for ASCII Input Data ............. 56

13. Example of a Parameter File for EBCDIC Input Data ............ 59

14. Sample Input Record Exit C Language Header ............... 66

15. Sample Index Record Exit C Language Header ............... 69

16. Sample Output Record Exit C Language Header .............. 70

17. Sample Resource Exit C Language Header ................. 72

18. Sample Print File Attributes C Language Header .............. 74

19. Font Mapping Table for Use with the chars Parameter ........... 77

20. Sample OS/390 and MVS JCL to Invoke ACIF ............... 81

21. Sample VM CMS Commands to Invoke ACIF ................ 83

22. Sample VSE JCL to Invoke ACIF ....................... 84

| 23. ACIF Parameters, Tasks, and Operating Systems ............. 88

24. Example of a Customer's Phone Bill .................... 114

25. Line-Data Phone Bill .............................. 115

26. Example of a Telephone Bill for an OS/390 or MVS ACIF Application . 116

27. Example of a Telephone Bill for a VM ACIF Application ......... 117

28. Example of a Telephone Bill for a VSE ACIF Application ........ 118

29. Library Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120

30. Sample Input Record Exit DSECT ...................... 124

31. Sample Index Record Exit DSECT ..................... 125

32. Sample Output Record Exit DSECT ..................... 127

33. Sample Resource Exit DSECT ........................ 128

34. Sample Print File Attributes DSECT ..................... 131

35. Example of Code Containing Group-Level Indexing ............ 196

36. Example of Code Containing Group- and Page-Level Indexing ..... 197

 Copyright IBM Corp. 1993, 1999 vii

viii ACIF User’s Guide

Notices

References in this publication to products, programs, or services of IBM do not suggest or imply that IBM will make them available in all countries where IBM does business, or that only products, programs, or services of IBM may be used. Noninfringing equivalents may be substituted, but the user must verify that such substitutes, unless expressly designated by IBM, work correctly. No license, expressed or implied, to patents or copyrights of IBM is granted by furnishing this document. You can send license inquiries, in writing, to the IBM Director of Licensing, IBM Corporation, North Castle Drive, Armonk, NY 10504-1785, USA.

Programming Interfaces

This publication documents intended Programming Interfaces that allow the customer to write programs to obtain the services of ACIF.

ACIF provides no macros that allow a customer installation to write programs that use the services of ACIF.

Attention: Do not use any ACIF macros as programming interfaces.

Disclaimer

All examples are for illustration only. Any references to existing businesses or individuals is unintentional and does not imply any connection or relationship of any kind between the businesses, individuals, and IBM.

Trademarks

The following terms appear in this publication and are trademarks of the IBM Corporation:

 Advanced Function Presentation  AFP  AIX  AIX/6000  AT

 Bar Code Object Content Architecture  BCOCA  BookManager  IBM

|  InfoColor |  InfoPrint |  Intelligent Printer data Stream

 IPDS  MVS/DFP  MVS/ESA  MVS/SP

 OnDemand for AIX  Operating System/2  Operating System/400  OS/2

|  OS/390

 OS/400  Personal System/2  Presentation Manager

 Print Services Facility  PrintManager  Proprinter  PSF

 PSF for AIX  Quietwriter  RACF  RS/6000  System/370  System/390  S/390

 The IBM Printing Systems Company  VM/ESA  VM/XA  WIN-OS/2

 Copyright IBM Corp. 1993, 1999 ix

The following terms appear in this publication and are trademarks of other companies:

 Adobe, ATM-1, and PostScript are trademarks of Adobe Systems, Inc.  Microsoft, Microsoft Windows, and Windows are trademarks of Microsoft, Inc.  NFS is a trademark of SUN Microsystems, Inc.  UNIX is a trademark of UNIX System Laboratories, Inc.

x ACIF User’s Guide

Summary Of Changes

| This publication contains additions and changes to the previous edition, | S544-5285-00. The technical additions and changes are marked with a revision bar | to the left of the changes.

| The following new function has been added: |  INSERTIMM=YES|NO (see APAR PN92597) |  FONTECH=UNBOUNDED (see APAR PN77365) |  MCF2REF={CPCS | CF } (see APAR PQ04391) |  PRMODE=SOSI3 (see APAR PQ07139) |  RESTYPE=...[,OBJCON][,BCOCA][,GOCA][,IOCA] (see APAR PQ02350)

| The APARs addressed in this publication include: |  PN77365 | You can use the FONTECH parameter to indicate to ACIF that the fonts are in

| the unbounded box format. The only valid value for FONTECH is | other values will cause ACIF to terminate with an error. Unbounded box fonts | are supported

only

by the IBM 3800 printer.

unbounded

;

|  PN77694 | If you attempt to print the front and back sides of a sheet from different input

| bins, ACIF issues error message APK252I. |  PN84383 | You can use ACIF to create either a sequential data set or a partitioned data

| set. This publication describes the JCL parameters necessary to successfully | create a resource data set as either partitioned or sequential.

|  PN92597 and PN91755 | You can use an INSERTIMM parameter to view named page groups as

| stand-alone entities. |  PQ02350 | You can use additional values with the RESTYPE parameter: BCOCA, GOCA,

| and IOCA. ACIF searches the libraries specified by the PSEGLIB parameter | and USERLIB parameter to find these objects. If BCOCA, GOCA, and/or IOCA | is specified for RESTYPE, ACIF includes all of those types of objects required | to print or view the output document in the resource object file. Note that page | segments referenced by an IOB structured field cannot contain IM1 image or | PTOCA data.

|  PQ04391 | You can use a new conversion parameter and resource retrieval parameter to

| specify the way ACIF builds the MAP Coded Font 2 (MCF2) structured field in | the output file and the resobj file.

|  PQ07139 | ACIF supports a new PRMODE value. PRMODE=SOSI3 is supported in the

| same manner as by PSF/MVS, with each shift out character being converted to

 Copyright IBM Corp. 1993, 1999 xi

| a Set Coded Font Local Text control. Each shift in character is converted to a | Set Coded Font Local Text control and two blanks.

| New or changed messages include: |  APK246S (APAR PQ02350)

xii ACIF User’s Guide

About This Publication

This publication describes Advanced Function Presentation Conversion and Indexing Facility (ACIF), which allows you to format and print System/390 line data and unformatted ASCII files with IBM Print Services Facility in the following environments:

 OS/390  MVS  VM  VSE  AIX

ACIF also provides indexing and resource retrieval capabilities that allow you to view, archive, and retrieve document files. ACIF is supported in the OS/390, AIX, MVS, VM, and VSE environments by IBM Print Services Facility (PSF).

This section identifies who should use this publication, how it is organized, the formatting conventions used, and a list of publications related to the product.

Why Should I Read This Publication?

Application programmers should use this publication as a guide and reference when they are developing ACIF applications. ACIF is a batch application development utility enabling creation of documents that can be printed, viewed, distributed, archived, and retrieved with fidelity across systems and platforms. Using ACIF, you can:

 Convert line-format print files to MO:DCA-P documents  Add indexing tags to documents; create a separate index object file from the

indexing tags in a MO:DCA-P document

 Retrieve and package AFP resources needed for printing or viewing a

MO:DCA-P document

What Do I Need To Know?

This publication assumes that you are familiar with Advanced Function Presentation (AFP) concepts as well as the parameters that you specify when printing with Print Services Facility (PSF). If you are not familiar with AFP concepts, refer to

Advanced Function Presentation

parameters, refer to either: the PSF user's guide for your operating system, as listed in “Bibliography” on page 207.

IBM Print Services Facility for AIX: Print Submission

Guide to

. If you are not familiar with the PSF print

The publication also assumes that you are somewhat familiar with the MO:DCA-P architecture and structured fields. You may want to order

Content Architecture Reference Guide and Line Data Reference

Note: This publication provides ACIF messages for the OS/390, MVS, VM, and

VSE environments, which contain instructions for the system programmers responsible for maintaining the operating system and the PSF program

 Copyright IBM Corp. 1993, 1999 xiii

and

Advanced Function Presentation: Programming

to read about these topics.

Mixed Object Document

running on it. You may need to show these messages to your system programmer for assistance from time to time.

How This Publication Is Organized

This publication contains information pertaining to ACIF support for AIX, OS/390, MVS, VM, and VSE operating environments supported by PSF. However, because AIX users can invoke the PSF MSG command to view AIX messages on-line or print them, the AIX messages have not been duplicated in this publication.

 Part one contains information common to AIX, OS/390, MVS, VM, and VSE.

– Chapter 1, Planning Your AFP Conversion and Indexing Facility (ACIF)

Application presents an overview of tasks you can do with the ACIF product, describes several related products, and describes system considerations for using ACIF.

 Part two contains information specific to AIX.

– Chapter 2, Using ACIF Parameters in AIX describes the acif command,

including syntax rules, parameters, and their values.

– Chapter 3, Example of an ACIF Application in AIX describes the steps for

developing an ACIF application for AIX.

– Chapter 4, User Exits and Attributes of the Input Print File in AIX describes

the exits available in AIX for customizing ACIF.

– Chapter 5, IBM AFP Fonts for ASCII Data provides a list of the fonts for

use with unformatted ASCII input data in AIX.

 Part three contains information specific to OS/390, MVS, VM, and VSE.

– Chapter 6, Using ACIF in OS/390, MVS, VM, and VSE provides sample

code for invoking ACIF in the OS/390, MVS, VM, and VSE environments.

– Chapter 7, Using ACIF Parameters in OS/390, MVS, VM, and VSE

describes the parameters used for ACIF processing in the OS/390, MVS, VM, and VSE environments.

– Chapter 8, Example: ACIF Application in OS/390, MVS, VM, or VSE

describes the steps for developing an ACIF application.

– Chapter 9, User Exits and Attributes of the Input Print File in OS/390,

MVS, VM, and VSE describes the exits available for customizing ACIF.

– Chapter 10, ACIF Messages for OS/390, MVS, VM, and VSE provides the

ACIF messages, with suggestions for responding to the errors.

 The appendix section through the end of this publication contains more

information common to AIX, OS/390, MVS, VM, and VSE.

– Appendix A, Helpful Hints describes some considerations of using ACIF as

a front-end preprocessor for viewing, archiving, and retrieving information. – 36 describes the structured-field information for indexing. – Appendix C, Format of the Index Object File describes the file that enables

applications to determine the location of a page group or page within the

MO:DCA-P print file, based on the indexing tags. – Appendix D, Format of the Output Document File shows the three separate

output files that ACIF can produce.

xiv ACIF User’s Guide

To order additional printed copies of this publication, use order number Note: Publications that are referred to in this book or that contain additional

information about AFP, the OS/390 or MVS operating systems, PSF, and related products are listed in “Bibliography” on page 207.

What Terms Are Used In This Publication?

The following are terms this publication uses, plus a description of how those terms apply to your system:

Document In all systems:

 A file that contains AFP structured fields in Mixed Object:

Document Content Architecture - Presentation (MO:DCA-P) format

File In AIX and OS/2:

 A collection of related data

In OS/390 and MVS:

 A sequential data set  A member of a partitioned data set  A name of a DD card

S544-5285

In VM:

 A CMS file (filename filetype filemode)

In VSE:

 A sequential (SAM) file

Library In AIX:

 A directory in which AFP resources are stored

In OS/2:

 A directory

 A list of files stored on a disk or diskette

In OS/390 or MVS:

 A partitioned data set  A series of concatenated data sets

In VM:

 A collection of CMS files, generally with the same file type

In VSE:

 A library.sublibrary

About This Publication xv

Related Information

Publications that are referred to in this book or that contain additional information about Advanced Function Presentation (AFP), the MVS operating system, PSF, and related products are listed in the “Bibliography” on page 207.

For additional information about OS/390 and PSF for OS/390, refer to these Web pages:

http://www.ibm.com/s39/os39 http://www.printers.ibm.com/pbin-id/go?/pdocs/psf39/home.html

To obtain the latest documentation updates for OS/390 base elements and optional features that result from DOC APARs and PTFs, refer to the DOC APARs and ++HOLD DOC Web page:

http://www.s39.ibm.com/os39/bkserv/new_tech_info.html

To obtain the latest documentation updates for PSF for OS/390, refer to these members in SYS1.SAMPLIB:

Member Publication

APSGCUSU APSGDGNU APSGDLGU APSGMACU APSGSECU APSGUSRU

Understanding Syntax Notation

This publication uses consistent conventions for the following:  Highlighting

 Notational conventions

Highlighting

This publication uses the following highlighting conventions: Bold Identifies commands, keywords, files, directories, and other items,

whose names are predefined by the system or must be entered as is, such as acif.

PSF for OS/390: Customization PSF for OS/390: Diagnosis PSF for OS/390: Download for OS/390 PSF for OS/390: Messages and Codes PSF: Security Guide PSF for OS/390: User’s Guide

, S544-3291

, S544-5622

, G544-5623

, S544-5630

, G544-5624

, G544-5627

Italic

Identifies parameters whose actual names or values you supply. Italics also identify the names of publications.

Monospace Identifies examples of specific data values, examples of text similar to

what you might see displayed, examples of portions of program code similar to what you might write as a programmer, messages from the system, or information you should actually type.

xvi ACIF User’s Guide

Notational Conventions

This publication uses the following notational conventions:

 Italics within a command represent variables for which you must supply a value.

For example:

cpgid=

means that you enter cpgid= as shown and then replace the variable

page identifier

three-character decimal value (for example, 395) that defines an IBM-registered code page.

 Do not enter the following symbols as part of the command:

Bar | Braces { } Brackets [ ] Underscore _

These symbols have the following meanings:

 A vertical bar, |, between values indicates that you can only enter one of the

values with the command. For example:

cc={yes | no}

means that when you enter cc=, you can specify either yes or no as the value, but not both.

Note: In AIX, sometimes the vertical bar, |, acts as a pipe. When the pipe

code page identifier

code

with a value that represents any valid code page, which is

symbol appears between commands, it indicates that the output from the first command becomes the input to the second command. For example:

acif inputdd=myfile | enq -P3825A

means that the output generated by the acif command is the input to the AIX enq command, which prints the file.

 Braces, { }, around values indicate a required value. For example:

cc={yes | no}

means that when you enter cc=, you must also enter yes or no.

 Brackets, [ ], around parameters indicate that they are optional. For example:

[cc=

means that you do not have to enter either cc=

 An underscore, _, indicates the default value, which ACIF uses if you do not

specify the parameter with a non-default value. For example:

means that if the cc parameter is not entered, ACIF uses the default value of yes for the cc parameter.

value

][cctype=

cc={yes | no}

value

]

value

or cctype=

value

About This Publication xvii

Examples

PSF for AIX must be installed if you want to use examples documented in this publication that contain pathnames indicating PSF; for example: “inpexit=/usr/lpp/psf/bin/asciinpe”

xviii ACIF User’s Guide

Part 1. Information Common to AIX, OS/390, MVS, VM, and

VSE Environments

 Copyright IBM Corp. 1993, 1999 1

2 ACIF User’s Guide

Chapter 1. Planning Your AFP Conversion and Indexing Facility (ACIF) Application

This chapter provides:

 A description of ACIF and the tasks you can perform with it  A brief description of related products you can use with ACIF  A list of system prerequisites for using ACIF

What Can I Do with ACIF?

AFP Conversion and Indexing Facility (ACIF) is a batch application development utility you can use to:

 Convert line data or mixed data into MO:DCA-P data, which is an architected,

device-independent data stream used for interchanging documents between different platforms

 Index a document to enhance your ability to view, archive, or retrieve individual

pages or groups of pages from large documents; create a separate

object file

from the indexing tags

index

 Retrieve and package AFP resources needed for printing or viewing a

document and place them in a separate file, so that you can print and view the exact document, possibly years after its creation

Figure 1 on page 4 shows a high-level overview of how the ACIF application development utility fits into an installation's AFP process for creating, indexing, viewing, and printing documents.

 Copyright IBM Corp. 1993, 1999 3

Figure 1. How ACIF Fits into Advanced Function Presentation

The figure shows the resources and the text data, which can be provided and used by various AFP and AFP-compatible products. With ACIF, data and resources can feed into ACIF for processing and can be sent to a customer-supplied archival and retrieval system, to the spool, or to the Viewer application of AFP Workbench for viewing.

ACIF accepts data from your application in the following formats:  AFP data  MO:DCA-P data

 S/370 line-mode data

 Mixed-mode data

 Unformatted ASCII data (AIX only)

Put simply, ACIF can process application print data and AFP resources to produce three types of files:

1. An AFP document file

2. An AFP resource file

3. An AFP index object file

4 ACIF User’s Guide

With the files that ACIF creates, you can do the following:

 Use PSF to print the AFP document file. If you have specified resources in the

AFP document file, PSF for AIX references the AFP resource file for the names and locations of the resources. The AFP document file must be concatenated to the end of the resource file before the file is printed.

 Use the Viewer application of AFP Workbench (hereafter referred to as

“Workbench Viewer”) to view the AFP document file. Workbench Viewer takes MO:DCA-P data and resources as input to produce output that can be viewed.

 Store report files and the index file entries created by ACIF in a document

archival system, such as IBM OnDemand for AIX. OnDemand operates in a client/server environment and supports small office environments as well as large enterprise installations with hundreds of system users. OnDemand provides a server to store report files and other types of business documents. End-users can search for and retrieve files from the server with client programs that run under Microsoft Windows and MVS CICS/ESA. OnDemand supports full fidelity viewing and reprinting of report files on local and remote printers.

 Use your own archive system to store the ACIF-created files.  Use your own retrieval system to access information in the ACIF files, using

retrieval information in the index object file.

Using ACIF for Different Tasks

ACIF can process your files to allow:

 Viewing with Workbench Viewer  Printing locally and on other systems  Selective archiving and retrieval

Chapter 1. Planning Your AFP Conversion and Indexing Facility (ACIF) Application 5

Figure 2. Using ACIF to Prepare Files for Viewing

Figure 2 shows the path your data takes when you are preparing files for viewing with the Workbench Viewer.

1. The process begins with your application (1), which is the program that processes your print data.

2. Your application creates your print data (2a) and optionally creates ACIF

processing parameters (2b). Resources are stored in the PSF resource libraries (2c).

3. You run ACIF (3), specifying that it create the index object file (3a), the AFP document (3b), and the resource file (3c).

4. For optimal performance in locating pages in a file, you concatenate (4) the index object file (3a) to the AFP document (3b). If the resources used by the

6 ACIF User’s Guide

document are not present on the workstation where the Workbench Viewer is installed, you concatenate the resource file (3c) to the AFP document file. The order of concatenation must be as shown in Figure 2, with the document file concatenated last.

5. Transfer the needed files in binary format to the workstation.

6. Using the Workbench Viewer, view your indexed document. You can also print

the document from the Workbench Viewer.

Figure 3. Using ACIF to Prepare Files for Distributed Printing

Figure 3 shows the steps to perform to prepare your files for printing:

Chapter 1. Planning Your AFP Conversion and Indexing Facility (ACIF) Application 7

1. Run ACIF, specifying that the resource file (1b) be created along with the AFP document file (1a).

If you are using ACIF on AIX and your resources reside on another operating system, you can use the AIX Network File System (NFS) to mount them to the AIX system where you are running ACIF.

2. If the print driver program (PSF) that manages jobs for your target printer runs on a different operating system than the one you run ACIF on, transfer the files in binary format to the system where PSF runs.

If your resources are not present on the remote PSF platform, concatenate the AFP document file to the end of the resource file before submitting the file to PSF. If your resources are already present on the remote PSF platform, you do not have to concatenate or transmit them.

3. Submit your MO:DCA-P print job to PSF.

Figure 4. Using ACIF to Prepare Files for Archiving and Retrieving

Figure 4 shows numbered steps you can use to archive your files:

1. Run ACIF, specifying that both the index object file (1a) and the resource file (1c) be created.

2. Run your archival application to archive (3) all three files (1a, 1b, 1c), so that the document can later be retrieved (4) and viewed or printed with fidelity.

8 ACIF User’s Guide

Tasks You Can Do with ACIF

This section describes the three tasks for which you can use ACIF. The tasks are listed in the order in which they are described, not in any order in which they should be done.

 Converting data streams

 Indexing documents  Retrieving resources

Converting Data Streams

ACIF processes the following input data streams to create a MO:DCA-P document.  AFP data

 MO:DCA-P data

 S/370 line-mode data

 Line-mode data  Mixed-mode data

 Unformatted ASCII (AIX only)

The following sections describe each type of data and refer you to additional publications, if you need to better understand them:

AFP Data:

supports the following objects:  Graphics (GOCA)

 Presentation text (PTOCA)  Image (IOCA and IM)

 Bar-code (BCOCA) The AFP data stream also supports print resources such as fonts, overlays, page

segments, form definitions, and page definitions. For more information on this data stream format, refer to which points to publications describing the other types of data objects.

Mixed Object Document Content Architecture Data:

data as a valid input data stream, with the following restrictions:

 Every structured field must appear in one record and cannot span multiple

records.

 Each record (structured field) must contain a X'5A' character before the first

byte of the structured field introducer.

ACIF does not change the MO:DCA-P structured fields it processes, because they are already in the correct format. However, although the MO:DCA-P input data stream may contain multiple Begin Document (BDT) and End Document (EDT) structured fields, the ACIF output contains only one BDT/EDT structured-field pair.

The AFP data stream is a superset of the MO:DCA-P data stream and

Mixed Object Document Content Architecture Reference

ACIF supports MO:DCA-P

For more information about this data stream, refer to

Content Architecture Reference

S/370 Line-Mode Data:

that may begin with a single carriage control character, which may be followed by a single table reference character (TRC). After these characters, zero or more bytes of EBCDIC data may follow. ACIF formats S/370 line-mode data into pages by

Chapter 1. Planning Your AFP Conversion and Indexing Facility (ACIF) Application 9

S/370 line-mode data is characterized by records of data

Mixed Object Document

using a page-definition (PAGEDEF) resource, in the same way as does PSF. For more information about line data, refer to

Programming Guide and Line Data Reference

Advanced Function Presentation:

Mixed-Mode Data:

inclusion of some AFP structured fields, composed-text pages, and resource objects such as image, graphics, bar code, and text. For more information about this data stream, refer to

Line Data Reference

Unformatted ASCII Data:

workstation environment and has not been formatted for printing. Unformatted ASCII data is formatted by ACIF using a page definition resource. Unformatted ASCII data is contrasted with the type of ASCII data that contains control characters (or, escape sequences) for the IBM Proprinter and Quietwriter, and does not need to be formatted by ACIF before printing with PSF for AIX. Unformatted ASCII can also be submitted for printing with PSF for AIX without being converted by ACIF, but the output format is predetermined (using a Proprinter emulation font and 60 lines per page, for example).

A page definition can be created for use in an unformatted ASCII file to allow the use of AFP functions such as varied print directions, multiple-up printing, and different fonts in the output format. You can use IBM Page Printer Formatting Aid for AIX (PPFA for AIX) to create your own page definitions. PPFA for AIX is a separate feature of PSF for AIX that you can order. For information on how to create page definitions using PPFA for AIX, refer to

Aid: User's Guide

Mixed-mode data is a mixture of line-mode data, with the

Advanced Function Presentation: Programming Guide and

Unformatted ASCII data is data that is generated in the

IBM Page Printer Formatting

Indexing Documents

One of the principal tasks you can do with ACIF is indexing print files, which are also known as documents. When indexing with ACIF, you can divide (segment) a large print file into smaller, uniquely identifiable units, called the MO:DCA-named group structured fields. Using ACIF, you can divide the large bank-statement application into the individual groups by inserting in the file structured fields that define the group boundaries. A group is a named collection of sequential pages, which, in this application, consists of the pages describing a single customer's account. For example, when you print a bank-statement application, you probably produce a large printout consisting of thousands of individual customer statements. You can think of each of these statements as a smaller, separate unit, each of which is uniquely identified by an account number or other attributes such as date and Social Security number.

Using ACIF, you can also create an index object file, which enables you to:

 Retrieve individual statements from storage, based on an account number or

any other attribute

 More rapidly access the statements for viewing by, for example, the Workbench

Viewer.

 Archive individual statements or the entire indexed print file for long-term

storage and subsequent data management and reprinting, even years after its creation

groups

, as defined by

In addition to building an index-information file containing structured fields (the

index object file

), ACIF also inserts strings of character data called

tags

in the print

10 ACIF User’s Guide

file in structured-field format. ACIF inserts these same structured fields in the index object file. (The tags are contained in Tagged Logical Element [TLE] structured fields, which are described in Appendix A, Helpful Hints and 36) You can use the indexing-tag structured fields to identify a group of pages.1Figure 5 shows the relationship between the group-level tags and the entries in the index object file.

Figure 5. AFP Document with Index Tags and the Index Object File

ACIF can create an index object file for the following types of input files:

 S/370 line-mode data or mixed-mode data  Unformatted ASCII data  AFP data produced by the AFP Application Programming Interface, Document

Composition Facility (DCF), or by AFP Toolbox, with or without indexing tags Note: In this instance, you are producing an index object file from an input file

that contains index tags. You are not adding new indexing tags to an existing file.

 AFP data produced by any other application

ACIF provides the following ways for you to generate the indexing tags placed in the print file:

 Using values present in the input data itself, when the data has been formatted

so that ACIF can reliably locate the values. This kind of indexing is called

indexing with data values.

 Using literal values that you specify to ACIF, which is useful when the values

you want to use in the indexing tags are not consistently present in the data. This kind of indexing is called

indexing with literal values.

Indexing with Data Values:

Some applications such as payroll or accounting statements contain data that might be appropriate to use for indexing tags. In the bank statement example, the account number is a type of data value that you may want to tag. You can then archive a single customer's account statement using the

With ACIF, you can generate group-level tags; with Document Composition Facility (DCF), AFP Toolbox, and AFP Application Programming Interface (AFP API), you can generate both group-level tags and page-level tags. These products will be described later in this chapter.

Chapter 1. Planning Your AFP Conversion and Indexing Facility (ACIF) Application

account number, and you can retrieve and view the same statement using the account number. If the data value you want to use in an indexing tag is consistently located in the same place for each statement, you can specify ACIF parameters that create a separate group of pages for each statement. The ACIF parameters that you use in this case are the TRIGGERn, FIELDn, and INDEXn parameters.

Indexing with Literal Values:

Some print files such as technical documents and memos cannot be divided easily into groups of pages using values in the data, because no data value is consistently present in the same location. Likewise, the output of an application may not contain the data you would like to use for an indexing tag. In these cases, you can specify one or more literal values for ACIF to use in the indexing tags for a single group of pages. The ACIF parameter that you use in this case is the FIELDn parameter.

Notes:

1. If you are using ACIF to add indexing tags to a file, and the input file already contains indexing tags, ACIF issues an error message and stops processing. If the input file already contains indexing tags, you can create the index object file by running ACIF

without

specifying any indexing parameters.

2. ACIF includes the name of the output document in the index object file and includes the name of the index object file in the output document, which provides a method of correlating the index object file with the appropriate output document.

An Indexing Example Using Data Values:

This example shows how to use the ACIF parameters described in Chapter 2, “Using ACIF Parameters in AIX” on page 23 and Chapter 7, “Using ACIF Parameters in OS/390, MVS, VM, and VSE” on page 87. Figure 6 shows the print file for a typical bank statement.

1ACCOUNT NUMBER: 445-66-3821-5 PAGE 1 CUSTOMER NAME: HENRY WALES DATE: 9/3/91 CHECK# 1 - 455. CHECK# 2 - 337.85 ... 1ACCOUNT NUMBER: 333-56-4378-5 PAGE 1 CUSTOMER NAME: KATHERINE CHARLES DATE: 9/3/91 CHECK# 221 - 5. CHECK# 222 - 1567.35 ...

Figure 6. Example Bank Statement Input File

In Figure 6, the print file contains bank statements dated September 30, 1991 (09/30/91). Each statement has the same general format, although statements may vary in size or number of pages. Assume you want to index the bank statements using the account number and the date. Although the account number identifies each customer's account, the date is important to differentiate one month's statement from another. For ACIF to extract the account number and date, it must first locate the records that contain the required information.

12 ACIF User’s Guide

Because ACIF can process different data streams with various file formats (carriage control characters, no carriage control characters, table-reference characters, and so on), it requires necessary index values. You may require multiple triggers to uniquely identify the start of a new statement. To index the bank statements using the account number and the date, first define the trigger values and the fields as shown in Figure 7:

trigger1=\,1,'1'

trigger2=,39,'PAGE 1' field1=,18,3 field2=,22,2 field3=,25,4 field4=,3,1 field5=2,8,2 field6=2,11,2 field7=2,14,2 index1='Account Number',field1,field2,field3,field4 index2='Date',field5,field6,field7

Figure 7. ACIF Processing Parameters to Index the Bank Statement

triggers

to determine an

anchor point

from which it can locate the

The information in Figure 7 defines two trigger values:

 The first trigger instructs ACIF to examine the first byte of every input record

until it finds the occurrence of an ANSI skip-to-channel 1 carriage control character ('1'). Because each page created by this particular application may contain this carriage control character, this trigger alone does not identify the start of a new bank statement.

 The second trigger accomplishes this task. When ACIF locates a record

containing a '1' in the first byte, it looks for the string ‘PAGE 1’ in that same record, starting at byte (column) 39. If this condition is found, a new statement exists, and ACIF uses the record containing trigger1 as the anchor point. The field definitions are relative to this anchor point.

In the example ( Figure 7), the account number has four fields. These fields can be defined as one field if the dashes are included as part of the index information. The date has three fields to remove the forward slashes. After ACIF has extracted all of the necessary indexing information for this statement, it begins looking for trigger1 again. This process is repeated until the entire print file is processed.

In summary, when ACIF indexes an input file, it first scans the input file to find matches for its parameters. When ACIF finds matches in the input file, it inserts structured fields immediately prior to the corresponding pages of the output file. Also, ACIF places structured fields in the index object file that point to matches in the output file. ACIF inserts structured fields before the corresponding pages of the output file where it finds the matches in the input file. ACIF also places structured fields that point to these matches in the index object file.

Indexing Limitations:

For a line-mode application that does not contain the appropriate data values in the application output and for which literal values are not suitable, the application program cannot insert tagging structured fields in the print data, because tagging structured fields are not allowed in mixed-mode data. In the case where the application data does not contain the necessary appropriate data values for indexing, the application could add the index triggers. One possible

Chapter 1. Planning Your AFP Conversion and Indexing Facility (ACIF) Application 13

location is the record containing the new-page carriage control character (for example, a skip-to-channel 1). The application would need to add the indexing trigger and attribute value to this record at a specified location on each statement in the print file. This allows ACIF to retrieve this information at processing time. (For information about different types of carriage control characters, see the description of the cctype parameter on 27 for AIX, or 89 for OS/390 or MVS, VM, and VSE.)

Retrieving Resources

ACIF can determine the list of required AFP resources needed to view or print the document and can retrieve these resources from the specified libraries. Then, you can view or print the document with fidelity. This ACIF function is especially valuable if the resources are not present on the designated platform in a distributed print environment.

When you archive a document, ACIF also allows you to archive the retrieved resources (fonts, page segments, and so on) in the form in which they existed when the file was printed. By archiving the original resources, you can reproduce the document with fidelity at a later date, even if the resources have changed since that time. For example, suppose that a page segment contains a company officer's signature and is included in the print data. When someone else replaces the officer, current print files must reference the new officer's signature, but archived files must reference the former officer's signature.

The type of resources ACIF retrieves from specified libraries is based on the value of the restype parameter. When ACIF processes a print file, it:

 Identifies the resources requested by the print file

While ACIF converts the input file into an AFP document, it builds a list of all the resources necessary to successfully print the document, including all the resources referenced inside other resources. For example, a page can include an overlay, and an overlay can reference other resources such as fonts and page segments.

 Creates a resource file

| ACIF creates a logical resource library in the form of an AFP resource group | and stores this resource group in a resource file. If you specify | restype=fdef,font,pseg,ovly,objcon,bcoca, goca, ioca, or restype=all, this | resource file contains all the resources necessary to view or print the document | with fidelity. Each time ACIF processes a print file, it can create a resource file | in one of two different formats:

| – A partitioned data set (PDS). The PDS format is supported only on OS/390 | or MVS and allows the resource file to be referenced as a user library | (USERLIB) when printing with PSF.

| – An AFP data-stream resource group. The AFP resource-group format is | useful when you are routing print output to remote AFP platforms (for | example, PSF/2 on OS/2) or when you are viewing the output with the | Viewer application of AFP Workbench.

 Calls the specified resource exit for each resource it retrieves

Before ACIF retrieves a resource from a library, it first calls the resource exit program as specified in the resexit parameter. You can write an exit program to filter out any resources you do not want included in the resource file. For example, the exit program can specify that all referenced fonts except for a

14 ACIF User’s Guide

specific typeface be included in the resource file. The only way to accomplish this is by using the resource exit.

 Includes the name of the output document in the resource file and the name of

the resource file in the output document, which provides a method of correlating resource files with the appropriate output document

An example of specifying ACIF processing parameters for resource retrieval can be found in Chapter 8, “Example: ACIF Application in OS/390, MVS, VM, or VSE” on page 113 and Chapter 3, “Example of an ACIF Application in AIX” on page 53.

What Other IBM Products are Related to ACIF?

Although ACIF is a stand-alone utility, it has been designed for use with other programs. These programs are described in this section:

 The Workbench Viewer  AFP Application Programming Interface (AFP API)

 AFP Toolbox

 Document Composition Facility (DCF)

The Workbench Viewer

| Figure 8 shows how Workbench Viewer can display documents on a workstation | running Microsoft Windows 3.1, Windows NT, Windows 95, or OS/2 operating | systems. These documents can contain an index object file and a resource group.

Figure 8. Workbench Viewer

Chapter 1. Planning Your AFP Conversion and Indexing Facility (ACIF) Application 15

| Workbench Viewer uses Adobe Type 1 or true type outline fonts when displaying | documents. If the document references a font for which no Type 1 font is available | at the workstation, Workbench Viewer can substitute an outline font for the | requested font. Workbench Viewer matches the requested point size and attempts | to match the typeface as closely as possible. Font definition files are available with | Workbench Viewer to allow you to define which Type 1 fonts are to be substituted | for your AFP fonts. Because Workbench Viewer does not use AFP fonts, you do | not need to specify the restype=font ACIF parameter when preparing a document | to use with Workbench Viewer.

When using ACIF to index a file for viewing, specify indexobj=all. This setting provides Workbench Viewer with the most complete indexing information for accessing groups of pages in a file. Also, concatenate the index object file to the document for optimal performance of Workbench Viewer. (It is important that the document file comes last, at the end of the resulting concatenated file; otherwise, an error will occur.)

Workbench Viewer limits the size of the attribute names in indexing information to 64 bytes. When indexing data for viewing, make your attribute names unique within the first 64 bytes. (ACIF allows up to 250 bytes for attribute names.)

| Workbench Viewer supports a subset of MO:DCA-P data and may not display | everything that PSF can print. For example, OS/2 Workbench Viewer recognizes | but ignores bar code (BCOCA) objects, whereas PSF can print these objects.

AFP Toolbox for Multiple Operating Systems

AFP Toolbox(Program Number 5655-A25) assists application programmers in formatting printed output. Without requiring knowledge of the AFP data stream, AFP Toolbox provides access to sophisticated AFP functions through a callable C, C++, or COBOL interface. With AFP Toolbox you can:

 Combine variable data with electronic forms, electronic signatures, and images  Define variable length paragraphs  Draw fixed or variable depth and width boxes  Generate bar code objects  Draw horizontal and vertical fixed or variable length lines  Include indexing tags for use in efficient viewing, archival, and retrieval  Accent printed output with color and shading  Dynamically control fonts, including user-defined fonts  Precisely position and align text anywhere on a page using a wide variety of

fonts

 Create graphical data objects such as pie charts and bar charts

AFP Toolbox is available on OS/390, MVS, AIX, OS/2, and OS/400 platforms.

16 ACIF User’s Guide

Document Composition Facility (DCF)

Document Composition Facility (DCF) is a program used primarily to prepare and format documents for printing. It is another product that can be used with ACIF to index your data in the OS/390, MVS, VM, or VSE environments. Along with its many other features, DCF provides the ability to add both group-level and page-level indexing tags; whereas, with ACIF, you can add only group-level indexing tags. Only ACIF generates the index object file.

In DCF, the indexing function is known as “navigation.” DCF also provides a very different function already called “indexing.” In DCF terminology, you “navigate” through a document with the viewing application, and its indexing function is used to build an alphabetical listing of page references (a “back-of-the-book index”).

Support for navigation (indexing) is provided with DCF Version 4.0. APAR PN36437 is required to enable the support.

For further information about DCF, refer to

Script/VS Language Reference (SH35-0070)

the AIX environment.

Document Composition Facility

. Note that DCF is not applicable to

What are the Systems Considerations for ACIF?

You must consider the following when using ACIF:  System limitations  System prerequisites

System Limitations

If you are using ACIF to build applications for PSF for OS/390 and PSF/MVS, PSF/VM, or PSF/VSE, you need to take the following limitations into consideration:

PSF for OS/390 or PSF/MVS Limitations

To print an ACIF output file that contains indexing information, you must have either PSF/MVS 2.1.1 or PSF/MVS 2.1.0 with PTF number UY96049 installed or you must have PSF 3.1 for OS/390.

PSF/VM Limitations

To print an ACIF output file that contains indexing information, you must have PSF/VM 2.1.1 or PSF/VM 2.1.0 with PTF number UN37799 installed.

PSF/VSE Limitations

PSF/VSE does not support inclusion of fonts, page segments, and overlays in the print file. If you use ACIF to retrieve these resources, do not concatenate the ACIF resource file to the print file. If you want to print an ACIF output document using PSF/VSE, ensure that the resources are present on that platform.

To print an ACIF output file that contains indexing information, you must have either PSF/VSE 2.2.1 or PSF/VSE 2.2.0 with APAR DY42845 installed.

Chapter 1. Planning Your AFP Conversion and Indexing Facility (ACIF) Application 17

System Prerequisites

The following section describes system prerequisites necessary to use ACIF in the AIX, OS/390, MVS, VM, and VSE environments.

AIX Prerequisites

Either one of the following AIX software products is required to use ACIF:

|  PSF for AIX Version 2.1 (program number 5765-505) with, minimally, the | psf.acif option installed. This version of PSF for AIX requires IBM AIX for RISC | System/6000 Version 3.2.5 (program number 5756-030) or higher.

| Notes: | 1. Installation of

| command. | The formdef parameter is required for running ACIF. For AIX, see page 34.

| For OS/390, MVS, VM, or VSE, see page 96. Though you may use form | definitions from other sources, the psf.acif install option provides a form | definition named F1ACIF. (See the description for form definition F1A10110 | in | form definition F1ACIF.)

| The pagedef parameter is required for running ACIF if the input file | contains S/370 line data, mixed-mode data, or unformatted ASCII data. | Though you may use page definitions from other sources, several page | definitions are provided with PSF for AIX. The PSF-supplied page | definitions are installed into the /usr/lpp/psf/reslib directory with the | psf.acif option. These page definitions are listed and described in |

| 2. In order to print and to use the other resources that are available for ACIF, | you must

|  InfoPrint Manager for AIX 3.1.0. This version of InfoPrint Manager requires AIX | version 4.2.1 and higher.

IBM Print Services Facility for AIX: Print Submission

Print Services Facility for AIX: Print Submission

only

psf.acif will provide you with the ability to run the acif

also

install psf.base.

for details regarding

IBM

OS/390 or MVS Prerequisites

The following OS/390 or MVS software products are required to use ACIF:

|  MVS/ESA Version 5.2.0 or OS/390 |  PSF/MVS 2.2.0 or PSF/MVS 3.1.0 for OS/390.

VM Prerequisites

The following VM software products are required to use ACIF:

 VM/SP 5 or above  VM/SP HPO 5 or above  VM/XA 1.2.1 or above  VM/ESA 1.1.0 or above

PSF/VM 2.1.0 (with PTF# UN37799 for printing files that contain indexing tags) or PSF/VM 2.1.1

18 ACIF User’s Guide

VSE Prerequisites

The following VSE software products are required to use ACIF:

 VSE/SP 4.1.2 or above  VSE/ESA 1.1.0 or above

PSF/VSE 2.2.0 (with APAR DY42845 for printing files that contain indexing tags) or PSF/VSE 2.2.1 or above.

Note: You can use later versions or releases of these products. Each of the above

products may require additional software products. Refer to their respective publications for the current list of system requirements.

Chapter 1. Planning Your AFP Conversion and Indexing Facility (ACIF) Application 19

20 ACIF User’s Guide

Part 2. Using ACIF in the AIX Environment

 Copyright IBM Corp. 1993, 1999 21

22 ACIF User’s Guide

Chapter 2. Using ACIF Parameters in AIX

This section describes the acif command for AIX, including syntax rules, parameters, and values.

Purpose

Transforms S/370 line data and unformatted ASCII files into MO:DCA-P files for printing, viewing, archiving, and retrieving.

Syntax

| acif [ cc= |[cpgid= |[fieldn={ | fileformat= | imageout= |[ indexdd= | indxexit= |[insertimm= |[outexit= |[pagedef= |[ pseglib= | resobjdd= | *},{ | userlib=

column

value

] [ cctype=

value

] [ dcfpagenames=

value

record,column,length

value

] [fontlib=

value

] [ indexn=

filename

programname

value

programname

pdefname pathlist

filename

| *},{'

pathlist

] [ indexobj=

] [inpexit=

] [ mcf2ref=

] [ outputdd=

] [ parmdd=

] [ resexit=

] [ restype=

trigger value

]

] [ chars=

value

] [ fdeflib=

} | {

literal value

pathlist

] formdef=

{'attribute name

value

] [ indexstartby=

programname

value

] [ msgdd=

filename

programname

value

] [ trc=

' |

X'trigger value

fontnames

] [ comsetup=

pathlist

X'literal value

fdefname

' |

X'attribute name'},field definition

] [ inputdd=

filename

] [ ovlylib=

] [ pdeflib=

] [ reslib=

value

] [ triggern= {

'}] [ uniquebngs=

name

]

'}] [

[ groupname=

value

] [

filename

] [ objconlib=

pathlist

]

] [ prmode=

] [

record value

]

value

pathlist

] [[

] [

]

value

]

The syntax shown here is what the acif command expects to receive. For example, acif expects to receive literal single quote characters for the field, index, and trigger parameters. In order for ACIF to receive these single quote characters, you must “escape” the quote characters so that your shell will not parse them. The way you “escape” quote characters depends on the shell you are using. If you need guidance in passing the acif command parameter syntax through the shell, refer to the documentation for the shell you are using in

Commands Reference

The following acif command parameters specify resource names or resource directories, and are equivalent to the parameters specified to PSF for AIX when you print a job: objconlib, fontlib, fdeflib, pseglib, reslib, and ovlylib. For these parameters, you should specify the same value with the acif command as you specify to PSF for AIX with an AIX print command. In this way, the search paths and resources used at transform time are identical to the search paths and resources used at print time.

Note: You may need to consult your system support group for information on

resource directories and other printing defaults contained in the PSF for AIX printer profiles used in your installation.

In addition to the notational conventions shown in “ Understanding Syntax Notation” on page xvi, the acif command follows these additional rules. These rules apply to parameters you type at the command line. See also the parmdd parameter on page 42 for the syntax of parameters contained in the acif parameter file.

AIX RISC System/6000

 Copyright IBM Corp. 1993, 1999 23

 When the acif command processes any unrecognized or unsupported

parameter, acif issues a message, ignores the parameter, and continues processing any remaining parameters. The acif command then stops processing.

 Though the parameters themselves are not case-sensitive, associated values,

such as file names, attribute names, and directory names For example,

formdef=F1MINE

not

the same as

formdef=f1mine

Be sure to specify these values in the case in which they exist in the file system (for external resources) or in the print file (for inline resources).

 If the same parameter is specified more than one time, the acif command uses

the last value specified. For example, if you specify the following:

pagedef=P1MINE pagedef=P1YOURS

are

case-sensitive.

Description

the acif command uses page definition P1YOURS only.

The acif command transforms S/370 line data, mixed-mode data, and unformatted ASCII files into the Mixed Object: Document Content Architecture for Presentation (MO:DCA-P) data stream. With this data stream, you can do the following:

 Print the file on a printer defined to PSF for AIX, or to other PSF products  View the file using a viewer product such as AFP Workbench  Archive and retrieve the file using your own archival management system

The acif command provides indexing and resource retrieval capabilities, which enable you to perform the viewing, archiving, and retrieving tasks with the appropriate system and software.

Three types of files can be generated, depending on what output options you specify:

 An AFP document file  An AFP resource file  An index object file

When you use the acif command to convert S/370 line data or unformatted ASCII data, you must specify a page definition ( pagedef parameter). If the page definition names some fonts, the acif command uses those fonts. If the page definition does not name any fonts (like the sample page definitions supplied with PSF for AIX), and if you want the file to print with more than one font, then the input file must contain table reference characters, and you must:

 Specify trc=yes.

 Use chars to indicate the fonts to be associated with each Table Reference

Character (TRC). with TRC 1, and so on.

fontname1

is associated with TRC 0,

fontname2

is associated

24 ACIF User’s Guide

Note: If the page definition does not specify fonts, and you have not specified any

TRCs, your job will print, although the output may not be formatted correctly.

If the page definition does not name any fonts, and you want the whole file to print with only one font, then you must:

 Specify trc=no.

 Use chars to indicate the single font in which the file should be printed.

The acif command searches for resources in the following order:

1. Paths specified by the userlib parameter

2. Paths specified by the fdeflib, fontlib, pdeflib, pseglib, objconlib, and ovlylib parameters for specific types of resources

3. Paths specified by the reslib parameter

4. Paths specified by the PSFPATH environment variable

5. The directory /usr/lpp/psf/reslib

6. The directory /usr/lpp/afpfonts

| For InfoPrint Manager for the AIX environment, the fonts are included in the | AFP font collection; refer to |

Collection

for more information.

IBM AFP Fonts: Font Summary for AFP Font

7. The directory /usr/lpp/psf/fontlib

When the acif command finds more than one resource with the same name in the same directory, it selects the resource to be used depending on the file extension. Figure 9 shows the order in which resources with the same name but different file extensions are used by acif.

Note: If a file name includes a period (.), the file extension is that part of the file

name that follows the period. For example, the file extension of the file name ARTWORK.PSEG382 is PSEG382.

Chapter 2. Using ACIF Parameters in AIX 25

Figure 9. File Extensions for Resources

Type of Resource File Extensions Searched (see note)

Form definitions 1. No file extension

2. FDEF3820

3. FDEF38PP

4. FDE

Page definitions 1. No file extension

2. PDEF3820

3. PDEF38PP

4. PDE

Fonts, 240-pel resolution 1. No file extension

2. 240

3. FONT3820

4. FONT38PP

Fonts, 300-pel resolution 1. No file extension

2. 300

2. FONT300

Page segments 1. No file extension

2. PSEG3820

3. PSEG38PP

4. PSG

Overlays 1. No file extension

2. OVLY3820

3. OVLY38PP

4. OVL

Coded fonts 1. No file extension

2. FONT3820

3. FONT38PP

4. CFT

Setup data 1. No file extension

2. SETUP

3. SET

4. COMSETUP

Note: All file extensions must be in uppercase format.

You can use ACIF to prepare S/370 line data or unformatted ASCII files. At print submission time, to

automatically

invoke the acif command for the purpose of preparing S/370 line data or unformatted ASCII files for printing with PSF for AIX, use the -odatatype=line flag and keyword-value pair with one of the AIX print commands (enq, lp, or qprt), or use the psfin command to specify a job script with a setting of -JsFiletype=line.

Note: The line2afp command of PSF for AIX is a subset of the acif command

and uses the acif command parameters for conversion to produce output for printing. As does ACIF, the line2afp command uses a page definition to define how the data is to be formatted on the printed page. If you use the line2afp command, you will be able to transform and print files, but you will not be able to take advantage of the indexing and resource retrieval

26 ACIF User’s Guide

The following parameters are used for just the either the acif command or the line2afp command: cc, cctype, chars, fdeflib,

fileformat, fontlib, formdef, imageout, inpexit, inputdd, insertimm, mcf2ref, msgdd, outexit, outputdd, ovlylib, pagedef, parmdd, pdeflib, prmode, pseglib, resexit, reslib, trc, and userlib.

The following parameters are used for

comsetup, fdeflib, fontlib, formdef, objconlib, ovlylib, pseglib, resexit, resobjdd, and restype.

The acif command uses the following parameters for its fieldn, groupname, indexn, indexdd, indexobj, indexstartby, indxexit, and triggern.

Flags and Values

cc={yes | no}

functions for viewing. The line2afp command is described in

Services Facility for AIX: Print Submission

resource retrieval

conversion

function of ACIF, with

with the acif command:

indexing

Specifies whether the input file has carriage-control characters. Values are:

yes The file contains carriage-control characters. no The file does not contain carriage-control characters.

IBM Print

functions: cpgid,

Carriage-control characters, if present, are located in the first byte (column) of each line in a document. They are used to control how the line will be formatted (single space, double space, triple space, and so forth). In addition, other carriage-controls can be used to position the line anywhere on the page. If there are no carriage-controls, single spacing is assumed.

cctype={z | a | m}

Specifies the type of carriage-control characters in the input file. The acif command supports ANSI carriage-control characters in either ASCII or EBCDIC encoding, as well as machine carriage-control characters. The acif command does not allow a mixture of ANSI and machine carriage-control characters within a file. Values are:

z The file contains ANSI carriage-control characters that are

a The file contains ANSI carriage-control characters that are

encoded in ASCII. The carriage-control characters are the ASCII hexadecimal values

that directly relate to ANSI carriage-controls, which cause the action of the carriage-control character to occur printed. For example, if the carriage-control character is zero (X'30'), which represents double spacing, double spacing will occur

before

the line is printed.

encoded in EBCDIC.

before

the line is

The use of ANSI carriage-control characters cause the action of the carriage-control character to occur printed. For example, if the carriage-control character is a zero

Chapter 2. Using ACIF Parameters in AIX 27

before

the line of data is

(X'F0'), which represents double spacing, the double spacing will occur

before

the line is printed.

m The file contains machine code carriage-control characters that

are encoded in hexadecimal format. The use of machine code carriage-control characters cause the

action of the carriage-control character to occur data is printed. For example, if the carriage-control character is a X'11', which represents double spacing, the line will be printed and the double spacing will occur addition, machine code carriage-control has a set of carriage-control characters that perform the action, but do not print the associated line. For example, if the carriage-control character is a X'13', which also represents double spacing, the print position will be moved down two lines but the line that contains the X'13' carriage-control character will not be printed. The next line in the data will be printed at the current print position and the action for the associated carriage-control character will be performed

after

the line is printed. In

the line is printed.

after

the line of

chars=

If you specify cc=yes but you do not specify cctype, the acif command assumes that the file contains ANSI carriage-control characters encoded in ASCII.

If you are not sure which type of carriage-control characters are in your input file, consult your system support group.

fontname1, fontname2, fontname3, fontname4

Specifies the file name of from one to four coded fonts to be used in processing the print file. A coded font specifies a character set and code page pair. The value is:

fontname

If you use the ASCII fonts that are supplied with PSF for AIX, use the four-character names as shown in Chapter 5, “IBM AFP Fonts for ASCII Data” on page 77. If you use your own coded font that has a file name with more than six characters (including the Xn prefix), then do one of the following:

 Rename the font file to a shorter name. For example,

– mv X4232 X422

 Copy the font file to a file that has a shorter name. For example,

– cp X4232 X422

 Link the original font file to a shorter name. For example,

– ln -s X4232 X422

The name of the desired coded font. The font name is limited to four alphanumeric or national characters, and should not include the two-character prefix of the coded-font name (X0 through XG). The font name is case-sensitive.

When you use the acif command to convert S/370 line-mode data or unformatted ASCII data, you must specify a page definition ( pagedef parameter). If the page definition names some fonts, the acif command uses those fonts, and ignores the chars parameter. If the page definition does not name any fonts (like the sample page definitions supplied with PSF for AIX), and if you want the file to print

28 ACIF User’s Guide

with more than one font, then the input file must contain table reference characters, and you must:

 Specify trc=yes.

 Use chars to indicate the fonts to be associated with each Table

Reference Character (TRC).

fontname2

is associated with TRC 1, and so on.

If the page definition does not name any fonts, and you want the whole file to print with only one font, then you must:

 Specify trc=no.

 Use chars to indicate the single font in which the file should be

printed.

Consider the following when specifying fonts with the chars parameter:

 If the input file is unformatted ASCII, you can do one of the

following:

– Specify a font that has the appropriate ASCII code points. To

specify a font search path, either use the fontlib parameter to specify it explicitly, or set the PSFPATH environment variable to search the appropriate directories. See Chapter 5, “IBM AFP Fonts for ASCII Data” on page 77 for a list of suggested ASCII fonts.

fontname1

is associated with TRC 0,

– Use the apka2e or asciinpe input record exit programs to

convert the ASCII code points in the input file into EBCDIC, and use EBCDIC fonts. To do this, use the inpexit parameter, specifying:

-inpexit=/usr/lpp/psf/bin/apka2e or

-inpexit=/usr/lpp/psf/bin/asciinpe See the inpexit parameter on page 39 for a description of

apka2e and asciinpe functions.

 You can specify fonts with the chars parameter only if you want

the entire file printed in a single printing direction. The acif command uses the fonts that have 0° character rotation for the specified direction. When a file requires fonts with more than one print direction or character rotation, you must specify the fonts in the page definition.

 You can specify from one to four fonts with the chars parameter.

If you specify more than one font with the chars parameter, then the input file must contain table reference characters, and you must specify trc=yes.

 If you use chars to specify fonts, but you also use the pagedef

parameter to specify a page definition that names fonts, the chars parameter is ignored. Therefore, if your page definition names fonts, you should not use chars.

Chapter 2. Using ACIF Parameters in AIX 29

 If you do not specify a chars parameter, and if no fonts are

contained in the page definition you specified, the acif command uses the default font that is set in the printer’s hardware.

comsetup=

name

Specifies the name of a COM setup file. A COM setup file is an AFP resource that contains instructions required when printing on a microfilm device. The value is:

name

The COM setup file you use may be located:

If the COM setup file is in an AIX directory, use the userlib or objconlib parameter to specify the path to the file. For example:

 comsetup=mysetup userlib=/usr/afp/resources or

Any valid COM setup file name. The eight alphanumeric or national characters, including the two-character prefix, if there is one. The case-sensitive.

Note: If the file name of the COM setup file includes a file

extension, do not use the file extension when specifying the setup file. For example, to use a setup file named mysetup.SET, specify setup=mysetup.

 In an AIX directory  Inline in the file (that is, within the file itself)

name

can be one to

name

cpgid={850 |

 comsetup=mysetup objconlib=/usr/lib/setups If the COM setup file is an inline resource, you must do the following:

 Specify comsetup=

COM setup file; or specify comsetup=dummy. If you specify comsetup=dummy but the file does not include an

inline COM setup file, the acif command looks for the COM setup file named dummy.

If the name specified for the comsetup parameter does not match the name of an inline COM setup file, the acif command looks for the COM setup file in the comsetup search path.

An input file can contain multiple COM setup files, but only one COM setup file can be used for printing. If a file contains more than one COM setup file, and you specify comsetup= inline COM setup file named inline COM setup file, and you specify comsetup=dummy, ACIF uses the first inline COM setup file in the input file.

code page identifier

Specifies the code page used when the index values and attribute names were specified on the indexn and fieldn parameters. Values are:

}

name

, where

name

is the name of the inline

name

, ACIF uses the first

. If a file contains more than one

850 IBM code page 850

30 ACIF User’s Guide

code page identifier

Any valid code page, which is a three-character decimal value (for example, 395) that defines an IBM-registered code page

ACIF uses this code page identifier value when it creates a Coded Graphic Character Set Global Identifier Triplet X'01' in the Begin Document (BDT) structured field for the output file. For more information on this triplet, refer to

Architecture Reference

The code page identifier value is used by programs, such as Workbench Viewer, that must display indexing information. These programs use this value with code page translation tables to represent the index attribute and value data. If this parameter is not specified, ACIF uses code page 850 as the default. For code-page numbers less than 100, add leading zeros (for example, 037). If a non-decimal value is specified, ACIF reports an error condition and terminates processing.

dcfpagenames={yes | no}

Specifies whether ACIF generates page names using an 8-byte counter or uses structured field tokens found in the input data stream. If the input data contains BPGs with FQNs, ACIF does not generate page names.

Mixed Object Document Content

fdeflib=

yes ACIF uses structured field tokens in the input data stream to

generate page names.

no The default, ACIF generates page names using an 8-byte

counter.

pathlist

Specifies the directories in which form definitions are stored. The value is:

pathlist

Any valid search path. You must use a colon (:) to separate multiple paths. The acif command searches the paths in the order in which they are specified.

The acif command searches for the form definition in the following order:

1. The paths you specified with userlib, if any

2. The paths you specified with fdeflib, if any

3. The paths you specified with reslib, if any

4. The paths specified by the PSFPATH environment variable

5. The directory /usr/lpp/psf/reslib

For information on how PSF for AIX selects resources, refer to

Print Services Facility for AIX: Print Administration

IBM

fieldn={

record,column,length

} | {'

literal value

' |

X'literal value

Specifies the data fields to be used to construct the indexing information. Either these data fields can be specified as literal values (constants), or ACIF can retrieve the data from the input records of the file. A maximum of 16 fields can be defined (field1 through field16). The definition of a field includes:

Chapter 2. Using ACIF Parameters in AIX 31

record

column

length

Specifies the relative record number from the indexing anchor record. When ACIF is indexing the file, it uses the information specified in the triggern parameters to determine a page group boundary. When all of the specified triggern values are true, ACIF defines the indexing anchor record as the record where trigger1 is located. trigger1 becomes the reference point from which all indexing information is located. The supported range of values for

Specifies the byte offset from the beginning of the record. A value of 1 refers to the first byte in the record. For files containing carriage-control characters, column 1 refers to the carriage-control. For those applications that use a specific carriage-control character to define page boundaries (for example, skip to channel 1), consider defining the value of the carriage-control character as one of the triggern parameters. The supported range of values for exceeds the physical length of the record, ACIF reports an error condition and terminates processing.

Specifies the number of contiguous bytes (characters) starting at range of values for

column

record

are ±0 to 255.

are 1 to 32756. If the specified value

that compose this field. The supported

length

are 1 to 250.

The field can extend outside the record length, as long as the column where it begins lies within the record length. In this case, ACIF adds padding blanks to fill out the record. If the field begins outside the maximum length of the record, ACIF reports an error condition and terminates processing.

literal value

For example, to specify five fields in your print job, you would enter:  field1=,2,2

 field2=5,5,1  field3=−15,3,5  field4='444663821'  field5=X'1'

X'literal value

Specifies the literal (constant) value of the field parameter. If the input data file contains unformatted ASCII data, this value can be specified either as character data or hexadecimal data. If the input data file is

anything other than

be specified as hexadecimal data (otherwise, the comparisons between the input file and what is coded in the fieldn parameter will not yield a match). The literal value can be 1 to 250 bytes in length. ACIF does not perform any validity checking on the actual content of the supplied data.

unformatted ASCII, the value must

In the preceding example, the fields have the following values:

32 ACIF User’s Guide

 The first field in the example is located in the indexing anchor

record (trigger1). The field is 20 bytes in length starting at the second byte of the record.

 The second field is located five records down from the indexing

anchor record. The field is 10 bytes in length starting at the fifth byte of the record.

 The third field is located 15 records before the indexing anchor

record. It is 5 bytes in length starting at byte 30.

 The fourth and fifth fields are literal (constant) values. The fourth

field is specified in ASCII, while the fifth field is specified as hexadecimal (for example, EBCDIC) data.

For more information about using data values or literal values for indexing, refer to “Indexing with Data Values” on page 11, and “Indexing with Literal Values” on page 12.

ACIF allows fields to be defined but never referenced as part of an index. Because ACIF requires either a field or trigger to appear on the first page of a group (for example, a bank statement), you can satisfy this requirement by defining a “dummy” field. This dummy field allows ACIF to determine the beginning page of a group, but it is not used as part of an index.

fileformat={record | record,n | stream | stream,

Specifies the format of the input file. If you do not specify fileformat, the acif command uses stream as the default.

The fileformat parameter does not apply to input files that are resources. Resource files are in MO:DCA-P or AFP data stream format, and the acif command automatically determines that the file is a resource. Values are:

record The input file is formatted in S/370 record format, where

the first two bytes of each line, called the record descriptor word (RDW), specify the length of the line. Files with record format typically are MVS or VM files that have a variable record format, and that are NFS-mounted to AIX.

record,

The input file is formatted in such a way that each record (including AFP data stream and MO:DCA-P records) is a fixed length, n bytes long. The value of n is a number from 1 to 32767, and specifies the fixed length of the entire record, excluding the RDW. The encapsulated size of the AFP structured field must be less than the size of

. Files with record,n format typically come with fixed-length file attributes from a S/370 host system like MVS or VM.

(newline=

X'nn')}

stream The input file has no length information; it is a stream of

data separated by a newline character. The AFP portion of the input file has its length information encapsulated in the structured field. Files with stream format typically come from a workstation operating system like AIX, OS/2, or DOS.

Chapter 2. Using ACIF Parameters in AIX 33

The acif command examines the first six bytes of the first line data record of the input file, to determine whether the input file is ASCII or EBCDIC. If ACIF determines that the input file is ASCII, ACIF looks for the ASCII newline character (X'0A') to delimit the end of a record. If ACIF determines that the input file is EBCDIC, ACIF looks for the EBCDIC newline character (X'25') to delimit the end of a record. If the input record is MO:DCA-P, no newline character is required. The acif command does not include newline characters in the MO:DCA-P data stream that ACIF produces.

fontlib=

stream,

(newline=

X'nn')

newline is an optional subparameter of fileformat that is

used only with the stream parameter. You use newline to specify a hexadecimal value for the newline character in the input data file.

You can use newline when ACIF’s algorithm cannot determine the correct newline character (if blanks are at the beginning of the file, for instance). Or you can use newline if you want to specify a newline character that is not the standard default. For example, you could use newline as follows:

fileformat=stream,(newline=X'D')

If newline is not specified, ACIF uses the algorithm specified under fileformat=stream.

pathlist

Specifies the directories in which fonts are stored. The value is:

pathlist

The acif command searches for the fonts in the following order:

Any valid search path. You must use a colon (:) to separate multiple paths. The acif command searches the paths in the order in which they are specified.

1. The paths you specified with userlib, if any

2. The paths you specified with fontlib, if any

3. The paths you specified with reslib, if any

4. The paths specified by the PSFPATH environment variable

5. The directory /usr/lpp/psf/reslib

6. The directory /usr/lpp/afpfonts

7. The directory /usr/lpp/psf/fontlib

formdef=

For information on how PSF for AIX selects resources, refer to

Print Services Facility for AIX: Print Administration

fdefname

Specifies the file name of the form definition. A form definition defines how a page of data is placed on a form, the number of copies of a page, any modifications to that group of copies, the paper source, and duplexing. The form definition is actually used at print time, not at transform time. The value is:

IBM

34 ACIF User’s Guide

fdefname

Any valid form definition file name. The

fdefname

can be one to eight alphanumeric or national characters, including the two-character prefix, if there is one. The

fdefname

is case-sensitive.

Note: If the file name of the form definition includes a file

extension, do not use the file extension when specifying the form definition. For example, to use a form definition named memo.Fdef38PP, specify formdef=memo.

The acif command requires a form definition in order to process the input file (even though the form definition actually gets used at print time). If you do not specify formdef=, or if you specify formdef= without a form definition file name, the acif command will not work.

The form definition you use may be located:

 In an AIX directory  Inline in the file (that is, within the file itself)

If the form definition file is in an AIX directory, use the userlib parameter or fdeflib parameter to specify the path to the file. For example:

 formdef=memo userlib=/usr/afp/resources or  formdef=memo fdeflib=/usr/lib/formdefns If the form definition is an inline resource, you must do the following:

 Specify cc=yes to indicate that the file contains carriage-control

characters.

 Specify formdef=

fdefname

, where

fdefname

is the name of the

inline form definition; or specify formdef=dummy. If you specify formdef=dummy but the file does not include an

inline form definition, the acif command looks for the form definition named dummy.

If the name specified for the formdef parameter does not match the name of an inline form definition, the acif command looks for the form definition in the formdef search path.

An input file can contain multiple form definitions, but only one form definition can be used for printing. If a file contains more than one inline form definition, and you specify formdef= the first inline form definition named

fdefname

, ACIF uses

. If a file contains more than one inline form definition, and you specify formdef=dummy, ACIF uses the first inline form definition in the input file.

groupname={index1 | indexn}

Specifies which of the eight possible index values should be used as the group name for each index group. Using a unique index value for the group name is recommended. The intent is to have a unique group name for every group ACIF produces in the output file. The value includes the field definitions from the index parameter but not

Chapter 2. Using ACIF Parameters in AIX 35

the attribute name. ACIF uses this parameter only when the file is indexed. Workbench Viewer displays this value along with the attribute name and index value. You can use the group name to select a group of pages to be viewed. Values are:

index1 ACIF uses the value of index1. indexnACIF uses the value of the specified index (index1, index2,

imageout={asis | ioca}

Specifies the format of the image data produced by the acif command in the output document. Values are:

asis The acif command produces all image data in the same

format that it was in the input file.

ioca The acif command produces all image data in the Image

Object Content Architecture uncompressed format.

index

n={'attribute name

Specifies the content of the indexing tags for the entire file. A maximum of eight indexes can be defined (index1, index2,... index8), and each index can be made up of one or more field definitions.

index3,...index8).

' |

X'attribute name

' },fieldn[,fieldn...]

If literal values are specified for every index, ACIF treats the entire file as one page group and uses this information to index the document. ACIF reports an error condition and terminates processing if literal values are specified for all indexn parameters and if any trigger parameters are also specified.

For field parameters that specify data values within the file, ACIF determines the actual location of the indexing information based on the indexing anchor record, set by the trigger parameters.

A valid set of index parameters comprises either of the following:

 field definitions containing only constant data (literal values)  field definitions containing both constant data and application data

(data fields in the print file)

You can also specify the same field parameters in more than one

index parameter. Note: If one or more triggern parameters are specified (that is, ACIF

will index the file), at least one indexn parameter must be specified, and that index must comprise at least one field parameter value that is not a literal. ACIF reports an error condition and terminates processing if this rule is not satisfied.

Valid components of the indexn parameter are:

attribute name

' |

X'attribute name

Specifies a user-defined attribute name to be associated with the actual index value. For example, assume index1 is a person’s bank account number. The string 'Account Number' would be a meaningful attribute name. The value of index1 would be the account number (for example, 1234567). Think of the attribute name as a label for the actual index value. This value

36 ACIF User’s Guide

can be specified either as character data or hexadecimal data. (If the input file is the value

must

be specified as hexadecimal data.) The attribute name is a string from 1 to 250 bytes in length. ACIF does not perform any validity checking on the contents of the attribute name.

fieldn[,fieldn...]

Specifies one or more fieldn parameters that compose the index value. A maximum of 16 fieldn parameters can be specified. If more than one fieldn parameter is specified, ACIF concatenates them into one physical string of data. No delimiters are used between the concatenated fields. Because an index value has a maximum length of 250 bytes, the total of all specified

fieldn parameters for a single index cannot exceed this

length. ACIF reports an error condition and terminates processing if this occurs.

For example, if you want to specify the following fields and indexes, you enter:

anything other than

ASCII, then

 field1='1234567'  field2=,1,2  field3=,25,2  index1='Patent Number',field1  index2='Employee Name',field2,field3

The example above specifies that the first index tag is made up of the literal character string '1234567', while the other two index tags are made up of fields within the file records.

 field1='123456'  field2='444556677'  index1='Account Number',field1

 index2='Social Security Number',field2

This example specifies both index tags as literal values. The entire file will be indexed using these two values. The resulting index object file contains only one record in this case.

Note: The preceding examples are based on ASCII input data. If the

input data were

not

ASCII, then in ACIF for AIX the literal values used in these examples would be expressed in hexadecimal strings. For an example using hexadecimal strings, see “Specifying ACIF Processing Parameters for EBCDIC Input Data” on page 58.

indexdd={INDEX |

filename

}

Specifies the name or the full path name for the index object file. When ACIF is indexing the file, it writes indexing information in the file with this name. If you specify the file name without a path, ACIF puts the index object file into your current directory. Values are:

INDEX ACIF uses INDEX as the name for the index object file.

Chapter 2. Using ACIF Parameters in AIX 37

filename

indexobj={group | all | none}

Specifies the type of information ACIF puts in the index object file. Values are:

group Places only group-level entries into the index object file,

all Places both page-level and group-level entries into the index

none Suppresses the collection of all index-level information.

indexstartby={1 |

Specifies the output page number by which ACIF must find an indexing field, if ACIF is indexing the file. Values are:

1 ACIF must find an index on the first page.

A character string containing only those alphanumeric characters supported in AIX file names.

which saves space.

object file. Select all if you are indexing a file for use with the Workbench Viewer.

Choose none if you do not require an external index file. Choosing none will also reduce ACIF storage requirements.

}

Specifies the output page number by which ACIF must find the index criteria specified.

indxexit=

inpexit=

This parameter is helpful if, for example, your file contains header pages. If your file contains two header pages, you can specify a page number one greater than the number of header pages (indexstartby=3).

If ACIF does not find an indexing field before the page number specified in the indexstartby parameter, it issues a message and stops processing.

programname

Specifies the name or the full path name of the index record exit program. This is the program ACIF calls for every record (structured field) it writes in the index object file ( indexdd). If you specify the file name without a path, ACIF searches for the exit program in the paths specified by the PATH environment variable. If this parameter is not specified, ACIF will not use an index record exit program. The value is:

programname

Any valid index record exit program name. The exit program name is case-sensitive.

programname

Specifies the name or the full path name of the input record exit program. The acif command calls this program for every record (every line) it reads from the input file ( inputdd). If you specify the file name without a path, the acif command searches for the exit program in the paths specified by the PATH environment variable. If you do not specify this parameter, the acif command will not use an input record exit program. The value is:

38 ACIF User’s Guide

programname

Any valid input record exit program name. The exit program name is case-sensitive.

If the input file is unformatted ASCII, but the fonts you are using contain EBCDIC, not ASCII, code points (for example, you specify chars=GT15), you can specify one of the following exit programs supplied with PSF for AIX:

/usr/lpp/psf/bin/apka2e

Converts ASCII stream data to EBCDIC stream data.

/usr/lpp/psf/bin/asciinp

Converts unformatted ASCII data that contains carriage returns and form feeds into a record format that contains an American National Standards Institute (ANSI) carriage control character. This exit encodes the ANSI carriage control character in byte 0 of every record.

/usr/lpp/psf/bin/asciinpe

Converts unformatted ASCII data into a record format in the same way as asciinp, and then converts the ASCII stream data to EBCDIC stream data.

If your input file uses fonts that have ASCII code points (for example, you specify chars=H292, or any of the fonts listed in Chapter 5, “IBM AFP Fonts for ASCII Data” on page 77) you should

not

use the apka2e or asciinpe exit programs. However, if your unformatted ASCII file contains carriage returns and form feeds, you may want to specify the following exit program supplied with PSF for AIX:

inputdd=

filename

Specifies the full path name of the input file that the acif command will process. If you do not specify inputdd, the acif command uses standard input.

| insertimm={yes | no} | Specifies whether ACIF is to insert an IMM structured field before the | first BPG structured field of every named page group. The default is | NO. If INSERTIMM=YES, an IMM is inserted before the first BPG | structured field in the named page group if no IMM was encountered | within the named page group.

| mcf2ref={cpcs | cf} | Specifies the way ACIF builds the Map Coded Font 2 (MCF2) | structured field in the output file and the resobj file. The values are:

| cpcs ACIF uses the names of the code page and character set | to build the MCF2 structured field. This is the default, | which means that ACIF must open and read the contents | of all coded fonts specified in MCFs in the input file or | input resources.

| cf ACIF uses the name of the coded font to build the MCF2 | structured field. You will improve ACIF performance by | specifying cf, because ACIF does not have to read the | coded fonts from the font library.

Chapter 2. Using ACIF Parameters in AIX 39

msgdd=

objconlib=

filename

Specifies the name or the full path name of the file where the acif command writes error messages. If you specify the file name without a path, the acif command puts the error file into your current directory. If you do not specify msgdd, the acif command uses standard error for its message output.

pathlist

Specifies the directories in which setup files are stored. A COM setup file consists of a MO:DCA structure called an object container. For further information about the COM setup file see page 30.

The value is:

pathlist

The acif command searches for a setup file in the following order:

1. The paths you specified with userlib, if any

2. The paths you specified with objconlib, if any

3. The paths specified in reslib, if any

4. The paths specified by the PSFPATH environment variable

5. The directory /usr/lpp/psf/reslib

Any valid search path. You must use a colon (:) to separate multiple paths. The acif command searches the paths in the order in which they are specified.

outexit=

outputdd=

ovlylib=

programname

pathlist

Specifies the name or the full path name of the output record exit program. The acif command calls this program for every output record (every line) it writes to the output document file ( outputdd). If you specify the file name without a path, the acif command searches for the file name in the paths specified by the PATH environment variable. If you do not specify this parameter, the acif command will not use an output record exit program. The value is:

programname

Any valid output record exit program name. The exit program name is case-sensitive.

filename

Specifies the name or the full path name of the output document file. If you specify the file name without a path, the acif command puts the output file into your current directory. If you do not specify outputdd, the acif command writes the output to standard output.

Specifies the directories in which overlays are stored. The value is:

pathlist

Any valid search path. You must use a colon (:) to separate multiple paths. The acif command searches the paths in the order in which they are specified.

The acif command searches for an overlay in the following order:

1. The paths you specified with userlib, if any

2. The paths you specified with ovlylib, if any

3. The paths specified in reslib, if any

4. The paths specified by the PSFPATH environment variable

5. The directory /usr/lpp/psf/reslib

40 ACIF User’s Guide

You should specify the same value for the ovlylib parameter to the acif command as specified to PSF for AIX. In this way, the search

paths and resources used at transform time are identical to the search paths and resources used at print time. For information on how PSF for AIX selects resources, refer to

Print Administration

IBM Print Services Facility for AIX:

pagedef=

pdefname

Specifies the file name of the page definition. A page definition defines the page format that the acif command uses to compose the input file into pages. The page definition is actually used at transform time, not at print time. The value is:

pdefname

Any valid page definition file name. The

pdefname

one to eight alphanumeric or national characters, including the two-character prefix, if there is one. The

pdefname

is case-sensitive.

Note: If the file name of the page definition includes a

file extension, do not use the file extension when specifying the page definition. For example, to use a page definition named memo.Pdef38PP, specify pagedef=memo.

The acif command does not require a page definition when indexing an AFP data stream file. However, ACIF does require a page definition to transform an input file that contains S/370 line data, mixed-mode data, or unformatted ASCII data into MO:DCA-P. If you are transforming such an input file, and you do not specify pagedef=, or if you specify pagedef= without a page definition file name, the acif command will not work.

can be

The page definition you use may be located:

 In an AIX directory  Inline in the file (that is, within the file itself)

If the page definition file is in an AIX directory, use the userlib parameter or pdeflib parameter to specify the path to the file. For example:

 pagedef=memo userlib=/usr/afp/resources or  pagedef=memo pdeflib=/usr/lib/pagedefns If the page definition is an inline resource, you must do the following:

 Specify cc=yes to indicate that the file contains carriage-control

characters.

 Specify pagedef=

pdefname

, where

pdefname

is the name of the

inline page definition; or specify pagedef=dummy. If you specify pagedef=dummy but the file does not include an

inline page definition, the acif command looks for the page definition named dummy.

Chapter 2. Using ACIF Parameters in AIX 41

If you use pagedef to specify an inline page definition that is different than the actual page definition used inline, the acif command looks for the page definition in the page definition search path instead of the inline page definition.

An input file can contain multiple page definitions, but only one page definition can be used by the acif command. If a file contains more than one inline page definition, and you specify pagedef= ACIF uses the first inline page definition named contains more than one inline page definition, and you specify pagedef=dummy, the acif command uses the first inline page definition in the input file.

pdefname

. If a file

parmdd=

filename

Specifies the name or the full path name of a file that contains the acif parameters and their values. If you specify the file name without a path, the acif command searches for the file name in your current directory.

You may find it convenient to put the acif parameters and values into a file, so that you do not have to type all of them on the command line whenever you use ACIF. Values are:

filename

Notes:

1. The beginning delimiter for comments is “/*.” For example:

Comments can appear anywhere, but the acif command ignores all information in the line following the “/*” character string. Also, although the ending delimiter (“*/”) is shown in some examples, it is not a required entry for ACIF.

2. Each parameter must be on a separate line. For example:

The name of the file containing acif command parameters and values.

formdef=F1TEMP / Temporary formdef

chars=GT1 cctype=a / This is not allowed.

pdeflib=

pathlist

Specifies the directories in which page definitions are stored. The value is:

pathlist

The acif command searches for a page definition in the following order:

1. The paths you specified with userlib, if any

2. The paths you specified with pdeflib, if any

3. The paths specified in reslib, if any

4. The paths specified by the PSFPATH environment variable

5. The directory /usr/lpp/psf/reslib

Any valid search path. You must use a colon (:) to separate multiple paths. The acif command searches the paths in the order in which they are specified.

42 ACIF User’s Guide

| prmode={SOSI1 | SOSI2 | SOSI3 |

aaaaaaaa

}

| Specifies the type of data in the input file and whether the acif | command must perform optional processing of that data. Values are:

| SOSI1 Specifies that each shift-out, shift-in code be converted to | a blank and a Set Coded Font Local text control. The | SOSI1 data conversion is the same as the SOSI1 data | conversion performed by PSF for OS/390, PSF/MVS, | PSF/VM, and PSF/VSE.

| SOSI2 Specifies that each shift-out, shift-in code be converted to | a Set Coded Font Local text control. The SOSI2 data | conversion is the same as the SOSI2 data conversion | performed by PSF for OS/390, PSF/MVS, PSF/VM, and | PSF/VSE.

| SOSI3 Specifies that each shift-out character be converted to a | Set Coded Font Local text control. Each shift-in is | converted to a Set Coded Font Local Text control and two | blanks. The SOSI3 data conversion is the same as the | SOSI3 data conversion performed by PSF for OS/390 or | PSF/MVS.

aaaaaaaa

Any eight-byte alphanumeric string. This value is supplied

| to all of the ACIF user exits. | For either SOSI process to work correctly, the first font specified in the

| chars parameter (or in a font list in a page definition) must be a | single-byte font, and the second font must be a double-byte font.

pseglib=

pathlist

| Specifies the directories in which page segments, BCOCA, GOCA, | and IOCA objects are stored. The value is:

pathlist

Any valid search path. You must use a colon (:) to | separate multiple paths. The acif command searches the | paths in the order in which they are specified.

| The acif command searches for page segments in the following order: | 1. The paths you specified with userlib, if any

| 2. The paths you specified with pseglib, if any | 3. The paths specified in reslib, if any | 4. The paths specified by the PSFPATH environment variable | 5. The directory /usr/lpp/psf/reslib

| You should specify the same value for the pseglib parameter to the | acif command as specified to PSF for AIX. In this way, the search | paths and resources used at transform time are identical to the search | paths and resources used at print time. For information on how PSF | for AIX selects resources, refer to |

Print Submission

IBM Print Services Facility for AIX:

resexit=

programname

Specifies the name or the full path name of the resource exit program. This is the program the acif command calls each time it attempts to retrieve a requested resource from a directory. If you specify the file name without a path, the acif command searches for the file name in

Chapter 2. Using ACIF Parameters in AIX 43

the paths specified by the PATH environment variable. If you do not specify this parameter, the acif command does not use a resource exit program. The exit program name is case-sensitive. The value is:

programname

Any valid resource exit program name.

reslib=

pathlist

Specifies the paths for the system resource directories. System resource directories typically contain resources that are shared by many users. The directories can contain any AFP resources (fonts, page segments, overlays, page definitions, or form definitions).

In most cases, you will want the acif command to find the same resources that PSF for AIX uses when it prints the file. If so, the

reslib paths should be the same as the paths specified with the respath parameter to PSF for AIX.

The value is:

pathlist

The acif command searches for resources in the following order:

1. Paths specified by the userlib parameter

2. Paths specified by the fdeflib, fontlib, pdeflib, pseglib, objconlib, and ovlylib parameters for specific types of resources

3. Paths specified by the reslib parameter

4. Paths specified by the PSFPATH environment variable

5. The directory /usr/lpp/psf/reslib

6. The directory /usr/lpp/afpfonts

7. The directory /usr/lpp/psf/fontlib

Any valid search path. You must use a colon (:) to separate multiple paths.

resobjdd={RESOBJ |

Specifies the name or the full path name for the resource file produced by ACIF. If you specify the file name without a path, ACIF puts the resource file into your current directory. When ACIF processes a print file, it can optionally create a file containing all or some of the resources required to print or view the file. ACIF writes the resource data in a file with this name. Values are:

RESOBJ ACIF writes the resource data in a file with this name.

filename

| restype={none | all | [fdef][,pseg][,ovly][,font][,objcon][,bcoca][,goca][,ioca]} | Specifies the type of AFP print resources ACIF should retrieve from | the resource directories for inclusion in the resource file ( resobjdd). | Values are:

| none Specifies that no resource file is to be created. | all Specifies that all resources required to print or view the

| output document file ( outputdd) will be included in the | resource file ( resobjdd).

filename

}

A character string containing only those alphanumeric characters supported AIX file names.

44 ACIF User’s Guide

| fdef Specifies that the form definition (formdef) used in | processing the file will be included in the resource file.

| pseg Specifies that all page segments required to print or view the | output document file will be included in the resource file.

| ovly Specifies that all overlays required to print or view the output | document file will be included in the resource file.

| font Specifies that all font character sets and code pages required | to print or view the output file will be included in the resource | file. If mcf2ref=cf is specified, ACIF also includes coded | fonts in the resource file. Otherwise, the coded fonts are | never included in the resource file.

| objcon Specifies that all object container files requested by the input | data stream (including the one specified by the comsetup | parameter) be included in the resource file.

| bcoca Specifies that all BCOCA objects included by an IOB | structured field required to print or view the output document | file be included in the resource file.

| goca Specifies that all GOCA objects included by an IOB | structured field required to print or view the output document | file be included in the resource file.

| ioca Specifies that all IOCA objects included by an IOB structured | field required to print or view the output document file be | included in the resource file.

| (See the reslib parameter for a description of how ACIF searches for | resources.)

| Because multiple resource types are contained in the page segment | library, and ACIF does not enforce a prefix for the 8-character | resource name, you should define a naming convention that identifies | each type of resource in the page segment library. IBM recommends | a two-character prefix:

| B1 for BCOCA objects | G1 for GOCA objects | I1 for IOCA objects | S1 for page segments

| ACIF supports the specification of fdef, font, objcon, ovly, bcoca, | goca, ioca, and pseg in any combination. For example, if you want to | specify form definitions, page segments, and overlays as the resource | types, you would enter:

| restype=fdef,pseg,ovly | Because Workbench Viewer does not use AFP raster fonts when

| presenting the data on the screen, you may want to specify | restype=fdef,ovly,pseg,objcon, bcoca, goca, ioca to prevent fonts | from being included in the resource file. This reduces the number of | bytes transmitted when the file is transferred to the workstation.

| Note: Keep in mind that if you have a resource type that you want | saved in a resource file, and it is included in another resource

Chapter 2. Using ACIF Parameters in AIX 45

| type, you must specify both resource types. For example, if | you request that just page segments be saved in a resource | file, and the page segments are included in overlays, the page | segments will not be saved in the resource file, because the | overlays will not be searched. In this case, you would have to | request that both page segments and overlays be saved.

trc={yes | no}

Specifies whether the input file contains Table Reference Characters (TRCs). Some applications may produce output that uses different fonts on different lines of a file by specifying TRCs at the beginning of each line after the carriage-control character, if one is present. Values are:

yes The input file contains table reference characters. no The input file does not contain table reference characters.

Consider the following when you use TRCs:

 The order in which the fonts are specified in the chars parameter

establishes which number is assigned to each associated TRC. For example, the first font specified is assigned 0, the second font 1, and so on.

triggern={

 If you specify trc=yes but TRCs are not contained in the file, the

acif command interprets the first character (or second, if

carriage-control characters are used) of each line as the font identifier. Consequently, the font used to process each line of the file may not be the one you expect, and one byte of data will be lost from each line.

 If you specify trc=no or you do not specify trc at all, but your data

contains a TRC as the first character (or second if carriage-control characters are used) of each line, the acif command interprets the TRC as a text character in the processed output, rather than using it as a font identifier.

record

| *},{

column

Specifies the locations and values of data fields within the input file that are to be used to define indexing groups in the file. These data fields are referred to as “triggers” because their presence in the file triggers a processing action. A maximum of four trigger parameters can be specified. The number of triggern parameters required to uniquely identify the beginning of a group of pages within the file is a function of the complexity of the application output. trigger1 is special and each record in the file containing this value is referred to as an indexing anchor record. The presence of a trigger parameter causes ACIF to index the input file. Each triggern parameter comprises three values:

| *},{'

trigger value

' |

X'trigger value

record

| * Specifies the relative record number from the indexing

anchor record (that is, trigger1). A value of ‘*’ can only be specified in trigger1; this value indicates that every record should be checked for the presence of the trigger1 value. After the trigger1 value has been found, all other triggern parameter values are specified as a relative offset from trigger1. ACIF reports an error

46 ACIF User’s Guide

condition and terminates processing if an ‘*’ is specified with any triggern parameter other than trigger1. The supported range of values for

record

is 0 to 255.

column

| * Specifies the byte offset from the beginning of the record

trigger value

where the trigger value is located. This value can be specified in absolute terms (for example, 10) or as ‘*’, which results in ACIF scanning the record from left to right looking for the trigger value. A value of 1 refers to the first byte in the record. For files containing carriage-control characters, column 1 refers to the carriage-control. The supported range of values for

column

are 1 to 32756. ACIF compares the trigger value to the input data. If the specified value exceeds the physical length of the record, ACIF considers the comparison “false” and continues processing.

' |

X'trigger value

Specifies the actual alphanumeric (case-sensitive) or hexadecimal value of the trigger. ACIF does not perform any validity checking on this value, but uses it in performing a byte-for-byte comparison with the records in the file. The trigger value can be 1–253 bytes in length. If the combined values of

column

and the trigger length exceed the physical length of the record, ACIF considers the comparison “false” and continues processing.

For example, to use a carriage-control character as a trigger, you enter:

trigger1=,1,'1' / Look for Skip-to-Channel 1 trigger2=,5,'ACCOUNT:' / Find account number trigger3=3,75,'PAGE 1' / Find page 1

In this example, trigger1 instructs ACIF to scan every record, looking for the occurrence of '1' in the first byte. After ACIF locates a record containing the '1', it looks in the same record, starting at byte 50, for the occurrence of ‘ACCOUNT:’. If ‘ACCOUNT:’ is found, ACIF looks at the third record down for a value of ‘PAGE 1’, starting at byte 75. If ‘PAGE 1’ is found, ACIF defines the record containing trigger1 as the indexing anchor record, and all indexing information is specified as relative locations relative from this point.

If ACIF finds either ‘ACCOUNT:’ or ‘PAGE 1’, ACIF begins scanning the first record after the farthest field specified. If either ‘ACCOUNT:’ or ‘PAGE 1’ are not found at their specified locations relative to trigger1, ACIF begins looking for trigger1 again, starting with the next record (that is, the current record containing trigger1 + 1).

Chapter 2. Using ACIF Parameters in AIX 47

Notes:

1. ACIF requires that at least one triggern or fieldn value appear within the page range specified by the indexstartby parameter. If no triggern or fieldn parameter is satisfied within the indexstartby page range, ACIF stops processing.

2. At least one triggern or fieldn must exist on the first page of every unique page group. ACIF cannot detect an error condition if

triggern or fieldn is missing, but the output may be incorrectly

indexed.

3. trigger1 must be specified when ACIF is requested to index the file.

4. An error condition will occur if you specify any trigger parameters when the input file contains indexing tags.

uniquebngs={yes | no}

Specifies whether ACIF creates a unique group name by generating an 8-character numeric string and appending the string to the group name. The group name defined in the Begin Named Page Group (BNG) structured field is comprised of an index value and a sequence number.

userlib=

yes Specifies that ACIF generate an 8-character numeric string and

append the string to the group name.

no ACIF does not generate the string. No is the default if you

specify dcfpagenames=yes. Specify no if you use the AFP API to generate your own group names.

pathlist

Specifies the names of user directories containing AFP resources for processing the input file. The directories can contain any AFP resources (fonts, page segments, overlays, page definitions, form definitions, or COM setup files).

By convention, these resources are typically used by one user, as opposed to the system resources (specified with the reslib parameter) that are shared by many users. Therefore, you should use the

userlib parameter to specify resources that are not retrieved with the fdeflib, fontlib, objconlib, ovlylib, pdeflib, or pseglib parameters.

The value is:

pathlist

The acif command searches for resources in the following order:

1. Paths specified by the userlib parameter

2. Paths specified by the fdeflib, fontlib, objconlib, ovlylib, pdeflib, pseglib parameters for specific types of resources

3. Paths specified by the reslib parameter

4. Paths specified by the PSFPATH environment variable

5. The directory /usr/lpp/psf/reslib

6. The directory /usr/lpp/afpfonts

7. The directory /usr/lpp/psf/fontlib

Any valid search path. You must use a colon (:) to separate multiple paths.

48 ACIF User’s Guide

Examples

The examples contained in this section show how to use ACIF processing parameters for conversion, resource retrieval, specifying fonts, and identifying the location of resource directories. For indexing examples, see Chapter 3, “Example of an ACIF Application in AIX” on page 53. For examples of how to use ACIF or the line2afp command to transform S/370 line data and unformatted ASCII files for printing with PSF for AIX, refer to “Using the line2afp Command” in

Services Facility for AIX: Print Submission

Note: In the following examples, ACIF is run by entering the acif command,

parameters, and values on the command line. When all of the parameters will not fit on a single line across the screen, the backslash, \, tells AIX to continue reading the command from the next line.

1. You have an EBCDIC S/370 line data file named OLDFILE.143 that you want to transform into a MO:DCA-P document named NEWFILE.afp.To do this, enter:

acif inputdd=OLDFILE.143 outputdd=NEWFILE.afp cctype=a \ fileformat=record pagedef=P1A6462 formdef=F1A111

IBM Print

ACIF converts the S/370 line data file, specified with the inputdd parameter, into a document file with the name specified by the outputdd parameter.

You specified cctype=a to indicate that the file contains EBCDIC ANSI carriage control characters. This particular input file is in S/370 variable length record format, so you indicated this by specifying fileformat=record. The pagedef and formdef parameters are required with your line data input file, so you specified the file names of the page definition and form definition you want ACIF to use in processing this file.

2. You have an AFP file (MYFILE) that contains page segments and overlays. You would like to retrieve the page segments and overlays from the file and create both a data file and a resource file. To do this, enter:

acif inputdd=MYFILE outputdd=MYDATA resobjdd=MYRES \

restype=pseg,ovly,fdef formdef=F1H111

From this job, ACIF will produce an AFP document file and a resource file. The AFP document file (MYDATA) will contain the AFP data from

MYFILE. The resource file (MYRES) will contain the resource data from MYFILE.

You specified restype=pseg,ovly,fdef so that the page segments and overlays would be included in the resource file, along with the form definition (specified with the formdef parameter) that you want ACIF to use when processing the file.

For more information about when and why you would want to use ACIF’s resource retrieval functions, refer to “Retrieving Resources” on page 14

3. You have an input file (MYFILE.asc) that contains unformatted ASCII data, and you want three coded fonts to be used in processing the file: Helvetica 12-point, and Times New Roman 10-point and 9-point. You

Chapter 2. Using ACIF Parameters in AIX 49

are using a page definition supplied with PSF for AIX (P1A6462), and the page definition does not name any fonts. To use the three fonts, specify the following:

acif inputdd=MYFILE.asc outputdd=MYFILE.afp chars=H2B2,N22,N292 \ trc=yes pagedef=P1A6462 formdef=F1A111

You specified the font names with the chars parameter. Because you need to use fonts with the appropriate ASCII code points for your unformatted ASCII input, you referred to Chapter 5, “IBM AFP Fonts for ASCII Data” on page 77. There you found that the IBM Core Interchange Font name is XH23B2 for Helvetica 12-point, XN232 for Times New Roman 10-point, and XN2392 for Times New Roman 9-point. Because the chars parameter limits the specification of a font name to four characters, you used the corresponding short name from the table for each of the three fonts, without eliminating the 2-character coded font prefix (X). Because table reference characters are required when you want the file to print with more than one font, you specified trc=yes.

Your input and output file names are specified with the inputdd and outputdd parameters. The page definition and form definition you want ACIF to use when processing the file are specified with the pagedef and formdef parameters.

4. You have an input file and you want to use specific resources during processing. You want to use a form definition (FORMD1A) and an overlay that are stored in the general resource directory at your location (/usr/site/resdir). To be sure that ACIF finds the resources you want to use, specify the following:

acif inputdd=INFILE outputdd=OUTFILE \ pagedef=PAGED6B formdef=FORMD1A \

userlib=/usr/mystuff/art1:/usr/mystuff/art2 \ pdeflib=/usr/dept/pdefdir3 reslib=/usr/site/resdir

The page definition you want to use (PAGED6B) is stored in one of the several page definition directories used by your department (/usr/dept/pdefdir3). The page definition is a copy of one with the same file name that is stored in the site’s general resource directory, with some modifications made for use by your department. Your page segments are stored in two other directories that you have set up for your own use (/usr/mystuff/art1 and /usr/mystuff/art2). Because ACIF always searches the path specified by the userlib parameter first, your page segments will be found in your personal directories. ACIF next searches the paths specified by the parameters for specific resource libraries (pdeflib, fdeflib, and so forth), so ACIF will then find the page definition you want to use from the department’s directory. ACIF will then search the path specified with the reslib parameter, finding your form definition and your overlay. ACIF will definition named PAGED6B that is stored in the /usr/site/resdir directory, because it will already have found the modified PAGED6B in the department directory specified with the pdeflib parameter.

not

use the page

50 ACIF User’s Guide

Implementation Specifics

The acif command is part of PSF for AIX, and is installed with the psf.acif option.

Files

/usr/lpp/psf/bin/acif

/usr/lpp/psf/acif/apkinp.c, apkind.c, apkres.c, apkout.c, apka2e.c, asciinp.c,

/usr/lpp/psf/bin/apka2e, apkinp, apkind, apkres, apkout, apka2e, asciinp,

/usr/lpp/psf/bin/Makefile

/usr/lpp/psf/acif/apkexits.h

The executable program (the acif command)

asciinpe.c

Sample ACIF user exits

asciinpe

Sample user exit executables

The build rules for the ACIF user exits, apkinp, apkind, apkres, apkout, apka2e, asciinp, and asciinpe

C language header file for the ACIF user exits

NLS Messages

ACIF messages on the AIX platform may be written in any one of the following languages: Simplified Chinese, Traditional Chinese, English, French, French-Canadian, German, or Japanese. The message files can be found in:

Consult the description of the NLSPATH and LANG environment variables for information on setting these variables in an appropriate manner. The default message catalog is

/usr/lib/nls/msg/enUS/ACIF.cat

Suggested Reading

“Transforming Line Data for Printing with PSF” in

AIX: Print Submission

“Form Definitions Supplied with PSF” and “Page Definitions Supplied with PSF” in

IBM Print Services Facility for AIX: Print Submission IBM Page Printer Formatting Aid/6000: User's Guide Version 2.1

how to create your own form definitions and page definitions. Refer also to

InfoPrint Manager for AIX: Administrator's Guide AIX: User's and Operator's Guide

/usr/lib/nls/msg/<country of choice>

IBM Print Services Facility for

for information on

and

IBM InfoPrint Manager for

IBM

Chapter 2. Using ACIF Parameters in AIX 51

52 ACIF User’s Guide

Chapter 3. Example of an ACIF Application in AIX

The line-data application used as the example in this section is shown in Figure 10 on page 54. The application generates telephone bills. The objective is to make the billing application output available on customer service representatives’ workstations. Then, when a customer calls with a billing inquiry, the representative can view the bill in the same format as the customer’s printed copy.

To do this, you must convert the output from your application into a document format that can be used with the Viewer application of AFP Workbench (Workbench Viewer). You also must index the file to facilitate searching the file with Workbench Viewer. To ensure that all resources used in the bills are available at the workstation, you must use the resource retrieval function of ACIF.

Your tasks include:

1. Examining the input file to determine how to tag it for viewing

2. Specifying ACIF parameters for indexing and resource retrieval for either ASCII or EBCDIC input data

3. Identifying the locations of the resources used when the bills are printed

4. Determining the form definition and page definition used to print the bills

5. Running the ACIF job

6. Concatenating the index object file, the resource file, and the document file

7. Making the document file available to a workstation running Microsoft Windows for viewing with Workbench Viewer

Note: This example is hypothetical; an input file is

example is intended only to help you understand how ACIF may be used for an actual application, and to assist you when you use ACIF for your own application. For practical use, you must provide your own input file, and specify paths, directories, and so forth, as they apply to your particular installation and application.

The following topics are covered in this section:

 An example of an input file  Specifying ACIF processing parameters for ASCII input data  Specifying ACIF processing parameters for EBCDIC input data  Identifying the locations of the specified resources  Determining the form definition and page definition resources needed to format

and print the ACIF job

not

actually provided. The

 How to run the ACIF job  The output files created by running the ACIF job  Concatenating the output files  Accessing the document file from a workstation for viewing

For an explanation of any parameter not specifically described in this section, see the description for that parameter in Chapter 2, “Using ACIF Parameters in AIX” on page 23.

Figure 10. Example of a Customer’s Telephone Bill

54 ACIF User’s Guide

The Input File

Figure 11 shows the line data file currently used to print the telephone bills.

Carriage Control ¦

Line ----+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8

 1 WILLIAM R. SMITH

- TOTAL AMOUNT DUE: $56.97

 1 BASIC SERVICE..............$3.56

2 LONG DISTANCE CHARGES

. . . . . . . . .$26.41

1  TOTAL . . . .$56.97

 BILL DATE: JAN 11, 1993

15 - $66.79 $66.79 $. $. $56.97

$56.97

2  SUMMARY OF CURRENT CHARGES  RESIDENCE SERVICE $25.7 911 SURCHARGE $.5

CUSTOMER ACCESS SERVICE $3.5

WIRING MAINTENANCE PLAN $.5 25 FEDERAL EXCISE TAX $.5 STATE TAX $.49

LONG DISTANCE CHARGES (ITEMIZED BELOW) $3.56

 LONG DISTANCE CHARGES

 NO. DATE TIME TO PLACE TO AREA NUMBER MINUTES AMOUNT 3  1 DEC 11 7:15P LOVELAND CO 33 666-7777 6 $.82 2 DEC 15 9:16A NIWOT CO 33 555-6666 12 $1.56

3 DEC 24 9:32P SANTA BARBARA CA 85 999-6666 32 $15.8 4 DEC 25 2:18P LAS VEGAS NV 72 888-7654 15 $8.23

- TOTAL . . . . . . .$26.41

35 -

 PAGE 1

528 SUNSHINE CANYON DR BOULDER CO 8-

DATE DUE: JAN 29, 1993

ACCOUNT NUMBER: 33-222-3456-6B

JAN 29, 1993

Figure 11. Line-Data Telephone Bill

Specifying ACIF Processing Parameters for ASCII Input Data

You can process the ACIF parameters that are needed to produce the telephone bill for this example application by using one of the following methods:

 Create and specify a parameter file  Enter the acif command, parameters, and values on the command line or in a

shell script

This section describes the creation of a parameter file that can be used to process ACIF parameters when the input file is in ASCII.

Chapter 3. Example of an ACIF Application in AIX 55

Using a Parameter File with ASCII Input Data

A parameter file created for use with ASCII input data is shown in Figure 12. To use a parameter file, you specify the parameter file name with the acif command parmdd parameter. For example, to use a parameter file named PARMFILE, specify:

acif parmdd=PARMFILE

cc=yes / carriage control used /

/ DATA CHARACTERISTICS /

cctype=z / ASCII ANSI carriage controls / chars=42B2 / coded font / cpgid=85 / code page identifier /

/ FIELD AND INDEX DEFINITION / field1=13,66,15 / Account Number data field / field2=,5,3 / Name data field / field3=1,5,3 / Address data field / field4=2,5,3 / City, State, Zip data field / field5=4,6,12 / Date Due data field / index1='Account Number',field1 / 1st index attribute / index2='Name',field2 / 2nd index attribute / index3='Address',field3 / 3rd index attribute / index4='City, State, Zip',field4 / 4th index attribute / index5='Date Due',field5 / 5th index attribute /

/ INDEXING INFORMATION / indexobj=all / index object file entries /

/ RESOURCE INFORMATION / formdef=F1A111 / formdef name / pagedef=P1A8682 / pagedef name / fdeflib=/usr/res/fdeflib1:/usr/res/fdeflib2 / formdef directories / fontlib=/usr/res/fontlib1:/usr/res/fontlib2 / font directories / ovlylib=/usr/res/ovlylib1:/usr/res/ovlylib2 / overlay directories / pdeflib=/usr/res/pdeflib1:/usr/res/pdeflib2 / pagedef directories / pseglib=/usr/res/pseglib1:/usr/res/pseglib2 / pseg directories / resobjdd=RESDATA / resource file name / restype=fdef,pseg,ovly / resource type selection /

/ FILE INFORMATION / indexdd=INDXOBJ / index file name / inputdd=/usr/data/INFILE / input path & file name / outputdd=OUTDOC / output file name / msgdd=acif.msg / error message file name /

/ EXIT AND TRIGGER INFORMATION / trigger1=,1,'1' / 1st trigger / trigger2=13,5,'ACCOUNT NUMBER' / 2nd trigger /

/ example phone bill /

Figure 12. Example of a Parameter File for ASCII Input Data

The example uses the following data values as the indexing attributes:  Account Number

 Name  Address

 City, State, Zip

 Date Due The task is to specify the ACIF indexing parameters so that the first page of each

bill includes group-level indexing tags containing the values of all five of these attributes.

To generate these indexing attributes, specify the trigger1 parameter first, because ACIF always scans for the data specified in trigger1 first. Because the data contains carriage control characters, including a carriage control character of 1 to indicate a new page, request that ACIF locate the start of a page by searching

56 ACIF User’s Guide

every record in the file for a trigger value of ‘1’ in column 1 of the data. To do this, specify:

trigger1 = ,1,'1'

When ACIF finds a record that contains a ‘1’ in column 1, that record becomes the indexing anchor record.

Subsequent triggern parameters are defined relative to the indexing anchor record. In this example, you want to ensure that the page being indexed is the first page of the bill, which is the only page in the bill that has the text ‘ACCOUNT NUMBER’ starting at byte 50 in the 13th record following the anchor record. To specify this additional trigger for locating the correct page to index, enter:

trigger2 = 13,5,'ACCOUNT NUMBER'

ACIF uses both trigger values to locate a place in the file to begin searching for the data supplied in the index parameters.

Next, specify the attribute name of the first indexing parameter as 'Account Number', and define the location of the attribute value in the data relative to the index anchor record set by trigger1. Because the data value for the Account Number attribute is located in the 13th record from the index anchor record starting in byte 66 and extending for 15 bytes, specify:

field1=13,66,15 index1='Account Number',field1

To create the indexing tag for the Name attribute, define 'Name' as the indexing attribute. Locate the value for ‘Name’ in the anchor record in the data starting at byte 50 and extending for 30 bytes. The ACIF parameters to specify this are:

field2=,5,3 index2='Name',field2

Repeat this process to specify the other three indexing tags, so that the index attributes and values are defined as follows:

 index1='Account Number',field1

– 'Account Number' is the 1st index attribute – field1 maps to the field1 index value, which is:

- 13 lines down from the indexing anchor record, 66 columns across, 15 bytes in length

 index2='Name',field2

– 'Name' is the 2nd index attribute – field2 maps to the field2 index value, which is:

- 0 lines down (in the indexing anchor record), 50 columns across, 30 bytes in length

 index3='Address',field3

– 'Address' is the 3rd index attribute – field3 maps to the field3 index value, which is:

- 1 line down from the indexing anchor record, 50 columns across, 30 bytes in length

 index4='City, State, Zip',field4

– 'City, State, Zip' is the 4th index attribute – field4 maps to the field4 index value, which is:

Chapter 3. Example of an ACIF Application in AIX 57

- 2 lines down from the indexing anchor record, 50 columns across, 30 bytes in length

 index5='Date Due',field5

– 'Date Due' is the 5th index attribute – field5 maps to the field5 index value, which is:

- 4 lines down from the indexing anchor record, 60 columns across, 12 bytes in length

The result of using these indexing parameters is that the first page of each bill in the ACIF output file will contain indexing tags for each of the five indexing attributes. Using Workbench Viewer, customer service representatives can locate a single customer bill in the ACIF document using any combination of the indexing attributes.

Specifying ACIF Processing Parameters for EBCDIC Input Data

You can process the ACIF parameters that are needed to produce the telephone bill for this example application by using one of the following methods:

 Create and specify a parameter file  Enter the acif command, parameters, and values on the command line or in a

shell script

This section describes the creation of a parameter file that can be used to process ACIF parameters when the input file is in EBCDIC.

For the sake of this example, assume that the data was generated on a S/370, and is accessed via NFS. The disk where the input data resides is mounted as binary, which retains the data as EBCDIC. The input data is in variable length record format on the S/370 host, so a fileformat parameter, specifying fileformat=record, is required. (See the description of the fileformat parameter, on page 33.)

Using a Parameter File with EBCDIC Input Data

A parameter file created for use with EBCDIC input data is shown in Figure 13 on page 59. To use a parameter file, you specify the parameter file name with the acif command parmdd parameter. For example, to use a parameter file named

PARMFILE, specify: parmdd=PARMFILE

Note: Literal values used in the field, index and trigger parameters must be

expressed in hexadecimal strings when the input data is anything other than ASCII. In Figure 13, because the input data is EBCDIC, hexadecimal strings are entered which represent the literal values. For example, ‘Name’, which is the 2nd index attribute, for the 2nd data field, is represented as follows:

index2=X'D5819485',field2

58 ACIF User’s Guide

cc=yes / carriage control used /

/ DATA CHARACTERISTICS /

cctype=a / EBCDIC ANSI carriage controls / chars=GT15 / coded font / cpgid=37 / code page identifier /

/ FIELD AND INDEX DEFINITION / field1=13,66,15 / Account Number data field / field2=,5,3 / Name data field / field3=1,5,3 / Address data field / field4=2,5,3 / City, State, Zip data field / field5=4,6,12 / Date Due data field / index1=X'C1838396A495A34D5A494828599',field1 / 1st index attr (Account Number) / index2=X'D5819485',field2 / 2nd index attr (Name) / index3=X'C184849985A2A2',field3 / 3rd index attr (Address) / index4=X'C389A3A86B4E2A381A3856B4E98997',field4 / 4th index attr (City, State, Zip) / index5=X'C481A3854C4A485',field5 / 5th index attr (Date Due) /

/ INDEXING INFORMATION / fileformat=record / input file format / indexobj=all / index object file entries /

/ RESOURCE INFORMATION / formdef=F1A111 / formdef name / pagedef=P1A8682 / pagedef name / fdeflib=/usr/res/fdeflib1:/usr/res/fdeflib2 / formdef directories / fontlib=/usr/res/fontlib1:/usr/res/fontlib2 / font directories / ovlylib=/usr/res/ovlylib1:/usr/res/ovlylib2 / overlay directories / pdeflib=/usr/res/pdeflib1:/usr/res/pdeflib2 / pagedef directories / pseglib=/usr/res/pseglib1:/usr/res/pseglib2 / pseg directories / restype=fdef,pseg,ovly / resource type selection /

/ FILE INFORMATION / indexdd=INDXOBJ / index file name / inputdd=/usr/data/INFILE / input path & file name / msgdd=acif.msg / error message file name / outputdd=OUTDOC / output file name / resobjdd=RESDATA / resource file name /

/ EXIT AND TRIGGER INFORMATION / trigger1=,1,X'F1' / 1st trigger (1) / trigger2=13,5,X'C1C3C3D6E4D5E34D5E4D4C2C5D9' / 2nd trigger (ACCOUNT NUMBER) /

/ example phone bill /

Figure 13. Example of a Parameter File for EBCDIC Input Data

The example uses the following data values as the indexing attributes:  Account Number

 Name  Address

 City, State, Zip

 Date Due The task is to specify the ACIF indexing parameters so that the first page of each

bill includes group-level indexing tags containing the values of all five of these attributes.

trigger1 = ,1,X'F1'

When ACIF finds a record that contains a ‘1’ in column 1, that record becomes the indexing anchor record.

Chapter 3. Example of an ACIF Application in AIX 59

Subsequent triggern parameters are defined relative to the indexing anchor record. In this example, you want to ensure that the page being indexed is the first page of the bill, which is the only page in the bill that has the hexadecimal string for the text ‘ACCOUNT NUMBER’ starting at byte 50 in the 13th record following the anchor record. To specify this additional trigger for locating the correct page to index, enter:

trigger2=13,5,X'C1C3C3D6E4D5E34D5E4D4C2C5D9' ACIF uses both trigger values to locate a place in the file to begin searching for the

data supplied in the index parameters. Next, specify the attribute name of the first indexing parameter as the hexadecimal

string for 'Account Number', and define the location of the attribute value in the data relative to the index anchor record set by trigger1. Because the data value for the Account Number attribute is located in the 13th record from the index anchor record starting in byte 66 and extending for 15 bytes, specify:

field1=13,66,15 index1=X'C1838396A495A34D5A494828599',field1

To create the indexing tag for the Name attribute, define the hexadecimal string for 'Name' as the indexing attribute. Locate the value for ‘Name’ in the anchor record in the data starting at byte 50 and extending for 30 bytes. The ACIF parameters to specify this are:

field2=,5,3 index2=X'D5819485',field2

Repeat this process to specify the other three indexing tags, so that the index attributes and values are defined as follows:

 index1=X'C1838396A495A34D5A494828599',field1

– X'C1838396A495A34D5A494828599' is ‘Account Number’, the 1st index

attribute

– field1 maps to the field1 index value, which is:

- 13 lines down from the indexing anchor record, 66 columns across, 15 bytes in length

 index2=X'D5819485',field2

– X'D5819485' is ‘Name’, the 2nd index attribute – field2 maps to the field2 index value, which is:

- 0 lines down (in the indexing anchor record), 50 columns across, 30 bytes in length

 index3=X'C184849985A2A2',field3

– X'C184849985A2A2' is ‘Address’, the 3rd index attribute – field3 maps to the field3 index value, which is:

- 1 line down from the indexing anchor record, 50 columns across, 30 bytes in length

 index4=X'C389A3A86B4E2A381A3856B4E98997',field4

– X'C389A3A86B4E2A381A3856B4E98997' is ‘City, State, Zip’, the 4th index

attribute

– field4 maps to the field4 index value, which is:

- 2 lines down from the indexing anchor record, 50 columns across, 30 bytes in length

60 ACIF User’s Guide

 index5=X'C481A3854C4A485',field5

– X'C481A3854C4A485' is ‘Date Due’, the 5th index attribute – field5 maps to the field5 index value, which is:

- 4 lines down from the indexing anchor record, 60 columns across, 12 bytes in length

Using the Shell with EBCDIC Literal Values

Literal values used in the field, index, and trigger parameters must be expressed in hexadecimal strings when the input data is anything other than ASCII. Because the input data for this example is EBCDIC, hexadecimal strings are required, and

must

be entered if you specify your parameters within a parameter file. If the parameters are as axeb or iconv) to convert ASCII literal values into EBCDIC literal values. For example, to convert the ASCII literal ‘Name’, for the 2nd index attribute (index2), do the following:

not

specified in a parameter file, you can use AIX commands (such

1. Create a shell environment variable to hold the EBCDIC literal

 To do this using the AIX axeb command, enter:

attr2=$(echo -n "Name" | axeb)

 To do this using the AIX iconv command, enter:

attr2=$(echo -n "Name" | iconv -fIBM-85 -tIBM-37)

2. Then, on the command line or in a shell script, specify the 2nd index attribute by entering:

index2="'$attr2'",field2

Note: This example is for use with the Korn Shell (ksh). If you are using a

different shell, refer to the documentation for the shell you are using in

AIX for RISC System/6000 Commands Reference

By using this method to convert the ASCII literals to the EBCDIC literals, no mistakes are made when converting the literals to a hexadecimal string.

Identifying the Locations of the Resources

To build the resource file, ACIF must know where to find the resources specified in the job. In the example, the following directories are defined:

fdeflib Form definition directories, /usr/res/fdeflib1:/usr/res/fdeflib2 fontlib Font directories, /usr/res/fontlib1:/usr/res/fontlib2 ovlylib Overlay directories, /usr/res/ovlylib1:/usr/res/ovlylib2 pdeflib Page definition directories, /usr/res/pdeflib1:/usr/res/pdeflib2

| pseglib Page segment, BCOCA (barcode), GOCA (graphics), IOCA (IO image) | directories, /usr/res/pseglib1:/usr/res/pseglib2

Chapter 3. Example of an ACIF Application in AIX 61

Determining the Form Definition and the Page Definition

To format and print the job, you need to specify page definition and form definition resources. In the example, the following resources are used:

formdef F1A10110, a standard form definition, provided with PSF for AIX pagedef P1A08682, a standard page definition, provided with PSF for AIX

Running the ACIF Job

You can run the ACIF job using one of the following methods:

 Use a parameter file that contains the parameters and values needed for the

application. To run the acif command with a parameter file named PARMFILE, you would enter:

acif parmdd=PARMFILE

 Enter the acif command, parameters and values on the command line or in a

shell script. For the example application you would enter:

acif cc=yes cctype=z chars=42B2 cpgid=85... and so forth (continuing by entering all of the remaining parameters and values)

ACIF Output

See “Examples” on page 49 for examples of running ACIF from the command line. For information on creating and running shell scripts, refer to

IBM Print Services Facility for AIX: AIX for Users of Print Services

Facility

The acif command then processes the parameters that you have specified on the command line, in the parameter file, or in the shell script.

With the example, the ACIF job creates the following output files in the current directory:

OUTDOC The document file, including indexing structured fields INDXOBJ The index object file RESDATA The resource file acif.msg The message file listing, including the ACIF parameters used, the

resources used, and the return code

To view the document file on a workstation using Workbench Viewer, you must first concatenate the index object file, the resource file, and the document file.

Concatenating ACIF Output Files

The following are examples of shell commands you can use to perform the concatenation of the index object file, the resource file, and the document file.

Note: To view the concatenated file with Workbench Viewer, it is important that

the index object file is first, followed by the resource file, and then the document file. The document file must be the last data in the concatenated file.

62 ACIF User’s Guide

 In the following example, the index object file, the resource file, and the

document file are combined to create a new file that contains all three files:

cat INDXOBJ RESDATA OUTDOC > NEWFILE

 In the following example, the resource file and the document file are added on

to the end of the existing index object file:

cat RESDATA OUTDOC >> INDXOBJ

You may use whichever method you prefer to concatenate the files. You do need to do both.

Accessing the Document File from the Workstation

To view the concatenated document file, it must be accessed from a workstation running Microsoft Windows for viewing with Workbench Viewer. You can access the file from the workstation by either of the following methods:



Transfer

Workbench Viewer is installed



Mount

installed

Each of these methods is described in the following sections.

Notes:

1. Whether you directory on the workstation system, you must have TCP/IP installed on both the AIX system and on the workstation system where Workbench Viewer is installed.

2. To installed, you must have TCP/IP with Network File System (NFS) installed on both the AIX system and on the workstation system where Workbench Viewer is installed.

the document file, in binary format, to the workstation where

your AIX directory on the workstation where Workbench Viewer is

transfer

mount

your AIX directory on the workstation where Workbench Viewer is

the file to the workstation, or you

mount

not

your AIX

For additional information about TCP/IP and NFS, please refer to your TCP/IP documentation.

Transferring the Document File to the Workstation

You can Windows and Workbench Viewer are installed with the File Transfer Protocol (FTP) program, using the following procedures:

 From the drive and directory of the workstation where you want the document

ftp

 You will then be prompted for your AIX user name.

 You will then be prompted for the password for your AIX user name.

Chapter 3. Example of an ACIF Application in AIX 63

transfer

file to reside, enter the FTP command and the name of your AIX system:

the concatenated document file to the workstation where Microsoft

AIXsystemname

Enter your AIX user name

Enter the password for your AIX user name

 Access the AIX directory where the concatenated document file currently

resides. Enter:

 The file must be transferred in binary format, so you must now enter:

bin

 To transfer a concatenated document file named NEWFILE, enter:

get NEWFILE

 The file will now be copied to the workstation, where you may open it for

viewing with Workbench Viewer.

AIXdirectoryname

Mounting the AIX Directory on the Workstation

| You can | Workbench Viewer are installed by using the NFS mount command and the | procedures documented in the Network File System manuals or your own | installation file mounting procedures.

mount

your AIX directory on the workstation where Microsoft Windows and

64 ACIF User’s Guide

Chapter 4. User Exits and Attributes of the Input Print File in AIX

| This chapter contains programming interface information.

A user exit is a point during ACIF processing that enables you to run a user-written program and return control of processing to ACIF after your user-written program ends. ACIF provides data at each exit that can serve as input to the user-written program.

This section describes the following topics:

User programming exits Non-zero return codes Attributes of the input print file

User Programming Exits

ACIF provides several sample programming exits to assist you in customizing the product. Use of the programming exits is optional. You specify the names of the exit programs with the inpexit, indxexit, outexit, and resexit parameters. Each of these parameters is described in Chapter 2, Using ACIF Parameters in AIX.

ACIF provides the following sample exits:

/usr/lpp/psf/acif/apkinp.c Input record exit /usr/lpp/psf/acif/apkind.c Index record exit /usr/lpp/psf/acif/apkout.c Output record exit

/usr/lpp/psf/acif/apkres.c Resource exit

In addition, ACIF provides the following user input record exits to translate input data streams:

/usr/lpp/psf/acif/apka2e.c

Converts ASCII stream data to EBCDIC stream data.

/usr/lpp/psf/acif/asciinp.c

/usr/lpp/psf/acif/asciinpe.c

Converts unformatted ASCII data into a record format as does asciinp.c, and then converts the ASCII stream data to EBCDIC stream data.

The C language header file for all ACIF exit programs is also provided: /usr/lpp/psf/acif/apkexits.h along with the build rules for the ACIF user exits: /usr/lpp/psf/acif/Makefile

For more information about compiling user exit programs, refer to IBM InfoPrint Manager for AIX Administrator's Guide, S544-5595, or

for AIX: Print Administration

Input Record Exit

ACIF provides an exit that enables you to add, delete, or modify records in the input file. You can also use the exit to insert indexing information. The program invoked at this exit is defined in the ACIF inpexit parameter.

This exit is called after each record is read from the input file. The exit can request that the record be discarded, processed, or processed and control returned to the exit for the next input record. The largest record that can be processed is 32756 bytes. This exit is not called when ACIF is processing resources from directories.

In a MO:DCA-P document, indexing information can be passed in the form of a Tag Logical Element (TLE) structured field. For more information about the TLE structured field, see 36 The exit program can create these structured fields while ACIF is processing the print file. This is an alternative to modifying the application in cases where the indexing information is not consistently present in the application output.

IBM Print Services Facility

Note: TLEs are not supported in line-mode or mixed-mode data. Figure 14 contains a sample C language header that describes the control block

that is passed to the exit program.

typedef struct _INPEXIT_PARMS / Parameters for the input record exit /

{

char work; / Address of 16-byte static work area / PFATTR pfattr; / Address of print file attribute information / char record; / Address of the input record / void reserved1; / Reserved for future use / unsigned short recordln; / Length of the input record / unsigned short reserved2; / Reserved for future use / char request; / Add, delete, or process the record / char eof; / EOF indicator /

} INPEXIT_PARMS;

Figure 14. Sample Input Record Exit C Language Header

The address of the control block containing the following parameters is passed to the input record exit:

work (Bytes 1–4)

A pointer to a static, 16-byte memory block. The exit program can use this parameter to save information across calls (for example, pointers to work areas). The 16-byte work area is aligned on a full word boundary and is initialized to binary zeros prior to the first call. The user-written exit program must provide the code required to manage this work area.

pfattr (Bytes 5–8)

A pointer to the print file attribute data structure. See “Attributes of the Input Print File” on page 74 for more information on the format of this data structure and the information it contains.

66 ACIF User’s Guide

record (Bytes 9–12)

A pointer to the first byte of the input record including the carriage control character. The record resides in a buffer that resides in storage allocated by ACIF, but the exit program is allowed to modify the input record.

reserved1 (Bytes 13–16)

These bytes are reserved for future use.

recordln (Bytes 17–18)

Specifies the number of bytes (length) of the input record. If the input record is modified, this parameter must also be updated to reflect the actual length of the record.

reserved2 (Bytes 19–20)

These bytes are reserved for future use.

request (Byte 21)

Specifies how the record is to be processed by ACIF. On entry to the exit program, this parameter is X'00'. When the exit program returns control to ACIF, this parameter must have the value X'00', X'01', or X'02', where:

X'00' Specifies that the record be processed by ACIF. X'01' Specifies that the record not be processed by ACIF. X'02' Specifies that the record be processed by ACIF and control returned

to the exit program to allow it to insert the next record. The exit program can set this value to save the current record, insert a record, and then supply the saved record at the next call. After the exit inserts the last record, the exit program must reset the request byte to X'00'.

A value of X'00' on entry to the exit program specifies that the record be processed. If you want to ignore the record, change the request byte value to X'01'. If you want the record to be processed, and you want to insert an additional record, change the request byte value to X'02'. Any value greater than X'02' is interpreted as X'00', and the exit processes the record.

Note: Only one record can reside in the buffer at any time.

eof (Byte 22)

An End-Of-File (eof) indicator. This indicator is a 1-byte character code that specifies whether an eof condition has been encountered. When eof is signaled (eof value=‘Y’), the last record has already been presented to the input exit, and the input file has been closed. The pointer record is no longer valid. Records may not be inserted when eof is signaled. The following are the only valid values for this parameter:

Y Specifies that eof has been encountered. N Specifies that eof has not been encountered.

This end-of-file indicator allows the exit program to perform some additional processing at the end of the print file. The exit program cannot change this parameter.

Chapter 4. User Exits and Attributes of the Input Print File in AIX 67

Using the ACIF User Input Record Exits

The apka2e input record exit program translates data that is encoded in ASCII (code set IBM-850) into EBCDIC (code set IBM-037) encoded data. You should use this exit when your print job requires fonts such as GT12, which has only EBCDIC code points defined.

To execute the apka2e input record exit program, set the following parameters as follows in your ACIF parameter file:

inpexit=apka2e cc=yes cctype=z

Also, ensure that the directory where the apka2e input record exit program resides is included in the PATH environment variable. When determining offsets for indexing parameters, if asciinp is to be used with ACIF to produce an index file, consideration must be made for the carriage control character inserted by asciinp into byte 0.

The asciinp input record exit program transforms an ASCII data stream into a record format that contains a carriage control character in byte 0 of every record. If byte 0 of the input record is an ASCII carriage return (X'0D'), byte 0 is transformed into an ASCII space (X'20') that causes a data stream to return and advance one line; no character is inserted. If byte 0 of the input record is an ASCII form feed character (X'0C'), byte 0 is transformed into an ANSI skip to channel 1 command (X'31') that serves as a form feed in the carriage control byte.

To execute the asciinp input record exit program, set the following parameters as follows in your ACIF parameter file:

inpexit=asciinp cc=yes cctype=z

Also, ensure that the directory where the asciinp input record exit program resides is included in the PATH environment variable.

Note: If asciinp is to be used with ACIF to produce an index file, consideration

must be made for the carriage control character inserted by asciinp into byte 0, when determining offsets for indexing parameters.

The asciinpe input record exit program combines both user input record exits described above. To execute, specify inpexit=asciinpe and follow the directions specified for both apka2e and asciinp. Also, ensure that the directory where the asciinpe input record exit program resides is included in the PATH environment variable.

Note: If asciinpe is to be use d with ACIF to produce an index file, consideration

must be made for the carriage control character inserted by asciinp into byte 0, when determining offsets for indexing parameters.

While the asciinp and asciinpe input record exits do not recognize other ASCII printer commands, you can modify these exits to account for the following:

 backspacing (X'08')

 horizontal tabs (X'09')  vertical tabs (X'0B')

68 ACIF User’s Guide

For more information on using and modifying these programs, refer to the prolog of the asciinp.c source file that is provided with PSF for AIX in the /usr/lpp/psf/acif directory.

Index Record Exit

ACIF provides an exit that allows you to modify or ignore the records that ACIF writes in the index object file. The program invoked at this exit is defined by the ACIF indxexit parameter.

This exit receives control before a record (structured field) is written to the index object file. The exit program can request that the record be ignored or processed. The largest record that can be processed is 32752 bytes (this does not include the record descriptor word).

Figure 15 contains a sample C language header that describes the control block that is passed to the exit program.

typedef struct _INDXEXIT_PARMS / Parameters for the index record exit /

{

char work; / Address of 16-byte static work area / PFATTR pfattr; / Address of print file attribute information / char record; / Address of the record to be written / unsigned short recordln; / Length of the output index record / char request; / Delete or process the record / char eof; / Last call indicator to ACIF /

} INDXEXIT_PARMS;

Figure 15. Sample Index Record Exit C Language Header

The address of the control block containing the following parameters is passed to the index record exit:

work (Bytes 1–4)

pfattr (Bytes 5–8)

record (Bytes 9–12)

A pointer to the first byte of the index record including the carriage control character. The record resides in a 32KB (where KB equals 1024 bytes) buffer. The buffer resides in storage allocated by ACIF, but the exit program is allowed to modify the index record.

recordln (Bytes 13–14)

Specifies the length, in bytes, of the index record. If the index record is modified, this parameter must also be updated to reflect the actual length of the record.

Chapter 4. User Exits and Attributes of the Input Print File in AIX 69

request (Byte 15)

X'00' Specifies that the record be processed by ACIF. X'01' Specifies that the record not be processed by ACIF.

A value of X'00' on entry to the exit program specifies that the record be processed. If you want to ignore the record, change the request byte value to X'01'. Any value greater than X'01' is interpreted as X'00'; the record is processed.

Note: Only one record can reside in the buffer at any time.

eof (Byte 16)

An End-Of-File (eof) indicator. This indicator is a 1-byte character code that signals when ACIF has finished processing the index object file.

When eof is signaled (eof value=‘Y’), the last record has already been presented to the index exit. The pointer record is no longer valid. Records may not be inserted when eof is signaled. The following are the only valid values for this parameter:

Y Specifies that the last record has been written. N Specifies that the last record has not been written.

This end-of-file flag, used as a last call indicator, allows the exit program to return control to ACIF. The exit program cannot change this parameter.

Output Record Exit

Using the output record exit, you can modify or ignore the records ACIF writes into the output document file. The program invoked at this exit is defined by the ACIF outexit parameter.

The exit receives control before a record (structured field) is written to the output document file. The exit can request that the record be ignored or processed. The largest record that the exit can process is 32752 bytes, not including the record descriptor word. The exit is not called when ACIF is processing resources.

Figure 16 contains a sample C language header that describes the control block passed to the exit program.

typedef struct _OUTEXIT_PARMS / Parameters for the output record exit /

{

char work; / Address of 16-byte static work area / PFATTR pfattr; / Address of print file attribute information / char record; / Address of the record to be written / unsigned short recordln; / Length of the output record / char request; / Delete or process the record / char eof; / Last call indicator /

} OUTEXIT_PARMS;

Figure 16. Sample Output Record Exit C Language Header

The address of the control block containing the following parameters is passed to the output record exit:

70 ACIF User’s Guide

work (Bytes 1–4)

pfattr (Bytes 5–8)

record (Bytes 9–12)

A pointer to the first byte of the output record. The record resides in a 32KB (where KB equals 1024 bytes) buffer. The buffer resides in storage allocated by ACIF, but the exit program is allowed to modify the output record.

recordln (Bytes 13–14)

Specifies the length, in bytes, of the output record. If the output record is modified, this parameter must also be updated to reflect the actual length of the record.

request (Byte 15)

X'00' Specifies that the record be processed by ACIF. X'01' Specifies that the record be ignored by ACIF.

Note: Only one record can reside in the buffer at any time.

eof (Byte 16)

An End-Of-File (eof) indicator. This indicator is a 1-byte character code that signals when ACIF has finished writing the output file.

When eof is signaled (eof value=‘Y’), the last record has already been presented to the output exit. The pointer record is no longer valid. Records may not be inserted when eof is signaled. The following are the only valid values for this parameter:

Y Specifies that the last record has been written. N Specifies that the last record has not been written.

This end-of-file flag, used as a last-call indicator, allows the exit program to return to ACIF. The exit program cannot change this parameter.

Chapter 4. User Exits and Attributes of the Input Print File in AIX 71

Resource Exit

ACIF provides an exit that enables you to “filter” resources from being included in the resource file. If you want to exclude a specific type of resource (for example, an overlay), you can control this with the restype parameter. This exit is useful in controlling resources at the file name level. For example, assume you were going to send the output of ACIF to PSF for AIX and you only wanted to send those fonts that were not shipped with the PSF for AIX product. You could code this exit program to contain a table of all fonts shipped with PSF for AIX and filter those from the resource file. Security is another consideration for using this exit because you could prevent certain named resources from being included. The program invoked at this exit is defined by the ACIF resexit parameter.

This exit receives control before a resource is read from a directory. The exit program can request that the resource be processed or ignored (skipped), but it cannot substitute another resource name in place of the requested one. If the exit requests any overlay to be ignored, ACIF will automatically ignore any resources the overlay may have referenced (that is, fonts and page segments).

Figure 17 contains a sample C language header that describes the control block that is passed to the exit program.

typedef struct _RESEXIT_PARMS / Parameters for the resource record exit /

{

char work; / Address of 16-byte static work area / PFATTR pfattr; / Address of print file attribute information / char resname[8]; / Name of requested resource / char restype; / Type of resource / char request; / Ignore or process the resource / char eof; / Last call indicator /

} RESEXIT_PARMS;

Figure 17. Sample Resource Exit C Language Header

The address of the control block containing the following parameters is passed to the resource record exit:

work (Bytes 1–4)

pfattr (Bytes 5–8)

A pointer to the print file attribute data structure. See “Attributes of the Input Print File” on page 74 for more information on the format of this data structure and the information presented.

resname (Bytes 9–16)

Specifies the name of the requested resource. This value cannot be modified (changed) by the exit program.

restype (Byte 17)

Specifies the type of resource the name refers to. This is a 1-byte hexadecimal value where:

72 ACIF User’s Guide

| X'03' Specifies a GOCA (graphics) object | X'05' Specifies a BCOCA (barcode) object | X'06' Specifies an IOCA (IO image) object

X'40' Specifies a font character set. X'41' Specifies a code page.

| X'42' Specifies a coded font.

X'FB' Specifies a page segment. X'FC' Specifies an overlay.

ACIF does not call this exit for the following resource types:  Page definition

The page definition (pagedef) is a required resource for processing line-mode application output. The page definition is never included in the resource file.

 Form definition

The form definition (formdef) is a required resource for processing print files. If you do not want the form definition included in the resource file, specify restype=none or explicitly exclude it from the restype list.

 Coded fonts

| If MCF2REF=cf is specified, coded fonts are included in the resource file.

 COM setup files

A COM setup file (setup) is a required resource for processing microfilm files. If you do not want a setup file included in the resource file, specify

restype=none or explicitly exclude it from the restype list.

request (Byte 18)

Specifies how the resource is to be processed by ACIF. On entry to the exit program, this parameter is X'00'. When the exit program returns control to ACIF, this parameter must have the value X'00' or X'01' where:

X'00' Specifies that the resource be processed by ACIF. X'01' Specifies that the resource not be processed by ACIF.

A value of X'00' on entry to the exit program specifies that the resource be processed. If you want to ignore the resource, change the request byte value to X'01'. Any value greater than X'01' is interpreted as X'00' the resource is processed.

eof (Byte 19)

An End-Of-File (eof) indicator. This indicator is a 1-byte character code that signals when ACIF has finished writing the resource file.

When eof is signaled (eof value = ‘Y’), the last record has already been presented to the resource exit. The pointer record is no longer valid. Records may not be inserted when eof is signaled. The following are the only valid values for this parameter:

Y Specifies that the last record has been written. N Specifies that the last record has not been written.

This end-of-file flag, used as a last-call indicator, returns control to ACIF. The exit program cannot change this parameter.

Chapter 4. User Exits and Attributes of the Input Print File in AIX 73

Non-Zero Return Codes

If ACIF receives a non-zero return code from any exit program, ACIF issues message 0425-412 and terminates processing.

Attributes of the Input Print File

ACIF provides information about the attributes of the input print file in a data structure available to ACIF’s user exits. Figure 18 shows the format of this data structure.

typedef struct _PFATTR / Print File Attributes /

{

char cc[3]; / Carriage controls? - "YES" or "NO " / char cctype[1]; / Carriage control type - A(ANSI), M(Machine), Z(ASCII) / char chars[2]; / CHARS values, including commas (eg. GT12,GT15) / char formdef[8]; / Form Definition (FORMDEF) / char pagedef[8]; / Page Definition (PAGEDEF) / char prmode[8]; / Processing mode / char trc[3]; / Table Reference Characters - "YES" or "NO " /

} PFATTR;

Figure 18. Sample Print File Attributes C Language Header

The address of the control block containing the following parameters is passed to the user exits:

cc (Bytes 1–3)

The value of the cc parameter as specified on the acif command. ACIF uses the default value if this parameter is not explicitly specified.

cctype (Byte 4)

The value of the cctype parameter as specified on the acif command. ACIF uses the default value if this parameter is not explicitly specified.

chars (Bytes 5–24)

The value of the chars parameter as specified on the acif command, including any commas that separate multiple font specifications. Because the chars parameter has no default value, this field contains blanks if no values are specified.

formdef (Bytes 25–32)

The value of the formdef parameter as specified on the acif command. Because the formdef parameter, has no default value, this field contains blanks if no value is specified.

pagedef (Bytes 33–40)

The value of the pagedef parameter as specified on the acif command. Because the pagedef parameter has no default value, this field contains blanks if no value is specified.

prmode (Bytes 41–48)

The value of the prmode parameter as specified on the acif command. Because the prmode parameter has no default value, this field contains blanks if no value is specified.

74 ACIF User’s Guide

trc (Bytes 49–51)

The value of the trc parameter as specified on the acif command. ACIF uses the default value if this parameter is not explicitly specified.

Notes:

1. Each of the previous character values is left-justified; that is, padding blanks are added to the end of the string. For example, if pagedef=P1TEST is specified on the acif command, the page definition value in the above data structure is ‘P1TEST’.

2. Exit programs cannot change the values supplied in this data structure. For example, if ‘P1TEST’ is the page definition value, and an exit program changes the value to ‘P1PROD’, ACIF still uses ‘P1TEST’.

3. This data structure is provided for informational purposes only.

Chapter 4. User Exits and Attributes of the Input Print File in AIX 75

76 ACIF User’s Guide

Chapter 5. IBM AFP Fonts for ASCII Data

When you specify a coded font name with the chars parameter of the acif command or the line2afp command, the font name is limited to four characters, excluding the two-character prefix.

| Figure 19 provides a list of the IBM Core Interchange Fonts for use with | unformatted ASCII input data. Because these fonts have eight-character names, the | table also provides a list of six-character short names. (Reminder: PSF for AIX | must be installed if you want to use documented examples that contain pathnames | indicating PSF.) These coded fonts are installed in the /usr/lpp/psf/reslib directory | when the psf.acif installation option is installed for PSF 2.1 for AIX. However, for | InfoPrint Manager, the ACIF component is installed automatically. The installation | program also creates the symbolic links of the eight-character names that | correspond to the six-character names. You may use these short names, | the X prefix, to satisfy the four-character limitation for specifying font names with | the chars parameter.

without

Figure 19 (Page 1 of 2). Font Mapping Table for Use with the chars Parameter

Linked Short

Point

Type Family

Courier 7 X0423072 X04272 Courier 8 X0423082 X04282 Courier 10 X0423002 X04202 Courier 12 X04230B2 X042B2 Courier 14 X04230D2 X042D2 Courier 20 X04230J2 X042J2 Helvetica 6 X0H23062 X0H262 Helvetica 7 X0H23072 X0H272 Helvetica 8 X0H23082 X0H282 Helvetica 9 X0H23092 X0H292 Helvetica 10 X0H23002 X0H202 Helvetica 11 X0H230A2 X0H2A2 Helvetica 12 X0H230B2 X0H2B2 Helvetica 14 X0H230D2 X0H2D2 Helvetica 16 X0H230F2 X0H2F2 Helvetica 18 X0H230H2 X0H2H2 Helvetica 20 X0H230J2 X0H2J2 Helvetica 24 X0H230N2 X0H2N2 Helvetica 30 X0H230T2 X0H2T2 Helvetica 36 X0H230Z2 X0H2Z2 Times New Roman 6 X0N23062 X0N262 Times New Roman 7 X0N23072 X0N272

Size

Coded Font Name

Name (for chars Parameter)

Figure 19 (Page 2 of 2). Font Mapping Table for Use with the chars Parameter

Linked Short

Point

Type Family

Times New Roman 8 X0N23082 X0N282 Times New Roman 9 X0N23092 X0N292 Times New Roman 10 X0N23002 X0N202 Times New Roman 11 X0N230A2 X0N2A2 Times New Roman 12 X0N230B2 X0N2B2 Times New Roman 14 X0N230D2 X0N2D2 Times New Roman 16 X0N230F2 X0N2F2 Times New Roman 18 X0N230H2 X0N2H2 Times New Roman 20 X0N230J2 X0N2J2 Times New Roman 24 X0N230N2 X0N2N2 Times New Roman 30 X0N230T2 X0N2T2 Times New Roman 36 X0N230Z2 X0N2Z2

Size

Coded Font Name

Name (for chars Parameter)

| If you are using an IBM 3800 printer, which needs fonts in the unbounded box | format, you can use the FONTECH parameter. The only valid value for FONTECH | is UNBOUNDED; any other value will cause ACIF to issue an error message and | terminate.

| If you specify FONTECH=UNBOUNDED and RESTYPE=FONT or RESTYPE=ALL, | ACIF reads unbounded box fonts and saves them in the resource object data set. | However, the unbounded box fonts are not syntax checked. If there are errors in | the AFPDS making up the font, ACIF will not issue an error message.

| Note: The FONTECH parameter must be used with caution. Unbounded fonts are | supported only by the IBM 3800 printer. They are not supported by any | other printer or the Viewer. Any resource object file archived will have very | limited use. Unbounded box fonts cannot be used by PSF for AIX or by | InfoPrint Manager for AIX.

78 ACIF User’s Guide

Part 3. Using ACIF in the OS/390, MVS, VM, and VSE

Environments

80 ACIF User’s Guide

IBM S544-5285-01 User Manual

Specifications and Main Features

Frequently Asked Questions

User Manual