doc1 suite 4 programmer’s guide - pitney bowes · 11 preface this programmer’s guide describes...

DOC1 Suite 4

Programmer’s Guide

Issue 7d

®

2

Copyright ©2008 Group 1 Software Europe Ltd. All rights reserved.

This publication and the software described in it is supplied under license and may only be used or copied in accordance with the terms of such license. The information in this publication is provided for information only, is subject to change without notice, and should not be construed as a commitment by Group 1 Software. To the fullest extent permitted by applicable laws Group 1 Software excludes all warranties, representations and undertakings (express or implied) in relation to this publication and assumes no liability or responsibility for any errors or inaccuracies that may appear in this publication and shall not be liable for loss or damage of any kind arising from its use.

Except as permitted by such license, reproduction of any part of this publication by mechanical, electronic, recording means or otherwise, including fax transmission, without the express permission of Group 1 Software is prohibited to the fullest extent permitted by applicable laws.

Nothing in this notice shall limit or exclude Group 1 Software's liability in respect of fraud or for death or personal injury arising from its negligence. Statutory rights of the user, if any, are unaffected.

*TALO Hyphenators and Spellers are used. Developed by TALO B.V., Bussum, NetherlandsCopyright © 1998 *TALO B.V., Bussum, NL*TALO is a registered trademark ®

Encryption algorithms licensed from Unisys Corp. under U.S. Patent No. 4,558,302 and foreign counterparts.

Security algorithms Copyright ©1991-1992 RSA Data Security Inc.

Base 14 fonts and derivationsCopyright 1981 - 1983, 1989, 1993 Heidelberger Druckmaschinen AG.All rights reserved.

Maxicode encoding, Datamatrix and PDF417 encoding, fonts and derivationsCopyright (c) 1999, 2000, 2003 DL Technology Ltd.All rights reserved

Linear barcode fonts Copyright © 1997 Terrapin Solutions Ltd. with NRB Systems Ltd.

This product includes software developed by the Apache Software Foundation (http://www.apache.org/).

Otherwise all product names are trademarks or registered trademarks of their respective holders.

Printed in the UK.

Contents

PREFACE ................................................................................................................11

Typographical conventions .................................................................................................11

File naming conventions .....................................................................................................12

Updates to this manual .......................................................................................................12

PROGRAMMING PCE ...............................................................................................13

Concepts and Command Overview ......................................................................... 14

Procedures and Program control .........................................................................................14

Variables, Data Types and Arrays .......................................................................................14

File Handling .....................................................................................................................15

Reading and Writing ..........................................................................................................16

Journal Files .......................................................................................................................17DIJ indexes and the Document Repository ...................................................................18

Data Manipulation .............................................................................................................18

Changing Composed Pages .................................................................................................19

Error Handling and Environment Information .....................................................................20

Document Groups ..............................................................................................................20

Support for AFPDS Indexing ..............................................................................................21

User Exits ...........................................................................................................................22

Command File Reference ..................................................................................... 23General ........................................................................................................................23Variables and Arrays ....................................................................................................23Literals ........................................................................................................................23File Names ..................................................................................................................24Comments ...................................................................................................................25

Conventions .......................................................................................................................26add DJDE ....................................................................................................................27add document id ..........................................................................................................27add document name .....................................................................................................28add document TLE ......................................................................................................28add medium map .........................................................................................................29

Contents 3

add TLE ......................................................................................................................29begin ce ........................................................................................................................30begin loop ....................................................................................................................31begin procedure ............................................................................................................31call procedure ...............................................................................................................32change DIJelement .......................................................................................................32close ............................................................................................................................33declare procedure .........................................................................................................33declare (variable) ..........................................................................................................34end ce ..........................................................................................................................34end loop .......................................................................................................................35end procedure ..............................................................................................................35exit loop .......................................................................................................................35extract document page ..................................................................................................36for…next ......................................................................................................................36if…else…end if .............................................................................................................37insert object ..................................................................................................................37let … barcode ...............................................................................................................38let (boolean evaluation) ................................................................................................39let … call userexit .........................................................................................................40let … DIJelement .........................................................................................................40let … document id ........................................................................................................41let … document name ...................................................................................................41let … document TLE ....................................................................................................42let (environment values) ................................................................................................42let (number functions) ...................................................................................................44let … page count ..........................................................................................................44let (text functions) .........................................................................................................45let … TLE … ...............................................................................................................48let (variable copy) .........................................................................................................49merge ...........................................................................................................................49move ............................................................................................................................50move page ....................................................................................................................51on error call ..................................................................................................................51open .............................................................................................................................53overwrite ......................................................................................................................56quit ..............................................................................................................................57read .............................................................................................................................57read … DIJentry ...........................................................................................................59read … document .........................................................................................................59

4 Contents

replace .........................................................................................................................60return ...........................................................................................................................60set page name ...............................................................................................................61TLE .............................................................................................................................61trace .............................................................................................................................63translate .......................................................................................................................63write ............................................................................................................................63write DIJentry ..............................................................................................................64write document ............................................................................................................65

Composition Edit Commands ................................................................................ 66

Print Positioning Concepts ..................................................................................................66

Printer Resource References ................................................................................................67Fonts referenced by index .............................................................................................67

Order of Commands ...........................................................................................................68

Command Structure ...........................................................................................................68COLR – Set Color ........................................................................................................69DBX – Draw Box .........................................................................................................69DIL – Define Image List ...............................................................................................70DHR – Draw Horizontal Rule ......................................................................................70DPOL – Define Overlay List ........................................................................................70DVR – Draw Vertical Rule ...........................................................................................71PBIM – Place Barcode – Intelligent Mail .......................................................................71PI – Place Image ..........................................................................................................72PPO – Place Page Overlay ............................................................................................72SBT – Set Boxed Text ...................................................................................................73SBTR – Set Boxed Text Right Justified .........................................................................73SCPP – Set Current Print Position ................................................................................74SPPS – Set Physical Page Size ......................................................................................75STL – Set Text Line .....................................................................................................75STP – Set Text Presentation ..........................................................................................76

Control File Sample ............................................................................................ 77

HTML DEPLOYMENT ...............................................................................................79Groups and Identifiers ........................................................................................................80

Graphics handling ..............................................................................................................81Lines and boxes ............................................................................................................81Static images ................................................................................................................81DOC1 chart feature ......................................................................................................81

DOC1 HTML PAK file format ...........................................................................................83

Contents 5

WORKSTATION UTILITIES ........................................................................................ 85

RTF2LDO – import RTF ......................................................................................85Restrictions ..................................................................................................................86

RTF2LDO control script format ..........................................................................................87

RTF2LDO Font Equivalents file format ..............................................................................92

RTF2LDO under Windows and Unix .................................................................................93

LOL2LDO – deconstructs document object library ......................................................94Output File Names .......................................................................................................94

LOL2LDO under Windows ................................................................................................95

Other Utilities ...................................................................................................96

MAKEBMP – converts images to bitmaps ...........................................................................96

DOC1GFC – Changing font references globally ...................................................................97

DOC1GLC – changes language attributes globally ...............................................................99

MERGELAR – merges multiple application rules ..............................................................101

PREVIEW API ....................................................................................................... 103

Environment ....................................................................................................................103Required Software Products ........................................................................................104DOC1 Resources ........................................................................................................104

About DOC1 Documents and Preview ..............................................................................104

General Principles and Function Overview ............................................................. 106

Initialization .....................................................................................................................106

Creating Preview Objects ..................................................................................................106

Associating control Files ...................................................................................................106

Generating Composed Output ...........................................................................................107

Identifying Required Pages ................................................................................................107

Creating a Preview Window ..............................................................................................108

Displaying Pages ..............................................................................................................108

Proof Printing ...................................................................................................................108

Debugging ........................................................................................................................109

Unloading Objects and Terminating API Services ..............................................................109

Function Return Codes .....................................................................................................109

Function Reference ........................................................................................... 110

Return Codes .................................................................................................. 126

6 Contents

Notification Codes ............................................................................................127

Types and Data Structures ...................................................................................129

CODING A CHARACTER LAYOUT FILE ....................................................................133

Location and Naming Convention .............................................................................. 133

Character Layout File format ............................................................................................ 134

INTEGRATING WITH THIRD PARTY PRODUCTS ..........................................................137

EDINAT©/DOC1 Production Bridge ....................................................................138

The DOC1 Upload Service ............................................................................................... 139Installing ....................................................................................................................139Running the Service ................................................................................................... 142

The DOC1 Port Monitor .................................................................................................. 142Port Monitor installation for Windows NT ................................................................. 143Port Monitor installation for Windows 2000 & XP ...................................................... 144

Preparing the EDINAT output on the host system ............................................................. 146

READYEDI under OS/390 .............................................................................................. 147

READYEDI under OS/400 .............................................................................................. 149

READYEDI under UNIX and OpenVMS ......................................................................... 150

READYEDI under Windows, OS/2 and DOS .................................................................. 151

Sharing application data ......................................................................................152

XML output ..................................................................................................................... 152

Reformat Initialization File format .................................................................................... 153

Running DOC1RFMT under UNIX, OpenVMS, OS/2, Windows and DOS ..................... 156

Running DOC1RFMT under OS/400 ............................................................................... 157

Running DOC1RFMT under OS/390 ............................................................................... 158

MAKEEDF – Windows only ............................................................................................ 159

Generating an OTS Finishing line .........................................................................160Available Finishing Lines ........................................................................................... 160Summary Pages .......................................................................................................... 161Address Block ............................................................................................................ 161OTS CASSing ............................................................................................................ 161Document Layouts ..................................................................................................... 162Finishing line information fields ................................................................................. 162Parallel Support .......................................................................................................... 163FormDefs .................................................................................................................. 163

Contents 7

OTS Records ....................................................................................................................164File Header ................................................................................................................165Address2 Information .................................................................................................166Postal Information NOP/PTX ....................................................................................167Zip Code NOP/PTX ..................................................................................................167Statement Trailer ........................................................................................................168

USER EXITS ......................................................................................................... 171

Summary of Requirements .........................................................................................171

Types and purpose of user exits ............................................................................ 173

Instruction type .................................................................................................................173

Data_Input type ................................................................................................................173

Printstream type ................................................................................................................173AFPDS ......................................................................................................................174PostScript and PDF ....................................................................................................174Metacode ...................................................................................................................174

User exit object header ......................................................................................................175

Preparing DOC1 applications for user exits ............................................................. 176

EMFE applications ...........................................................................................................176

PCE applications ..............................................................................................................177

User Exit control file format ..............................................................................................178

Creating the user program ................................................................................... 180

About memory cells ..........................................................................................................180

Initiation ..........................................................................................................................181

Program calls and data exchange .......................................................................................181

Invocation modes .............................................................................................................182

Return Data ......................................................................................................................183

Structures used with program calls .....................................................................................184

InvocationMode ...............................................................................................................184

ApiData ...........................................................................................................................184

EmfeInputData .................................................................................................................185

ReturnStatus .....................................................................................................................185

Compiling & linking .........................................................................................................186Windows & OS/2 ......................................................................................................186UNIX ........................................................................................................................186

8 Contents

OS/390 ...................................................................................................................... 186OS/400 ...................................................................................................................... 187

Run-time requirements ..................................................................................................... 187

User Exit Data Exchange API ...............................................................................188

C Functions ...................................................................................................................... 189

C Definitions .................................................................................................................... 191

Cobol Functions ...............................................................................................................192

Cobol Definitions .............................................................................................................196

User program examples .......................................................................................197

C Example ....................................................................................................................... 197

Cobol Example .................................................................................................................199

INDEX ..................................................................................................................203

Contents 9

10 Contents

Preface

This Programmer’s Guide describes the requirements of features in the DOC1 environment that require customizing at the programmer level.

PCE Programming Full information is provided regarding programming PCE using the control File language. Note that information about executing a PCE application and details of the PCE run-time environment can be found in the Production Guide.

Workstation utilities Some manipulation of file used by the DOC1 Workstation can be performed using a range of batch utilities.

Preview API This API allows a user program to access the features of the ALE Preview facility, i.e. to sample an application on the workstation.

Character Layout Files These files allow you to customize the layout of the Characters dialog that is used when selecting special characters for a Text element in DOE.

Third party product integration Details of interfaces between DOC1 and partner products. The EDINAT/DOC1 production bridge allows AFP documents generated by the EDINAT product to be printed and post-processed using DOC1 production features.The Reformat utility converts a DOC1 data format and associated application data file to an independent format to allow data sharing.

User Exits User Exits are used to invoke user–defined programs during processing of a EMFE or PCE application. Typically a user exit will perform functions which are outside the scope of DOC1 features as externalized in the ALE or the PCE control File language.

If you have not already read the DOC1 Overview and specific topics in other User Guides that may affect these features, we recommend that you do so first.

Typographical conventionsThe following are used throughout this manual.

[...] parameters between square brackets are optional.

{ opt1 | opt2 } parameters between curly braces represent a list of options, one of which must be chosen.

Text in italics represents parameter data which should be replaced with customized values.

UPPER CASE text represents constant command text which should be typed exactly as written.

• space character (used only if spaces are not apparent).

11

File naming conventionsThe following conventions are expected whenever you need to specify file names in the DOC1 environment.

OS/390All files are referenced by Data Definition (DD) labels with actual datasets being assigned to these labels in start-up JCL. Example:

OS/400Files are referenced by the libname/filename(member) convention. The Library specification can be omitted if it is in the *LIBL list. Example:

Windows, OS/2 or DOSFiles are referenced by path (optional) and filename. If a path name is not specified EMFE will search the current directory (from which EMFE was started) for the filename. Example:

UNIXFiles are referenced by path (optional) and filename. If a path name is not specified EMFE will search the current directory (from which EMFE was started) for the filename. Example:

OpenVMSFiles are referenced by path (optional) and filename. If a path name is not specified EMFE will search the current path (from which EMFE was started) for the filename. Example:

Updates to this manualThis manual may be reissued in electronic format from time to time to include corrections that have been made since the original hard copy publication. Such changes are indicated by change bars in the left margin next to the amended material.

Rules=DD:EMFERULE

Rules=DOC1HOST/EMFERULE(APPLIC1)

Rules=C:\DOC1HOST\EMFERULE\APPLIC1.EAR

Rules=/doc1host/emferule/applic1.ear

Rules=[doc1host.emferule]applic1.ear

12 Preface

Programming PCE

The DOC1 Post Composition Engine (PCE) handles the requirements of some applications for additional processing once a printstream has been generated by EMFE. PCE can perform such functions as selecting specific pages for output, reordering, merging and adding additional items to a composed page. PCE supports the manipulation of printstreams in the AFPDS, Xerox Metacode, VPS or PostScript formats produced by EMFE.

The primary input to a PCE process is normally one or more output datastreams previously generated by EMFE. These can be processed on a page-by-page basis or you can use journal files to act as an index into the specific pages to be manipulated. Such journals will have been created by EMFE at the same time as the associated printstream if the appropriate commands were used in the application design.

SEE THE DESIGNER’S GUIDE FOR INFORMATION ABOUT SETTING UP YOUR APPLICATION TO CREATE JOURNALS. THE PRODUCTION GUIDE CONTAINS DETAILS OF HOW THE ACTUAL JOURNAL FILES ARE CREATED ON THE HOST SYSTEM.

PCE can read output datastream records stored in unstructured (‘flat’) files or, on OS/390 systems, as VSAM relative record datasets (RRDS). When using the latter option, each RRDS record contains the data required to compose a single printed page. Note: indexed access of datastreams stored as RRDS normally requires the presence of vector file offsets in the appropriate journal files so that the required pages can be located.

The governor of all PCE processes is an external control file that specifies the input/output files required for a particular PCE process, the pages to be selected, any additional formatting required and any output batching to be carried out. The control file language is pseudo program code which allows page selection and manipulation to be comprehensive and flexible.

13

Concepts and Command OverviewFor every PCE process you want to define you will need to create a control file that contains the required commands. The control file language is a set of pseudo programming commands with predetermined function/statement identifiers such as OPEN, WRITE and LET. The syntax of the various statements consist of fixed format sub-operands, file identifiers plus variable names and literal expressions.

Procedures and Program controlTo avoid repetition, statements can be grouped into procedures. All control files must have at least one procedure known as "Main" and this will be assumed to be the first procedure if it is not explicitly defined. You must use the declare command to identify all procedures (including Main) before using any procedural statements.

The start of a procedure is identified by a begin procedure command. All statements from this command up till the next end procedure command are considered to be part of the procedure.

A procedure can invoke a lower level procedure via the call procedure command. Procedures cannot be called recursively, i.e. they cannot call themselves or a higher level procedure.

If required, the return command in a procedure can immediately pass control back to the statement following the appropriate call procedure command. Note that end procedure implicitly performs the same function.

Loops

Standard program repeat features are available via begin loop/end loop/exit loop and for.../next constructs.

Conditions

Conditions can be tested via the let (boolean) command and subsequent program branching achieved via the if...else.../end if construct.

Variables, Data Types and ArraysAs with all programming languages, a PCE variable is an item of data retained in computer memory until it is required. As with procedures, all variables to be used during processing must be declared before any procedural statements. The declare command simply assigns valid names for use by the process.

14 Programming PCE

Up to 1900 variables can be used by a single PCE process. However, when specifying array variables, bear in mind that each array element accounts for a variable allocation.

All variables must be declared before any procedural statements and all declared names have global effect. This means that any changes to the contents assigned to a variable have effect across all procedures.

Values stored in variables can be copied by using the let (copy) command.

Data types

When you first declare a variable it is assumed to be a number. If any data is read into a variable from a file it is then assumed to be a text string. You may need to use the let...(text functions) or let (number functions) commands to convert types where appropriate

Arrays

You can define arrays of variables to store multiple examples of the same data type. You may, for instance, want to store multiple pages of print datastream under the same name but be able to manipulate them independently.

Symbols

Symbols that have been defined in the Initialization file, or on the start-up command line can be accessed by the PCE script file by using the symbol variant of the let (text functions) command.

Memory requirements

The amount of memory required to store variables is self-defined by the data assigned to them. However, PCE does not perform memory checking and you should therefore be aware of the amount of data your control file requires to be held in memory at any one time and ensure that your system has sufficient resources to cope. For instance, the print datastream that makes up a printed page can require a significant amount of memory. Obviously holding many pages in memory at any one time can result in a large overhead on available system resources.

File HandlingFiles used by a typical PCE process consist of the existing print datastream files that are to be processed, any journal files that are related to the datastreams, and output files to receive the reorganized print datastreams or other information. Note: PCE can open files for read or write functions but not both simultaneously.

Concepts and Command Overview 15

Files used by a PCE process are referenced by a unique ID which is specified as part of the open command in the control file. The open command also identifies the names of files to be used and their type.

Defining File Types

The two type parameters are crucial to correct processing by PCE. The first parameter defines the record construct of the file and the second specifies its content, i.e. what type of printstream or other data it contains and therefore how much data should be handled each time a read or write command is performed. For instance, an AFPDS file on an OS/390 system should be opened as type "record/AFPDS" but will normally be type "line/AFPDS" under NT or UNIX.

There are predefined record construct types to support datastreams stored as VSAM RRDS files under OS/390. Other specialist file types can be defined via the format parameter.

The content type has predefined definitions for files containing AFPDS, Metacode, VPS and PostScript. The delimited content type is used to read non-printstream files that have multiple fields in each record and store them separately. The delimiter itself is the character that is used to separate the various fields. Journal files that contain multiple references to a page or document will often need to be opened as type delimited.

Block and Record Headers

Where a print datastream file has been defined as having additional block or record header data, this will be stripped from the file before the ‘pages’ of data are processed. If data from such file types is written out to different files, block and/or record header structures will only be applied to the new file if they are explicitly defined as part of the format parameter in the appropriate open command, or if the default format for the file type automatically applies such headers. Note: block and record headers should not be confused with document headers which are discussed below.

A specific close command is available which closes the appropriate file immediately while processing continues. However, an automatic close of all files will be performed at the end of any PCE process. In addition, an open file with an ID that is specified as part of a further open command will also be automatically closed.

Reading and WritingAs indicated above, the amount of data handled by the read or write command depends on how it has been opened. For instance, an ‘item’ of data from a file that has been opened as AFPDS or Metacode consists of all structured fields that make up a printable page. For a delimited journal file an item will be a single field from the current record.

16 Programming PCE

A read command specifies the number of items to be read and a variable to contain the results of the function. Each time the read is performed all data required to make up the required number of items is stored in that variable. If more than one item is specified and the variable has been declared as an array, each item will be stored in an individual array element. If not, multiple items will be concatenated together.

Similarly the write command copies items from a variable to an output file. Note that multiple items can only be written by a single write command if the variable has been specified as an array.

File Pointers and Offsets

Every file has a pointer that indicates the place in the data where the next read or write operation will commence. Every time a read or write is performed the appropriate file pointer is updated.

When you are reading from file you can specify a specific file offset at which the read should start.

When you are writing print datastream output you can use the file offset values available as part of the let (environment values) command to get the current file position offset. This is particularly useful if you are updating print datastream ‘pages’ and need to be aware of new offsets as the pages are written back to file.

Document Headers

Print datastreams can have information stored before the start of structured data that makes up printable pages. For the purposes of this guide this is known as the document header. The supported printer protocols have different document header structures. The document header data for a particular protocol is automatically read into memory the first time a read is performed against a specified file that has been opened as that type. This will be used to initialize all output file when PCE is creating print datastreams of the appropriate type. If your application is manipulating different types of print protocol, multiple document headers are retained.

Journal FilesWhen your application has a known post-processing requirement it is usual to specify one or more journal files as part of the application design. Journals are typically used to provide an index for the documents and pages within composed datastreams and can be used to allow you to locate particular parts of the output that need further processing. If you include a vector environment variable within the journal you can use this to move the file pointer associated with a datastream to a particular document/page without the need to read all intervening data.


If you are amending a datastream in any way using PCE you will normally want to create a new journal so that you have an up-to-date index.

DIJ indexes and the Document Repository

If your output datastream is intended to be stored in a Document Repository for use with the DOC1 Archive, DOC1 Present or DOC1 Pay products the application should always generate a specialized index known as a DOC1 Interchange Journal (DIJ). A DIJ is an XML journal which has a fixed structure with a predefined set of elements pertaining to the documents within the datastream. A DIJ always contains one entry for each document in the datastream with which it is associated.

Such files must be opened as type DIJ so that PCE knows how to handle their XML structure. You must use the read… DIJelement and write DIJelement command when performing IO with DIJ files. You may only read and write a single DIJ entry at a time.

The let… DIJelement command allows you to read the values stored within a DIJ element. If required, you can use the change DIJelement command to update these values.

Documents that are referenced by a DIJ always have a unique identifier stored within the first page which is used for integrity checking when the relevant datastream is loaded into the Document Repository. If your PCE script has cause to remove or reorder the position of pages within a document you may need to use the add document id command to ensure that page 1 of each document has a valid identifier. The let ... document id command enables you to read the identifier from a page if required.

Data ManipulationThe majority of data manipulation functions are carried out by the string and numeric manifestations of the let command.

Numbers

The let (number functions) group of commands allows a variable to receive the results of a variety of calculations and conversions.

Text

The let (text) group of commands manipulates and formats text strings according to a range of parameters. This includes numeric data which can be converted to a string and formatted with decimal places and padding via the string operand.

18 Programming PCE

DBCS Text

The let (text) command also supports the creation of Double Byte Character Set (DBCS) text strings via a hex encoding format.

Barcodes

The let...barcode... command translates a text string into one of a number of supported barcode types.

Character Translation

The translate command uses the DOC1 Translation Tables file to convert a text string to the specified format.

Changing Composed PagesAlthough PCE handles composed print datastream pages’ as a whole, some restricted editing of this data is possible. For example it is possible to add print items to a page and also to adjust/amend existing items depending on their type.

Text strings within composed pages can be amended via the overwrite or replace commands.

The merge command can be used to generate a single composite page from the printable items from two composed pages. The move command will offset all printable items on a composed page by the defined values.

Adding New Elements

The begin ce/end ce command construct is used to add entirely new elements to existing pages. Commands within this construct are known as Composition edit (CE) commands and, for greatest efficiency when manipulating the actual print datastream protocol, are defined at a lower level than regular PCE commands. As a result, CE commands have a different general format from regular PCE commands and also mean that care must be taken to ensure that the sequence of such commands is correct. The format of CE commands is fully discussed in “Composition Edit Commands” on page 66 at the end of this section.

Printer controls

The add medium map command can be used to include an AFPDS Invoke Medium Map structured field to an existing ‘page’ of AFP print datastream.

The add DJDE can be used to include a Xerox DJDE command (with user defined format) to an existing ‘page’ of Metacode datastream.


For PostScript output files you can use the set page name command to add a page name to the output being generated.

Error Handling and Environment InformationSyntax errors in the control file and inconsistencies between the control File specifications and actual data will result in an immediate termination of the PCE process. The appropriate messages are issued to the Trace and Log files as usual.

For errors relating to IO functions you can control the actions to be taken by evaluating error codes. The codes are generated by errors encountered during the processing of the open, close, read, write, replace and overwrite commands. The on error call function allows you to specify a procedure in the current control File that will be called whenever such a problem is encountered. To be effective this procedure should query the nature of the error and have logic to deal with each anticipated error. If on error call is not coded, PCE will terminate and issue a generic error message on encountering an IO error.

You can also specify a customized value to be assigned to the return code issued on completion of a PCE process via the predefined variable name <sys_exit_value>. The value can be assigned via the let (number) command and must be a number in the range 0-999.

For errors or any other type of information you can query a range of environment value including the current system date and time via the let...(environment values) command.

Document GroupsIf required, you can create temporary groups of pages (known as ‘document groups’) that can be manipulated as a whole. You will need to do this if you intend to create group level AFP indexes (see below). Document groups are created by reading one or more ‘pages’ into a document group structure via the read ... document command and are given a name with add document name. When you use the write document command to write the grouped pages to an output file, the datastream records making up the pages plus any required grouping records are stored.

PCE document groups are not related to the documents created by EMFE. Therefore, if for example your EMFE application has created a five page ‘document’ in the appropriate print datastream, you will need to read those same five pages into a PCE document group structure before they can be manipulated as a whole.

20 Programming PCE

Important: document groups are not currently supported for Xerox Metacode datastreams and the use of document group commands with this protocol is unpredictable.

Support for AFPDS IndexingSeveral commands allow the reading, writing and manipulating of AFPDS Tag Logical Element (TLE) structured fields. TLE’s are part of the indexing feature used with the AFPDS architecture and are structured fields which are assigned a name and a value by which document elements can be referenced and located by appropriate software.

TLEs can be used either at the page or document level. When working with document level TLEs you should normally read the pages of a document into a PCE document group structure. This will ensure that the document header in which document level TLEs are normally stored is included. You can have any number of TLEs in a page or a document.

Page level TLEs

To read existing page level TLEs use the let...TLE... command. To manipulate TLEs or create new ones use the TLE command. IMPORTANT: the TLE command is only supported in PCE after version 4.3. In earlier versions the the add TLE command can be used to create new indexes but deleting and replacing is not supported.

Group level TLEs

Before you can use any command related to document level TLEs you must first read the appropriate pages into a PCE document group (see “Document Groups” on page 20 above).

To read existing document level TLEs use the let...document TLE command. To manipulate TLEs or create new ones use the TLE command. IMPORTANT: the TLE command is only supported in PCE after version 4.3. In earlier versions the the add document TLE command can be used to create new indexes but deleting and replacing is not supported.

When the write document command is used the records that make up the appropriate pages plus the group level TLEs are enclosed within start-end named group structured fields.

If required you can also extract or add pages from/to an existing document group by using the extract document page and move page commands. You may want to do this if you need to work with page level TLE’s in the AFP pages that make up the group.

Note: it is assumed that there is enough memory available to PCE to read in all the pages in the page group. If not, the results will be unpredictable.


User ExitsUser exits functions are initiated via the let ... call userexit command.

User exits of type INSTRUCTION call an external user-defined program function and, optionally, provide a value that can provide input to the PCE script.

User exits of type PRINTSTREAM are intended to return a self-contained segment of output datastream. You can use the insert object command to merge such segments into existing pages.

User exits of type DATA_INPUT are not supported for PCE.

For details of setting up user exits refer to page 171 of this guide.

22 Programming PCE

Command File Reference

General

All statements are independent and compound statements are not allowed. Thus statements cannot include or be concatenated with other statements.

Every statement must be terminated by a semicolon.

If necessary statements may span multiple lines.

Commands may be written in UPPER or lower case or a MIXture of the two.

Leading and trailing blanks are always ignored including those used in multiple line statements.

Variables and Arrays

All variables must be pre-declared. Variables are identified by token names enclosed in chevrons. For example:

<PageOfPrintData>

All standard keyboard characters are valid for use as part of the token name except the space character. Names can be any reasonable length but note that the total length of any statement including all token names cannot exceed 999 characters.

The data type and required storage for all variables is defined implicitly by the contents assigned to them and/or the statement used for the assignment. No explicit definition is required.

To specify that a variable is an array or to reference a specific array element, add the required number immediately following the variable name enclosed in parenthesis:

<PagesOfPrintData>(10)

When using a variable array element (as distinct from declaring it) you can also specify the element number as another variable:

<PagesOfPrintData>(<NumberOfPages>)

Literals

Wherever a variable can be used in the control file you can alternatively specify literal contents. For numbers you type the value required without modification. For instance:

let <Var1> = 2;

Command File Reference 23

For text strings you must enclose the characters in single or double quotation marks. Examples:

let <Var2> = ‘Text String’;let <Var3> = "Text String";

For text strings that include single or double quotation marks you must enclose the string within quotation marks of the opposite kind. Examples:

let <Var4> = "Text containing ‘single quotes’";let <Var5> = ‘Text containing "double quotes"’;

If a string needs to include both types of quotation mark you will need to repeat the quote characters for one of the types. Examples:

let <Var6> = "Contains ‘single quotes’ and ""double quotes""";let <Var7> = ‘Contains ‘‘single quotes’’ and "double quotes"’;

Similarly, semicolons within text strings must appear twice, thus:

let <Var8> = "Text containing semi-colon;;";

For hex characters you must specify a text representation of the actual hex value required. An example of the required format is:

let <Var9> = X‘F6,E8,F9,40’;

File Names

When you use the open command you will need to code file names in the format suitable for the host environment on which PCE will execute. File names are text strings and thus must be enclosed in double quotes as described above.

OS/390 You can either specify fully qualified dataset names or reference datasets by Data Definition (DD) labels with actual files being assigned to these labels in PCE start-up JCL. Note that PCE does not provide a mechanism for specifying dataset attributes so where open to a new output file is specified a DD reference should normally be used so that the relevant attributes can be specified in the JCL. Example:

open "DD:AFPDS1"...open "USER1.PCE.INPUT"...

OS/400 Files are referenced by the libname/filename(member) convention. Example:

open "DOC1HOST/PCEINPUT(AFPDS1)"...

The Library specification can be omitted if it is in the *LIBL list.

OS/2, Windows or DOS Under OS/2 or DOS, files are referenced by path (optional) and filename. Example:

open "C:\DOC1HOST\PCEIN\AFPDS1.OUT"...

24 Programming PCE

UNIX Under all supported UNIX systems, files are referenced by path (optional) and filename. Example:

open "/doc1host/pcein/afpds1.out"...

OpenVMS Under OpenVMS, files are referenced by path (optional) and filename. Example:

open "[doc1host.pcein]afpds1.out"

Comments

Comments can appear anywhere in the control file except embedded within a command.

The start of a comment is indicated by a double slash (‘//’) positioned anywhere on a line after a statement:

declare <PageOfPrintData>[5]; // Holds 5 pages of data

or instead of a statement:

// The following holds 5 pages of print data in memorydeclare <PageOfPrintData>[5];

Alternatively entire lines may be commented by commencing with an asterisk in column 1:

* The following holds 5 pages of print data in memorydeclare <PageOfPrintData>[5];


ConventionsVariables <Variable> Text within chevrons indicates a variable.

<Variable> Where a variable is underlined you can use either a variable name or type literal contents in the format of the required data type (see “Literals” on page 23).

Literal Where chevrons are not used you must type literal contents.

Data Types Text in italics represents variable data types. The first three letters used for the name represents the type of data expected:

<doc...> contains one or more print datastream ‘pages’ (see pag... below) in a document group structure.

<hex...> contains hex data, i.e. a text representation of one or more hex values such as "F6".

<iod...> contains I/O data, i.e. data of any supported type that is to be read to/written from file.

<num...> contains a number, i.e. a signed integer value.

<pag...> contains print datastream ‘pages’, i.e. the data required to generate one or more complete ‘pages’ on the appropriate printer type.

<str...> contains a text string.

<var...> can contain variable data of more than one type.

<xml...> contains a record from an XML file with a supported schema.

Multi-choice Parameters Parameters between curly braces {...} indicate that one should be selected from the available options which are separated by the ‘or’ delimiter – ‘|’. For instance:

let boo1 = num1 {lt|le|gt|ge|eq|ne} num2

Indicates that you may type either ‘lt’, ‘le’, ‘gt’, ‘ge’, ‘eq’ or ‘ne’ as the comparison operator.

Optional Parameters Optional parameters or groups of parameters are set between square brackets […].

26 Programming PCE

add DJDE

Function Adds a Xerox DJDE command to a Metacode page or file header.

Syntax add DJDE <strDjde> to { start | end } of{ <pagExistingPage> | header <numFileRef> };

Effects <strDjdeName> is inserted into the specified Metacode stream and is assumed to contain a valid DJDE command. You can add the DJDE either to a specific page in memory or to the header of an entire Metacode file.

Depending on the option chosen the DJDE will be placed either at the start or end of the commands that make up the page or header.

Comments For the file header option you must code the command after the file has been opened and at least one page has been read but before any pages are output.

The DJDE parameter format may need to include quotation marks. Refer to "Language Syntax Rules" above for formatting requirements.

Example ...open "DD:METAIN" for input as file 1 record/metacode;open "DD:METAOUT" for output as file 2 record/metacode;read 1 item from file 1 into <XeroxPage>;add DJDE "OTEXT 111" to start of header 2;add DJDE "OTEXT 999" to end of <XeroxPage>;write 1 item into file 2 from <XeroxPage>;

add document id

Function Adds (or changes) the DOC1 unique identifier that is assigned to the first page of documents intended for the Document Repository component.

Syntax add document id of <strID> to <pagExistingPage>;

Effects The identifier stored in <strID> will be inserted into the datastream page stored in <pagExistingPage>.

Comments <pagExistingPage> must be the first page of a document.

<strID> must contain a valid DOC1 identifier otherwise an error will be raised. The only method of getting a valid identifier string is to read one from an existing page using the let ... document id command.

Example ...//Skip page 1 (contains a separator)read 1 page from file 1 into <AFPPage>;let <DocId> = document id in <AFPPage>;read 1 page from file 1 into <AFPPage>;add document id of <DocId> into <AFPPage>;write 1 page into file 2 from <AFPPage>;


add document name

Function Adds (or changes) the name information for a document group.

Syntax add document name of <strName> to <docGroup>;

Effects The name <strName> will be inserted into the begin and end structured fields of the AFPDS page group stored as PCE document group <docGroup>.

Comments If the document group already has a name, then it will be changed.

Note that this command is only valid when working with AFPDS files with a page group structure. Using it with other file formats will cause unpredictable results.

Example See “add document TLE” on page 28

add document TLE

Function Adds (or changes) group level TLE information in the document group.

Syntax add document TLE of attrib <strName> value <strValue> [qualifier <numSeq>] to <docGroup>;

Effects An AFPDS TLE (Tag Logical Element) structured field will be inserted into the data that makes up the AFPDS page group stored as PCE document group <docGroup>. The TLE will be assigned an attribute name of <strName> and attribute value of <strValue>.

Optionally, you can also assign sequence and level numbers to the TLE via <numSeq>. The parameter expects a numeric value with a decimal point. The value to the left of the decimal point is treated as the sequence number and the value to the right becomes the level; e.g. 009.010 would produce a sequence number of 9 and a level of 10.

If a TLE record of the same name already exists, then it is replaced.

Comments You should refer to the IBM publication Mixed Object Document Content Architecture Reference (MODCA-P) for full technical details of the index construct. However, the parameters used above map to the components of the actual TLE structured field (using the terms as documented in the MODCA-P manual for TLE) as follows: Attribute Name is the Fully Qualified Name (X’0B’ Attribute Name) triplet; the Attribute Value is as described in the entry for TLE; Sequence Number and Level are parameters of the Attribute Qualifier triplet.

Note that this command is only valid when working with AFPDS files with a page group structure. Using it with other file formats will give unpredictable results.

In versions of PCE after 4.3 you may also perform this and other functions related to AFPDS indexing using the TLE command – refer to page 61.

Example // Open the I/O files (containing AFP data)open "DD:PCEIN" for input as file 1 record(8205)/afpds;open "DD:PCEOUT" for output as file 2 record(8205)/afpds;

28 Programming PCE

//// Read all the pages into the document grouplet <numberofpages> = 4;read <numberofpages> document from file 1 into <document1>;//// Assume that a successful read took place// Give the document group a name and add TLEs to itadd document name of "firstdoc" to <document1>;add document TLE of attrib "first_tle" value "Index1" to <document1>;add document TLE of attrib "another_tle" value "Index2" to <document1>;//// Write the document group back to file, thus creating the page group write document into file 2 from <document1>;

add medium map

Function Inserts an AFPDS Invoke Medium Map structured field into an existing AFPDS ‘page’.

Syntax add medium map <strMMName> to <pagExistingPage>;

Effects An AFPDS Invoke Medium Map structured field that invokes a medium map object with name <strMMName> will be inserted into the data that makes up the AFPDS ‘page’ stored in variable <pagExistingPage>.

Comments A medium map is a functional definition of an AFP form definition and is also known as a copy group. Refer to your IBM AFP related documentation for more information on the uses of medium maps.

When printing the AFPDS changed by this command, the medium map name used must be included in the form definition assigned to the print function (e.g. when printing via PSF on OS/390 you must specify the appropriate form definition in the JCL DD statement related to the output file).

Example ...open "DD:AFPIN" for input as file 1 record(8205)/AFPDS;open "DD:AFPOUT" for output as file 2 record/AFPDS;read 1 item from file 1 into <AFPPage>;let <MMName> = "MAP1";add medium map <MMName> to <AFPPage>;write 1 item into file 2 from <AFPPage>;

add TLE

Synopsis Inserts a TLE index structured field into an existing AFPDS ‘page’.

Syntax add TLE of attrib <strName> value <strValue> [qualifier <numSeq>] to <pagAFPData>;


Effects An AFPDS TLE (Tag Logical Element) structured field will be inserted into the data that makes up the AFPDS ‘page’ stored in variable <pagAFPData>. The TLE will be assigned an attribute name of <strName> and attribute value of <strValue>.

Optionally, you can also assign sequence and level numbers to the TLE via <numSeq>. The parameter expects a numeric value with a decimal point. The value to the left of the decimal point is treated as the sequence number and the value to the right becomes the level; e.g. 009.010 would produce a sequence number of 9 and a level of 10.

Comments You should refer to the IBM publication Mixed Object Document Content Architecture Reference (MODCA-P) for full technical details of the index construct. However, the parameters used above map to the components of the actual TLE structured field (using the terms as documented in the MODCA-P manual for TLE) as follows: Attribute Name is the Fully Qualified Name (X’0B’ Attribute Name) triplet; the Attribute Value is as described in the entry for TLE; Sequence Number and Level are parameters of the Attribute Qualifier triplet.

In versions of PCE after 4.3 you may also perform this and other functions related to AFPDS indexing using the TLE command – refer to page 61.

Example ... read 1 item from file <AFPInput> into <AFPPage>; read 2 items from file <ExternalTable> into <IndexRef>; add TLE of attrib <IndexRef>[0] value <IndexRef>[1] qualifier 123.456 to <AFPPage>; write 1 item into file <AFPOutput> from <AFPPage>; ...

begin ce

Function Indicates the start of one or more composition edit (CE) commands which are intended to add print elements to an existing ‘page’ of print datastream.

Syntax begin ce into <pagExistingPage>;

Effects All text between the begin ce and end ce statements will be interpreted as commands in the format required for DOC1 composition edit. The results of the CE commands will be merged into the existing ‘page’ of print datastream stored in variable <pagExistingPage>.

Comments The following CE commands are supported by PCE:DBX – Draw BoxDIL – Define Image ListDHR – Draw Horizontal RuleDPOL – Define Overlay ListDVR – Draw Vertical RulePI – Place ImagePPO – Place Page OverlaySBT – Set Boxed TextSBTR – Set Boxed Text Right JustifiedSCPP – Set Current Print PositionSTL – Set Text LineSTP – Set Text Presentation

30 Programming PCE

The “Composition Edit Commands” on page 66 that follows this section gives details of the syntax and function of the required commands. However, bear in mind the following general rules when generating the CE commands:• if you intend to call image or overlays via PI or PPO you must include a DIL command and/or

a DPO command as appropriate.• an SCPP must precede any command that places an element other than PI or PPO;• if an STL command is to follow the SCPP use an STP to set the required text orientation;• if you need to include a PCE variable in any command it must be prefixed with %@.

Example ...if <LastPage>; begin ce into <AFPDSPage>; =SCPP 001.500 002.500;; =STP 90;; =STL X0T055A0 This is the last page of %@<pagecount>;; end ce;end if;

begin loop

Function Used to indicate the start of one or more control file statements that are to be processed a variable number of times.

Syntax begin loop;

Effects Statements between the begin loop and end loop statements will be repeatedly executed until an exit loop statement is actioned.

Comments Loops can be nested but the user must ensure that the correct sequence of begin loop and end loop statements is maintained.

Example ...begin loop; read <n> items from file 1 into <input>; // Exit if less than 5 items read. let <done> = <n> ne 5; exit loop when <done>; ...end loop;

begin procedure

Function Used to indicate the start of one or more control file statements that make up a procedure.

Syntax begin procedure <strProcName>;

Effects All statements between this statement and the next end procedure statement are part of procedure <strProcName>.


Comments All control file procedures must be declared before use – see “declare procedure” on page 33. Note that if the ‘is main’ parameter is omitted from all procedures the first procedure in the control file is assumed to be main.

Example declare procedure <MainProc> is main;declare procedure <Proc1>;begin procedure <MainProc>; ... call procedure <Proc1>;end procedure;begin procedure <Proc1>; ... return;end procedure;

call procedure

Function Executes a procedure of control file statements.

Syntax call procedure <strProcName>;

Effects The procedure identified by <strProcName> will be executed.

Control will pass to the command following this statement on return from the called procedure.

Comments All control file procedures must be declared before use – see “declare procedure” on page 33.

Procedures cannot be called recursively i.e. they cannot call themselves or a higher level procedure. Note that if the ‘is main’ parameter is omitted from all procedures the first procedure in the control file is assumed to be main.

Example See “begin procedure” on page 31.

change DIJelement

Function Updates the value of an element of an entry in a DOC1 Interchange Journal (DIJ).

Syntax change DIJelement {Name|AddrLine1...AddrLine6|City|Region|PostalCode|Country|Phone|NumberOfPages|SkippedPages} value to <varValue> in <xmlRecord>;

Effects The named element within the DIJ record <xmlRecord> will be updated with the value contained in <varValue>.

Comments The file from which the record is taken must have been opened as type DIJ.There are 6 possible 'address line' elements.

32 Programming PCE

Example declare <dijrecord>declare <zip>declare <newzip>// Open the journalopen "C:\doc1\original\applic1.jrn" for input as file 1 line/DIJ;open "C:\doc1\new\applic1.jrn" for output as file 1 line/DIJ;read 1 item from file 1 into <dijrecord>;let <zip> = dijelement PostalCode in dijrecord;let <newzip> = call userexit <datahygiene> with <zip> in 9901;if <newzip> ne <zip> then change DIJelement PostalCode value to <newzip> in <dijrecord>end if;write 1 item into file 2 from <dijrecord>;

close

Function Explicitly closes a file during a PCE process.

Syntax close { input | output } <numFileRef>:

Effects The file previously opened with ID <numFileRef> is immediately closed. Processing continues.

If an error occurs a return code from this function will be stored as system value sys_last_error. This can be queried as part of a user defined error routine via the on error call function.

Comments Note that the specification of the input or output parameters is important in identifying the most efficient manner in which to close the file.

Open files are automatically closed at the end of any PCE process. In addition, an open file with an ID that is specified as part of a further open command will also be automatically closed.

Example ...on error call <IOErrorRoutine>...close input 1;close output <PassNo>;...

declare procedure

Function Used to declare a name to be used as a reference to a procedure within the control file.

Syntax declare procedure <strProcName> [is main];

Effects The string <strProcName> is to be used as the reference name for a procedure within the control file. Optionally the parameter ‘is main’ is added to the declaration to indicate that this is the main procedure of the control file.


Comments A procedure is any group of control file statements (including the main procedure) started by begin procedure and terminated by end procedure statements. All control file procedures must be declared before use.

The main procedure is always executed first by PCE. Note that if ‘is main’ is omitted from all procedure declarations the first procedure in the control file is assumed to be main.


declare (variable)

Function Used to declare a name to be used as a variable.

Syntax declare <strVarName> [(numArray)];

Effects The string <strVarName> is to be used as a variable name in the control file. Variables indicate a reserved area (address) of computer memory and can contain any data type and any amount of data.

You can optionally specify that the variable contains an array of numArray elements of the specified data type.

Comments Where an input file is delimited – i.e. has multiple fields, the boundaries of which are determined by a predefined character – the variable that is to receive the data from the file must have enough array elements to cater for the number of fields. This is typically a requirement for journal files. See “Command File Reference” on page 23 for details of file types.

Note that the number of array elements cannot itself be specified as a variable in a declaration. You must declare a fixed number of elements.

Example declare <count>; // Loop counter.declare <JournalData>(5); // Holds 5 journal records. ...

end ce

Function Used to indicate the end of one or more composition edit (CE) commands that are intended to add print features to an existing ‘page’ of print datastream.

Syntax end ce;

Effects All statements following end ce will be assumed to be PCE directives rather than CE commands.

Comments See “begin ce” on page 30.

Example See “begin ce” on page 30

34 Programming PCE

end loop

Function Used to indicate the end of statements processed by a loop.

Syntax end loop;

Effects Marks the end of loop statements started by begin loop. Note that for...next loops do not require an end loop statement.

Comments Loops can be nested but the user must ensure that the correct sequence of begin loop and end loop statements is maintained.

Example See “begin loop” on page 31.

end procedure

Function Used to indicate the end of one or more control file statements that make up a procedure.

Syntax end procedure;

Effects This marks the end of the procedure indicated by the previous begin procedure statement.

On encountering end procedure control will be passed back to the command following the relevant call procedure statement.

Comments Note that if a return statement is not encountered before an end procedure it is assumed.


exit loop

Function Terminates loop processing when a boolean condition is matched.

Syntax exit loop when <booTest>;

Effects Processing of a loop will be terminated immediately when variable <booTest> contains a value other than zero (i.e. a condition is matched).

Example ...let <count> = 0;begin loop; let <count> = <count> + 1; // Exit loop if more than 5 executions. let <done> = <count> GT 5;


exit loop when <done>; ...end loop;

extract document page

Function Extracts a page from the document group.

Syntax extract document page <pagNewPage> in <docGroup> at <strPosition>;

Effects The page stored at <strPosition> in the document group <docGroup> is moved into the variable <pagNewPage>.

Comments <strPosition> may be ‘Start’, ‘End’, or the page number of the page to be removed. If the page number is invalid, then no page is extracted.

The original page is completely removed from the document group <docGroup>. You can reinsert it into the document group via the move page command.


Example // Open the I/O files (containing AFP data)open "DD:PCEIN" for input as file 1 record(8205)/afpds;open "DD:PCEOUT" for output as file 2 record(8205)/afpds;//// Read all the pages into the document grouplet <pagecount> = 6;read <pagecount> document from file 1 into <document2>;...// Get the page from the document groupextract document page <page1> in <document2> at <Start>;...// Having worked on the page, move it back into the document group// & write the update document group back to filemove page <page1> to <document2> at <Start>;write document into file 2 from <document2>;

for…next

Function Used to indicate the start of one or more control file statements that are to be processed a fixed number of times.

Syntax for numLower to <numUpper>; ...next;

36 Programming PCE

Effects Statements between the for and next statements will be executed the number of times that is indicated by the difference between numLower and <numUpper>.

Comments NB.. for...next loops cannot be nested.

Example ...// Read field count (from first field)read 1 item from file 0 into <FieldCount>;// Write each field to new filefor 0 to <FieldCount>; read 1 item from file 0 into <JournalField>; write 1 item into file 1 from <JournalField>;next;

if…else…end if

Function Allows conditional execution of statements.

Syntax if <booTest>; ... [else; ...]end if;

Effects Statements between the if statement and else or end if statements (whichever appears first) will be executed if the variable <booTest> evaluates to true.

If <booTest> evaluates to false statements between the else and end if statements (if any) will be executed.

Comments if...else...end if constructs may be nested but the coder should ensure that the statements are balanced.

Example ...// Check current page countlet <Page1> = <Count> lt 1;// Over write text as appropriateif <Page1>; overwrite "type to replace" in <StartPage> with <HeadPage1>;else; overwrite "type to replace" in <StartPage> with <HeadPage2>;end if;

insert object

Function Adds a self-contained segment of output datastream to an existing page.


Syntax insert object <varObject> at [START|END] of page <pagExistingPage>;

Effects The contents of <varObject> are inserted into <pagExistingPage> either before existing data (START) or after existing data (END).

Comments The object to be inserted is normally provided by calling a user exit of type PRINTSTREAM. Only those objects supported by PRINTSTREAM user exits can be inserted using this command.

Refer to the “Types and purpose of user exits” on page 173 for details of the output datastreams supported and the required content of an object to be used in this context.

Example ...read 1 page from file 0 into <AfpPage>;let <Image> = "Image1";let <UXResult> = call userexit <GetImage> with <Image> in 9901;insert object <UXResult> at start of page <currentpage>;

let … barcode

Function Converts a string to a format suitable for printing as a barcode.

Syntax let <strBarcode> = barcode {PostNet|2of5|3of9|Code128A|Code128B|Code128C}using <strInput>;

Effects The string stored as <strInput> will be converted to a new string stored as <strBarcode> that will produce an equivalent barcode image of the specified type when printed using an appropriate barcode font. Standard ‘framing’ characters will be applied to the start and end of the barcoded string depending on the type specified.

Comments This command only produces a barcode compatible string. If the barcode is to be printed you will need to use composition edit commands (begin ce/end ce) to include the element in an existing print datastream page. The string is suitable for printing with the appropriate barcode font as provided with DOC1 Host distribution material.

Example ...// Read page of AFP dataread 1 page from file 0 into <AFPDSPage>;// Read barcode info from journalread 1 items from file 1 into <JournalData>;let <BarCode> = barcode 3of9 using <JournalData>; begin ce into <AFPDSPage>; =SCPP 001.500 002.500;; =STP 90;; =STL X0BAR3O9 %@<BarCode>;; end ce;

38 Programming PCE

let (boolean evaluation)

Function Computes a boolean expression and stores result.

Syntax let <booResult> = { <num1> in range numLower..numUpper | <num1> {lt|le|gt|ge|eq|ne} num2 | <str1> contains str2 | <str1> equals str2 | <boo1> {and|or|and not|or not} <boo2> | not <boo1> | true | false} ;

Effects of the various options:

<num1> in range numLower..numUpper<booResult> is true if variable num1 contains a value in the inclusive range represented by literals numLower to numUpper.

<num1> {lt|le|gt|ge|eq|ne} num2<booResult> is true if comparison of variable <num1> with literal num2 matches the argument given. Standard shorthand is used for the comparison argument: ‘less than’ (lt); ‘less than or equal to’ (le); etc.

<str1> contains str2<booResult> is true if variable <str1> matches or contains part of literal str2.

<str1>equals str2<booResult> is true if variable <str1> matches literal str2.

<boo1> {and|or|and not|or not} <boo2><booResult> is true if comparison of two variables holding boolean values matches the argument given.

not <boo1><booResult> is true if variable <boo1> is false.

true<booResult> is set to true.

false<booResult> is set to false.

Comments Nested expressions are not directly supported. You may need to specify consecutive statements to achieve the desired logic.

Example ...// Read from journalread 5 items from file 1 into <Input>;// Check page number is less than 100let <PageNumber> = <Input>(0);


let <Check1> = <PageNumber> lt 100;// If OK check for batch typeif <Check1> then; let <BatchType> = <Input>(1); let <Check2> = <BatchType> contains "blue"; if <Check2> then; ... end if;end if;

let … call userexit

Function Call an external program via the user exit feature.

Syntax [let <Result> = ]call userexit {"Identifier"} [[with <Parameter> in numCell]...];

Effects The user defined program specified by "Identifier" in the User Exit control file being used by the PCE application will be executed. Any value returned by the user exit program will be stored in <Result> if this is coded. Optional parameters <Parameter> are passed to the program via PCE memory cells as indicated by numCell.

Comments User exits of type PRINTSTREAM should return a self-contained segment of output datastream. This can be included within an existing page using the insert object command.

Parameters can only contain a STRING or PAGE data type; NUMBER and DATE data types are not supported. The PCE memory cell for the parameter must be in the range 9900–9998 and must match the appropriate number specified in the DOC1 Engine Data Exchange API function being used with the user program. The result value, if used, will always be of type STRING.

Refer to the “User Exits” on page 171 in this guide for more information about the communication process between PCE and user programs, returning AFP image objects and coding the User Exit control file.

Example ...let <Title> = "Customer_Name"; let <Number> = "Customer_Number";call userexit <WriteName> with <Title> in 9900;let <UXResult> = call userexit <GetAddress> with <Number> in 9901;let <Parm1> = substring<UXResult> 2 5;

let … DIJelement

Function Gets index elements from an entry read from a DOC1 Interchange Journal (DIJ).

40 Programming PCE

Syntax let <strValue> = DIJelement {Name|AddrLine1...AddrLine6|City|Region|PostalCode|Country|Phone|NumberOfPages|SkippedPages} in <xmlRecord>;

Effects The named element within the DIJ record <xmlRecord> will be copied into the variable <strValue>.

Comments The file from which the record is taken must have been opened as type DIJ.There are 6 possible 'address line' elements.

Example See “change DIJelement” on page 32.

let … document id

Function Retrieves the unique DOC1 document identifier from the first page of a document.

Syntax let <strId> = document id in <pageExistingPage>;

Effects The DOC1 document identifier stored in <pagExistingPage> is copied to <strId>.

Comments Document identifiers are added to the datastream by EMFE when a DIJ index is being created for the application – i.e. when the datastream is intended to be stored in the Document Repository component. The ID will always be stored in the first page of each document within the datastream.

If your PCE script has cause to remove or reorder the position of pages within a document you may need to use the add document id command to ensure that page 1 of each document has a valid identifier.

Example See “add document id” on page 27.

let … document name

Function Retrieve the name of the document group.

Syntax let <strAttributeName> = document name in <docGroup>;

Effects The name in the begin and end structured fields of the AFPDS page group stored as PCE document group <docGroup> is retrieved into the variable <strAttributeName>.

Comments Note that this command is only valid when working with AFPDS files with a page group structure. Using it with other file formats will cause unpredictable results.

Example let <nameofdoc> = document name in <document1>;


let … document TLE

Function Retrieves the AFP group level TLE information from a document group.

Syntax let <strAttributeValue> = document TLE <strAttributeName> in <docGroup>;

Effects The contents of the AFPDS page group stored as PCE document group <docGroup> will be searched for an AFP group level index attribute name matching <strAttributeName>. If a match is found the data stored as the attribute value will be copied to <strAttributeValue>. If a match is not found <strAttributeValue> will be a zero length string. (Note: this can be checked for – see example).

This command searches for an AFPDS ‘Tag Logical Element’ (TLE) structured field in the variable. This is one of the structured fields that make up the indexing features of the AFPDS protocol.

Comments The content of TLE’s will need to be established before this command can be coded. You should refer to the IBM publication Mixed Object Document Content Architecture Reference (MODCA-P) for full technical details of the index construct. However, the parameters used above map to the components of the actual TLE structured field (using the terms as documented in the MODCA-P manual for TLE) as follows: Attribute Name is the Fully Qualified Name (X’0B’ Attribute Name) triplet; the Attribute Value is as described in the entry for TLE; Sequence Number and Level are parameters of the Attribute Qualifier triplet.


Example let <firstgroupTLE> = document TLE <index1> in <document3>;let <OK> = Length <firstgroupTLE>;if <OK>; write document into file <logfile> from <document3>;else: trace "Index not matched";end if;

let (environment values)

Function Gets various values relating to the PCE run-time environment.

Syntax let <varValue> = {pageoffset|docoffset|date|time};

Effects <varValue> is given the current value of the environment type specified:

pageoffset<varValue> is given a byte count representing the current offset of a file pointer from the start of a print datastream file. The file pointer used always belongs to the print datastream output file that was the subject of the last write operation.

42 Programming PCE

docoffset<varValue> is given a byte count representing the offset from the start of a print datastream file where the document header information ends and where the actual ‘page’ data begins. The file pointer used always belongs to the print datastream output file that was the subject of the last write operation.

date<varValue> is given a string representing the system date at which the command was issued. The format of this string is ‘DayOfMonth[2]Month[3]Year[4]’ where the figures in brackets indicate the length of information for each part of the date. Abbreviations are used where appropriate. Example output: 04Jul1998.

time<varValue> is given a string representing the system time at which the command was issued. The format of this string is ‘Hours[2]:Minutes[2]:Seconds[2]’ where the figures in brackets indicate the length of information for each part of the time. Example output: 13:06:56.

Comments For pageoffset and docoffset values it is advisable to use this command immediately after the write operation for the file to which it is intended to apply. You cannot get these values from files opened for input.

Example ...open <OutputList> for output as file 0 line/plainopen <AFPInFile> for input as file 1 wsafp/afpds;open <AFPOutFile> for output as file 2 wsafp/afpds;// Read and write first page of AFPread <ReadNumber> page from file 1 into <AFPData>;write 1 page into file 2 from <AFPData>;//Get and write document offset to outputlet <DocumentOffset> = docoffset;let <Offsetout> = string <Offset> 10 zero;write 1 item into file 1 from <OffsetOut>begin loop; //Get and write page offset to output let <Offset> = pageoffset; let <OffsetOut> = string <Offset> 10 zero; write 1 item into file 0 from <OffsetOut> // Get and write date and time info to output let <Date> = date; write 1 item into file 0 from <Date> let <Time> = time; write 1 item into file 0 from <Time> // Read next ‘page’ read <ReadNumber> items from file 1 into <AFPData>; // stop if no more data to process let <Done> = <ReadNumber> lt 1; exit loop when <Done>; // Write out current page before querying offset value write 1 page into file 2 from <AFPData>;end loop;


let (number functions)

Function Computes a numeric expression or conversion and stores result.

Syntax let <numResult> ={ num1 | <num1> {+|*|-|/} <num2> | value <str1> | length <str1> |} ;


num1the literal value num1 is copied to <numResult>.

<num1> {+|*|-|/} <num2><numResult> is given the value resulting from the calculation specified involving <num1> and <num2>.

value <str1><numResult> is given the result of converting the text representation of a decimal number in variable <str1> to an actual numeric value.

length <str1><numResult> is given the numeric value equivalent to the number of bytes occupied by variable <str1>.

Comments Nested expressions are not directly supported. You may need to specify consecutive statements to achieve the desired calculation.

Example ...// Read page number from journal and convert to numberread 1 items from file 1 into <Input>;let <PageCount> = value <Input>;// Compute number of pageslet <PageTotal> = <AddPages> + <PageCount>;

let … page count

Function Gets the number of pages in a document group.

Syntax let <numPages> = pagecount of <docGroup>;

Effects The number of pages in the AFPDS page group stored as PCE document group <docGroup> is stored in <numPages>.

44 Programming PCE


Example let <NumberofPages> = pagecount of <document1>;

let (text functions)

Function Computes a string expression and stores result.

Syntax let <strResult> = { <str1> | <str1> + <str2> | "Literal %@<var1> more literal" | X‘hex1,hex2,hex3,...’ |..mapp "...@@[Nstr1|Dnum1|I<var1>|Mnum1]@@..." | ltrim <str1> | rtrim <str1> | atrim <str1> | mixc <str1> |..substring <str1> numStart numLength |..string <num1> numLength [{left|right|zero}] | dbcs-hex’hexCodes’ |..symbol "<symbolname>" } ;


<str1>The contents of variable <str1> are copied to <strResult>.

<str1> + <str2><strResult> is given the result of a concatenation of the contents of variables <str1> and <str2>.

Example: let <var1> = "The quick ";let <var2> = "brown fox";let <var3> = <var1> + <var2>; // produces "The quick brown fox"

"Literal... "The text and the contents of the variables included within the quote marks are copied to <strResult>. Variable names must be indicated by the prefix %@.Example:let <var1> = "brown"let <var2> = "The quick %@<var1> fox";*// above produces "The quick brown fox"


X ‘hex1,hex2,hex3,...’<strResult> is given a string which is the result of a translation of the characters represented in hex format to the text equivalent for the appropriate operating system. (Note: use the DBCS-HEX keyword to enter text for double byte fonts). Example:let <var1> = x’E3,88,85,40,98,A4,89,83,92,40,82,99,96,A6,95’; // above produces "The quick brown" on EBCDIC systems

mapp...These options perform a look-up of one or more strings in the DOC1 text substitution file (as assigned to the application in the Initialization file). <strResult> is updated with the string parameter as entered but with any text between double @ symbols resolved with the appropriate entry from the text substitution file. The look-up can be performed using a variety of methods as indicated by the first character within the @@ construct (which is ignored). These are as follows:N – str1 is a literal indicating a label used in the text substitution file.D – num1 is the sequence number of an entry in the text substitution file where 1 is the first entry,

2 is the second and so on.I – <var1> is an indirect reference to an entry in the text substitution file. If it contains a string it is

assumed to be a label name. If it contains an integer it is assumed to be a sequence number. M – num1 is a literal reference to one of the 16 user value keywords in the currently active preference

section of the Initialization file. 1 = UserValue1, 2 = UserValue2 and so on. The value assigned to the keyword must be numeric and is used as the sequence number of an entry in the text substitution file.

Examples:All examples assume the text substitution file contains the following entriesday Wednesdaymonth June period quarterly1. <var2> will be given "The month is June":

let <var1> = "The month is @@Nmonth@@";let <var2> = mapp <var1>;

2. <var2> will be given "The day is Wednesday"let <var1> = "The day is @@D1@@";let <var2> = mapp <var1>;

3. <var3> will be given "Accounting period is quarterly"let <var1> = "period"let <var2> = "Accounting period is @@I<var1>@@";let <var3> = mapp <var1>;

4. Assuming the initialization file containsUserValue3 = 2<var2> will be given "The month is June":let <var1> = "The month is @@M3@@";let <var2> = mapp <var1>;

Refer to the DOC1 Production Guide for details of the text substitution and Initialization files.

ltrim <str1><strResult> will contain the contents of variable <str1> with leading spaces removed.Example:let <var1> = " The quick brown fox";let <var2> = ltrim <var1>; // produces "The quick brown fox"

46 Programming PCE

rtrim <str1><strResult> will contain the contents of variable <str1> with trailing spaces removed. Example:let <var1> = "The quick brown fox ";let <var2> = rtrim <var1>; // produces "The quick brown fox"

atrim <str1><strResult> will contain the contents of variable <str1> with leading and trailing spaces removed. Example:let <var1> = " The quick brown fox ";let <var2> = atrim <var1>; // produces "The quick brown fox"

mixc <str1><strResult> will contain the contents of variable <str1> with mixed case conversion applied. If this option is used the initialization file used must specify an exception dictionary file. Words not present in the dictionary will produce ‘standard’ cased output – i.e. the first character will be upper-case and all others lower-case regardless of the input format. Words that are present in the dictionary - i.e. that have the same letters as the input word – will produce the casing used in the dictionary.The exception dictionary should simply contain one or more text strings with the required casing correctly specified. Each text string should appear on a separate line/record. Example: if the exception dictionary contains the text string "PhD"let <var1> = mixc "phd" // produces "PhD"if the exception dictionary does NOT contain "PhD" (using any casing)let <var1> = mixc "pHD" // produces "Phd"

substring <str1> numStart numLength<strResult> is given a copy of (up to) numLength characters from string variable <str1> starting at character numStart. Example:let <var1> = "The quick brown fox";let <var2> = substring <var1> 4 5; // produces "quick"

string <num1> numLength [{left|right|zero}]<strResult> is given the result of converting the numeric value of variable <num1> to a text representation of a decimal number.numLength is a number literal indicating the format to be used when storing the result. The overall length of the string (e.g. the number of characters used to represent it) is dictated by a number to the left of the decimal point (if used). The number to the right of the decimal point (if any) indicates the number of decimal places to be used. If numLength is 0 (zero) strResult will be allocated the number of characters required to store the result (i.e. its variable length). Note that the decimal point and minus character each occupy one character position. Any decimal places defined but not filled with data will automatically be padded with 0’s (zeros). For example if numLength is 7.3 the overall length of the result string will be seven characters one of which will be a decimal point and three of which will be reserved for decimal places.The final, optional parameter may be used to indicate whether the result is to be left or right justified, or whether it is to have numeric padding of spaces. This formatting takes place within the number of characters specified for numLength. The default is right justification. If the zero option is defined, all integral positions defined by numLength but not filled with data will be padded with 0’s (zeros). Examples:let <var2> = 3.5;let <var1> = string <var2> 6 left // produces "3 "let <var1> = string <var2> 6 right // produces " 3"let <var1> = string <var2> 6 zero // produces "000003"


let <var1> = string <var2> 6.2 right // produces " 3.50"let <var1> = string <var2> 6.2 zero // produces "003.50"let <var1> = string <var2> 6.2 zero // produces "003.50"let <var2> = -3.5;let <var1> = string <var2> 6 left // produces "-3 "let <var1> = string <var2> 6 zero // produces "0000-3"let <var1> = string <var2> 6.2 right // produces " -3.50"let <var1> = string <var2> 6.2 zero // produces "0-3.50"

dbcs-hex’hexCodes’<strResult> stores the DBCS text representation hexCodes for later use with an AFP (only) DBCS font. hexCodes takes the form of groups of four characters representing a sequence of hex bytes. The first four characters represent the first double byte character to be printed; characters 5-8 represent the second double byte character and so on. Within these groups, the first two characters together represent the section number and the second two the actual code point of the double byte character. Example:let <var1> = dbcs-hex‘020A001B030B00A4’;

symbol "<symbolname>"The value of symbol <symbolname> is copied to <strResult>. The symbol <symbolname> and its value must be defined either in the Initialization file or as part of the PCE start-up process; see ‘Executing PCE’ in the DOC1 Production Guide for details. If a symbol is used that does not have a value, then an empty string is returned.

Comments Nested expressions are not directly supported. You may need to specify consecutive statements to achieve the desired logic.

See also “let … barcode” on page 38

let … TLE …

<strValue> Searches for and stores an AFPDS index value.

Syntax let <strAttributeValue> = TLE <strAttributeName> in <pagAFPData>;

Effects The contents of the AFPDS ‘page’ stored as variable <pagAFPData> will be searched for an AFP Index attribute name matching variable <strAttributeName>. If a match is found the data stored as the attribute value will be copied to variable <strAttributeValue>. If a match is not found <strAttributeValue> will be a zero length string (note: you can check for this – see example).

This command searches for an AFPDS ‘Tag Logical Element’ (TLE) structured field in the variable. This is one of the structured fields that make up the indexing features of the AFPDS protocol. If you are using the full DOC1 solution to generate AFPDS files, a TLE will be placed in AFPDS ‘pages’ created by EMFE when an appropriate journal Entry has been specified as part of the application rules. (This assumes that the associated journal object has been defined as output type AFP.) In this scenario the attribute name will be the data generated by the first object associated with the journal Entry object in the Application Layout Editor when designing the application. The attribute value will be the second associated object in the sequence.

48 Programming PCE

Comments If the AFP Index was not generated by EMFE the content of TLE’s will need to be established before this command can be coded. You should refer to the IBM publication Mixed Object Document Content Architecture Reference (MODCA-P) for full technical details of the index construct. However, the parameters used above map to the components of the actual TLE structured field (using the terms as documented in the MODCA-P manual for TLE) as follows: Attribute Name is the Fully Qualified Name (X’0B’ Attribute Name) triplet; the Attribute Value is as described in the entry for TLE.

Note that this command is only valid when working with AFPDS files. Using it with other file formats will cause unpredictable results.

Example ... read 1 item from file <AFPInput> into <AFPPage>; let <Title> = "Customer_Name"; let <Value> = TLE <Title> in <AFPPage>; let <OK> = Length <Value>; if <OK>; write 1 item into file <ReportFile> from <Value>;else: trace "Index not matched";end if;

let (variable copy)

Function Copies one variable to another.

Syntax let <var1> = <var2>;

Effects The contents of variable <var2> will be copied into <var1> regardless of the existing type of either contents. The existing contents of <var1> (if any) will be overwritten.

Example ...if <CopyRequired>; let <DocPage2> = <DocPage1>; let <HoldInfo>(1) = <Journal>(<Entry1>);end if;

merge

Function Merges two ‘pages’ of output datastream and optionally re-sizes. For AFPDS output merge can also be used to copy a BCOCA object into an existing page.

Syntax merge <pagPage1> into <pagPage2> [of new size <numXSize> <numYSize> inches] ;

Effects All printable elements defined in the existing ‘page’ of print datastream stored as variable <pagPage1> will be added to the print datastream page stored as variable <pagPage2>. Optionally, <pagPage2> is re-sized with the values specified in number variables <numXSize> (page ‘width’) and <numYSize> (page ‘height’).


If no new size is specified <pagPage2> retains its existing dimensions.

<pagPage1> is unaffected by this operation.

Comments Both <pagPage1> and <pagPage2> must each contain a single output datastream ‘page’ or, for AFPDS files only, <pagPage1> can be a complete BCOCA object. Both pages must be of the same output datastream type.

‘Width’ and ‘height’ values are relative to the ‘page origin’. This is defined as the top left corner of the physical page. The concepts of ‘top’ and ‘left’ depend on the particular printer being used. Consult your printer hardware documentation for details.

Example ...open "DD:INPUT1" for input as file 1 record(8205)/AFPDS;open "DD:INPUT2" for input as file 2 record(8205)/AFPDS;open "DD:OUTPUT" for output as file 3 record(8205)/AFPDS;...read 1 items from file 1 into <TopOfPage>;read 1 items from file 2 into <WholePage>;let <X> = 7.5;let <Y> = 11;merge <TopOfPage> into <WholePage> of new size <X> <Y> inches;write 1 items into file 3 from <WholePage>;

move

Function Moves all elements in a print datastream ‘page’ by an offset value.

Syntax move <pagExistingPage> by <numXOffset> <numYOffset> inches;

Effects All printable elements defined in the existing ‘page’ of print datastream stored as variable <pagExistingPage> will be moved by the values specified in number variables <numXOffset> (‘across’ the page) and <numYOffset> (‘down’ the page). <numXOffset> and <numYOffset> may be negative values if desired.

Comments <pagExistingPage> must only contain a single print datastream ‘page’.

Printing positions and X and Y directions are relative to the ‘page origin’. This is defined as the top left corner of the physical page. The concepts of ‘top’ and ‘left’ depend on the particular printer being used. Consult your printer hardware documentation for details.

It is the user’s responsibility to ensure that all printable elements will still fall within physical page boundaries following the move. Results will be unpredictable where this is not the case.

Example ...open "DD:INPUT1" for input as file 1 record(8205)/AFPDS;open "DD:OUTPUT" for output as file 2 record(8205)/AFPDS;read 1 items from file 1 into <AFPPage>;let <X> = 1.5;let <Y> = -1;move <AFPPage> by <X> <Y> inches;write 1 items into file 2 from <AFPPage>;

50 Programming PCE

move page

Function Moves a page into a document group

Syntax move page <page> to <docGroup> at <strPosition>;

Effects All printable elements defined in the existing page of print datastream stored as <page> will be moved to the AFPDS page group stored as PCE document group <docGroup>. The page will be stored at <strPosition>. After the move, <page> will be empty.

Comments <strPosition> may be ‘Start’, ‘End’, or the page number after which the page will be inserted. If the page number is invalid, the page is inserted at the end.

<page> must have been read from a file previously opened as type ‘AFPDS’ and must only contain a single print datastream ‘page’.

Example See “extract document page” on page 36

on error call

Function Specifies a function name to be called in the event of an IO error.

Syntax on error call <strFunctionName>;

Effects Whenever the open, close, read, write, replace or overwrite commands return an error, function <strFunctionName> will be called.

Only one function can be called in this manner during a PCE process.

Comments This command can be specified anywhere in the control File but only becomes active once it has been processed. Once activated you cannot return to the default functionality for PCE IO errors. Default functionality (i.e. where on error call is not active) is for the PCE process to terminate and a generic error message to be issued.The function acting as the error routine can query the nature of the error via the sys_last_error system value. The table below shows possible values and their meanings.


Example declare procedure <MainProc> is main;declare procedure <ErrorRoutine>;on error call <ErrorRoutine>

begin procedure <MainProc>;...end procedure <MainProc>;

begin procedure <ErrorRoutine>; // Perform evaluation for possible error codes and take appropriate action let <ErrorCheck> = <sys_last_error> = 22; if <ErrorCheck>; trace "Output file not opened"; let <sys_exit_value> = 12; quit; end if; let <ErrorCheck> = <sys_last_error> eq 24; if <ErrorCheck>; trace "Unable to close output file"; end if; let <ErrorCheck> = <sys_last_error> eq 129; if <ErrorCheck>; trace "Unable to write to output file"; end if;end procedure;

sys_last_error Meaning

21 The open command could not open an input file

22 The open command could not open an output file

23 The close command was unable to close an input file

24 The close command was unable to close an output file

25 A replace or overwrite command has failed

33 An invalid file ID has been specified

95 A non-existent file has been specified in a read or write command

126 The format of a read or write command is incorrect

129 Unable to write to an output file

52 Programming PCE

open

Function Declares and opens a file for processing.

Syntax open <strName> for {input|output} as file <numRef> [PARM1[/PARM2]];

Effects The file identified by <strName> is opened for input or output processing with attributes as specified in PARM1 and PARM2. Files specified as input are opened for read. Those specified as output are opened as for a new file (i.e. an existing file is overwritten). The file is assigned an ID of <numRef> by which it is referred to in subsequent PCE commands.

If an error occurs a return code from this function will be stored as system value <sys_last_error>.

Parameters File attribute specification is split into two parameters separated by a slash if both are defined.

PARM1

The first parameter defines the record construct of the file. Specify one of the following operands:

lineIndicates that the file uses CR/LF bytes at the end of each record.Use this operand for most file types when processing on OS/2, NT or UNIX where wsafp and wsmeta do not apply.

record [(numRecSize)]Indicates that the file is in the standard ‘record’ format used for OS/390 and is unblocked file with variable length records.Use this operand for most file types when processing on OS/390.numRecSize optionally specifies the record length associated with the file. If you are writing to a variable blocked dataset under OS/390 you should specify a value greater than the longest possible record length to be produced (e.g. 8205 for AFPDS and 300 for Metacode). For fixed blocked datasets specify the block size or greater. Read functions will cease at end of record regardless of length specified. If you do not specify numRecSize PCE will assume the value from the Maximum Record Length parameter of the active Preferences definition (see ‘File Format Reference’ in the DOC1 Production Guide for details).

vsamafp [(numRecSize)] OR vsammeta[(numRecSize)]Indicates a predefined format of an OS/390 VSAM file containing AFPDS (vsamafp) or Metacode (vsammeta). PCE supports only VSAM Relative Record Datasets (RRDS) and this format is always assumed. The dataset has fixed length records of size numRecSize. If you do not specify a length parameter PCE will assume a record length of 100. A ‘page’ of composed print datastream always starts at the beginning of a record ‘slot’ but may span multiple slots. The final slot occupied by a page is padded to the start of the next slot.Note: suitable RRDS datasets are defined as type "numbered" when generated using the Define Cluster utility of VSAM Access Method Services under OS/390. The following is an example of the Define Cluster command syntax that would generate an RRDS dataset supported by PCE (assumes a numRecSize of 100):DEFINE CLUSTER -(NAME(DATA.FOR.PCE) -RECORDSIZE(100 100) -VOLUMES(VSER01) -TRACKS(10 5) -NUMBERED)


wsafpIndicates a predefined format for an AFPDS print datastream suitable for most purposes when the host system is OS/400, UNIX, NT, OS/2, or DOS. Specifically, the AFPDS is produced as a true stream and has no special blocking or record formatting. If you were using the format operand this would equate to the parameter sequence:$BN($RV($RD))

wsmetaIndicates a predefined format of Xerox Metacode print datastream that is suitable for various types of tape driver software that can be attached to OS/400, UNIX, NT OS/2 or UNIX hosts. Specifically, the Metacode includes an Intel style record descriptor word (RDW) before each datastream record. If you were using the format operand this would equate to the parameter sequence:$BN($RV($RS(L,2,0),$RD))

ksdsafp [(numRecSize)] OR ksdsmeta[(numRecSize)]Indicates a predefined format of an OS/390 VSAM KSDS file containing AFPDS(ksdsafp) or Metacode (ksdsmeta). The dataset has fixed length records of size numRecSize.A ‘page’ of composed print datastream always starts at the beginning of a record ‘slot’ but may span multiple slots. The final slot occupied by a page ispadded to the start of the next slot.Notes: • Suitable KSDS datasets must be defined as type 'INDEXED' with a keylength of 10 bytes

starting in the first byte of the record.when generated by EMFE/PCEusing the Define Cluster utility of VSAM Access Method Services under OS/390.

• The Blocksize that is defined in the VSAM KSDS must be 10 bytes greater than that specified in the $BK statement to allow for the key.

The following is an example of the Define Cluster command syntax that would generate a KSDS dataset supported by DOC1 (assumes a numRecSize of 1000):DEFINE CLUSTER -(NAME(MYUSER.FROMEMFE.KSDS) -INDEXED -KEYS(10 0) -SPEED -SHR(1 3) -FREESPACE(0 10) -RECORDSIZE(1010 1010)) -DATA -(NAME(MYUSER.FROMEMFE.KSDS.DATA) -VOLUMES(VOLSER01) -TRACKS(10 5) -CONTROLINTERVALSIZE(1024)) -INDEX -(NAME(MYUSER.FROMEMFE.KSDS.INDEX) -VOLUMES(USER91) -CONTROLINTERVALSIZE(1024))

format(strFormatParms)Indicates that the file has a format not catered for by the predefined keywords. Where this is the case you will need to supply details of the format as strFormatParms. The conventions used for such definitions together with examples of use are detailed in Appendix B of the DOC1 Production Guide.

54 Programming PCE

PARM2

The second parameter specifies the file type, i.e. what data it contains and therefore how much data should be handled each time a read or write command is performed. Specify one of the following operands:

plainThe file is not delimited by any of the methods indicated below. Each read/write operation will get/put a complete ‘record’ from or to the appropriate file. Use this for most DOC1 journal files except for type DIJ.

delimited({‘charSep’|numSep})The file contains two or more fields in each record and that the fields are separated by the character specified. The field separation character may be identified as a text character ‘charSep’ or as a decimal value representing the character in the standard code page for the relevant operating system numSep. Each read/write operation will get/put a single field from the file.

afpdsThe file contains AFP datastream file. Each read/write operation will get/put the data structures that make up a single composed AFPDS page.

metacodeThe file contains Metacode datastream file. Each read/write operation will get/put the data structures that make up a single composed Metacode page.

postscriptThe file contains PostScript datastream file. Each read/write operation will get/put the data structures that make up a single composed PostScript page.

VPSThe file contains VPS datastream file. Each read/write operation will get/put the data structures that make up a single composed VPS page.

DIJThe file contains a DOC1 Interchange Journal. This is an XML construct which passes document indexes to the DOC1 Archive, DOC1 Present and DOC1 Pay environments. Each read/write operation will get/put the index entry related to a single document.

Comments Refer to “File Names” on page 24 at the start of this section for details of how files are identified on the various supported operating systems.

If the attribute parameters are not coded the defaults for UNIX, OS/2, NT or DOS are "line/plain" and for OS/390 or OS/400 "record/plain".

Note: for datastreams created by DOC1 generated applications, a new ‘page’ in the appropriate datastream format is created every time a ‘New Page’ action is used or implied (i.e. at the start of processing for each data document).

Examples

(for OS/390) ...// Determine which AFPDS input file is required and open it.// The DD Name used is a concatenation.let <AFPfile> = <DDPrefix> + <PassNo>


open <AFPFile> for input as file 0 record(8205)/afpds;// Open the journal file with an explicit dataset name.// This file has 3 fields delimited by the space character // which is identified by the decimal EBCDIC code below.open "USER001.APPLIC1.JOURNAL(JAN05)" for input as file 1 record(80)/delimited(64);// Open the output AFPDS file with an explicit DD Name// The file ID is set by a counter variablelet FileCount = FileCount + 1;open "DD:AFPOUT" for output as file <FileCount> record(8205)/afpds;...

(for Windows, etc.)...// Determine which AFPDS input file is required and open it.// The path is concatenated with the file name.let <AFPFile> = <PathString> + <FileName>;open <AFPFile> for input as file 0 wsafp/afpds;// Open the journal file with an explicit path name. // This has 3 fields delimited by the space character// which is identified by the decimal ASCII code below.open "C:\DOC1\APPLIC1\JOURNAL\JAN05.JRN" for input as file 1 line/delimited(32);// Open the output AFPDS file with an explicit path name.// The file ID is set by a counter variable.let FileCount = FileCount + 1;open "C:\DOC1\APPLIC1\OUT.AFP" for output as file <FileCount> wsafp/afpds;...

overwrite

Function Finds and replaces a string without affecting string length.

Syntax overwrite <strOld> in <pag1> with <strNew> [ once ];

Effects One or more occurrences of the <strOld> in variable <pag1> will be overwritten with the contents of variable <strNew>. The space allocated to store <strNew> will be exactly the same as <strOld> so truncation may occur or some bytes may remain unchanged if the two strings are of different length.

If the optional parameter "once" is specified the first occurrence of <strOld> will be overwritten but subsequent occurrences will not be affected.

If an error occurs, for example, ‘search string not found’, a return code from this function will be stored as system value <sys_last_error>.

Comments The string parameters of the overwrite function are case sensitive.

If you need to replace strings of different length without truncation or padding use the replace statement.

If performance is an issue, use overwrite rather than replace if possible. Specifying ‘once’ will improve the performance of overwrite in most cases.

56 Programming PCE

Example ...if <Page1>; let <OverwriteText> = "Page 2 is next";else; let <OverwriteText> = "Page 2 is here";end if;overwrite "***texthere***" in <AFPPage> with <OverwriteText>;on error call <ErrorProc>

quit

Function Causes an immediate termination of PCE processing.

Syntax quit;

Effects On encountering this statement the PCE program will terminate immediately.

Comments All open files will be closed automatically.Example ...

// Check that a full read took place...let <BadRead> = <ReadNumber> lt 5;// ... if not abort programif <BadRead>; quit;end if;

read

Function Reads one or more items from a file.

Syntax read [at <numOffset>] <numBatches> items from file <numFileRef> into <iodReadData>;

Effects <numBatches> items of data will be read from the file referenced by <numFileRef> and stored in variable <iodReadData>. If <iodReadData> has been declared as an array, each item will be read into a separate array element. If not, all items will be concatenated and subsequently treated as a single batch.

The amount of data that makes up an item depends on the attributes specified for the file when it was opened.

If the optional ‘at’ keyword/parameter is specified, reading will begin at the point in the file indicated by <numOffset>. This value can have two different bases depending on the host system. OS/390, OS/400 <numOffset> represents a record count from the start of file. The first record

is considered to be 1. (Note: on OS/390 systems, this value can be used with the VSAM RRDS files as well as other standard OS/390 formats.)


OS/2, UNIX, DOS <numOffset> is a byte offset from the start of file. The first byte is considered to be byte 0 (zero).

If the data for <numOffset> is being read from a journal file generated by a EMFE application, the required value types can be generated by using the vector offset environment variable. Refer to the Designers Guide for more information about environment variables.

Following a successful read, the file pointer of <numFileRef> will be updated to the position immediately after the data read, i.e. if a further read takes place without using the <numOffset> parameter, reading will commence at the position immediately following the end of the data that was previously read.

Reading will stop before the number of specified items if end of file is reached or if <iodReadData> has less array elements than the number of items specified. Providing <numBatches> is a variable it will be updated to reflect the number of items actually read. If required, the variable can be queried to ascertain how many pages have been read.


Comments The actual batch of data that constitutes an item depends on the parameters used for the appropriate file open statement. For a ‘delimited’ file for instance (typically a DOC1 journal file), an item is the data between the start of a record and the delimiter character or between two delimiters. For a file containing print datastream it is the structured data that makes up a complete printable page.

Note that, if more than 1 item is read into a non-array variable PCE has no means of identifying individual pages once they are stored.

If used on page group structures, the page group information will be lost.

To assist readability, the operand ‘items’ in the command syntax may be replaced by any other single word. For instance you may want to use ‘pages’ for handling print datastreams.

Example Declare <JournalData>(5);Declare <AFPData>;...let <ReadNumber> = 2;// Read from journalread <ReadNumber> items from file 0 into <JournalData>;// Check that a full read took place...let <BadRead> = <ReadNumber> lt 2;// ... if not abort programif <BadRead>; trace "Insufficient data in journal file"; quit;end if;// If the journal entry shows the type required...let <MatchedAccount> = <JournalData>(0) equals "Type 2";//...read the AFPDS page at the appropriate file offsetif <MatchedAccount>; read at <JournalData>(1) 1 page from file <AFPFile> into <AFPData>;end if;

58 Programming PCE

read … DIJentry

Function Reads an entry from a DOC1 Interchange Journal.

Syntax read <numEntries> DIJentry from file <numFileRef> into <xmlRecord>;

Effects The next entry from DIJ file <numFileRef> will be stored in variable <xmlRecord>. Following a successful read, the file pointer will be moved to the start of the subsequent entry in the DIJ so that further reads can take place.

Comments: The file to be read must have been opened as type DIJ.In the current version of PCE you may only read one entry at a time, i.e. <numEntries> must be the constant '1' or be a variable containing '1'.Refer to “let … DIJelement” on page 40 for information about reading specific elements from a DIJ entry.


read … document

Function Reads pages directly into a document group.

Syntax read [at <numOffset>] <numPages> document from file <numFileRef> into <docGroup>;

Effects For AFP datastreams the page(s) specified by <numPages> in the file <numFileRef> will be stored as a PCE document group in the variable <docGroup>

If the optional ‘at’ keyword is specified, reading will begin at the point in the file indicated by <numOffset>. This value can have two different bases depending on the host system.OS/390, OS/400 <numOffset> represents a record count from the start of file. The first record

is considered to be 1. (Note: on OS/390 systems, this value can be used with the VSAM RRDS files as well as other standard OS/390 formats.)

NT,OS/2,UNIX <numOffset> is a byte offset from the start of file. The first byte is considered to be byte 0 (zero).

If the data for <numOffset> is being read from a journal file generated by a EMFE application, the required value types can be generated by using the vector offset environment variable. Refer to the Designers Guide for more information about environment variables.

Following a successful read, the file pointer of <numFileRef> will be updated to the position immediately after the data read, i.e. if a further read takes place without using the <numOffset> parameter, reading will commence at the position immediately following the previously read data.

Any error return code from this function will be stored as system value <sys_last_error>.

Comments An AFP page group structure is created in the document group, i.e. the BNG (Begin Named Page Group) and ENG (End named Page Group) structured fields are added to the structure.



Example See “add document TLE” on page 28.

replace

Function Finds and replaces a string in a Metacode page. String length may be changed.

Syntax replace "strOld" in <pag1> with <strNew> [ once ];

Effects Any occurrence(s) of the literal string <strOld> in variable <pag1> will be replaced with the contents of variable <strNew>. The space allocated to store <strNew> will be the exact amount required for the new string thus the overall size of <pag1> may be affected if the two strings are of different length.

If the optional parameter once is specified the first occurrence of <strOld> will be replaced but subsequent occurrences will not be affected.

If an error occurs, for example, ‘search string not found’, a return code from this function will be stored as system value <sys_last_error>.

Comments N.b. Replace should NOT be used with data from AFPDS pages. Doing so may result in the amount of data contradicting the length parameters in the various AFPDS structured fields.

The string parameters of the replace function are case sensitive.

If you need to replace strings without affecting length use the overwrite statement.

If performance is an issue, use overwrite rather than replace if possible. Specifying ‘once’ will improve the performance of replace in most cases.

Example ...if <Page1>; let <ReplaceText> = "Page 1 needs a large text string here";else; let <ReplaceText> = "Others do not";end if;replace "***replaces***" in <MetacodePage> with <ReplaceText>;on error call <ErrorProc>;

return

Function Causes an immediate return from a procedure.

Syntax return;

Effects On encountering this statement processing of the current control file procedure will cease and control will be passed back to the calling procedure.

Comments A return is implied by the end procedure statement. There is no need to code the actual statement in this circumstance.

60 Programming PCE

Example See “declare procedure” on page 33.

set page name

Function Defines a page name to be included in PostScript output.

Syntax set page name to <strPageName>;

Effects When generating PostScript output, the contents of the variable <strPageName> will be used by PCE to build the "%%Page:" DSC comment which is included in all PostScript pages. This will be included in the output stream the next time PCE writes out a page. Once set, this value remains in effect until the next set page name command, or until the output file is closed.

Comments Each page starts with a %%Page DSC comment. Document Structuring Conventions (DSC) comments provide information about the PostScript file to a document manager or intelligent printer. %%Page has two arguments:Page Name – can be any value. set page name will set this argument.Page Position – the position of the page in the PostScript file. This is set by PCE.If this command is not used the Page comments in the input file will be written unchanged to the output file.

Example open "C:\DOC1\APPLIC1\EMFEOUT.PS" for input as file 2 line/postscript;open "C:\DOC1\APPLIC1\OUT.PS" for output as file 3 line/postscript;...begin loop; ... // extract the customer account number ... read 1 items from file 2 into <cust_account_no>; // ... and write it into the DSC comment for PostScript set page name to <cust_account_no>; write 1 items into file 3 from <cust_account_no>; ...end loop;

TLE

Synopsis Adds, deletes or replaces a TLE (Tag Logical Element) structured fields in AFPDS data. TLEs are used to index documents and pages within the AFPDS architecture.

Syntax TLE [add|delete|replace] at [page|document] of attrib <strName> value <strValue> [qualifier <numSeq>] to <varAfpData>;


Effects This command acts on a variable or document group that contains AFPDS pages. You can add or manipulate page level TLEs in either format. When working with document level TLEs you should normally read the pages into a PCE document group to ensure the header containing the TLE is not excluded.

If adding:A TLE structured field will be inserted into the data that makes up the AFPDS page(s) stored in variable <varAfpData>. The TLE will be assigned an attribute name of <strName> and attribute value of <strValue>. Optionally, you can also code the qualifier keyword to assign sequence and level numbers to the TLE as specified in <numSeq> (see comments).If page is specified the TLE will be added within each page stored in <varAfpData>. If document is specified the TLE will be added immediately before the first page stored in <varAFPData>. In this circumstance it is the users responsibility to make sure that all the pages that make up a document are stored in the variable when the TLE is added.

If deleting:PCE will look for either page or document TLE’s (as specified) with attribute <strName> within <varAfpData>. If found, all such TLE’s are removed.

If replacing:PCE will look for either page or document TLE’s (as specified) with attribute <strName> within <varAfpData>. If found the value of all occurrences will be replaced with <strValue>. If qualifier is also coded, <numSeq> will be used to replace all existing sequence and level numbers (see below).

Comments The qualifier parameter expects a numeric value with a decimal point. The value to the left of the decimal point is treated as the sequence number and the value to the right becomes the level; e.g. 009.010 would produce a sequence number of 9 and a level of 10.

The parameters in this command map to the components of the actual TLE structured field as follows: Attribute Name is the Fully Qualified Name (X’0B’ Attribute Name) triplet; the Attribute Value is as described in the entry for TLE; Sequence Number and Level are parameters of the Attribute Qualifier triplet.

IMPORTANT: this command is not supported in PCE 4.3 and earlier versions.

Examples ... //Read document pages into document groupread 5 document from file 1 into <AFPPages>;//Add a new document level TLE before these pagesTLE add at document of attrib "Doc_start" value "First_doc" qualifier 123.456 to <AFPPages>;//Delete any page level TLEs with name ’Phase1’TLE delete at page of attrib "Phase1"//Add new page level TLEsTLE replace at page of attrib "Phase2" value "First_pages" qualifier 123.456 to <AFPPages>;write 1 item into file <AFPOutput> from <AFPPages>; ...

62 Programming PCE

trace

Function Writes a message to the PCE diagnostic files.

Syntax trace <strMessage>;

Effects <strMessage> will be written to the PCE trace and log files.

The message text may contain variable names provided the following format is used: @@<var1>

Comments See "Executing PCE" in the DOC1 Production Guide for more information regarding diagnostic files.

Example ...// Check the number of items read...let <ReadResult> = <ReadNumber> lt 5;// ... and write diagnostic messageif <ReadResult>; trace "There were less than 5 items read";else; trace "There were @@<ReadNumber> items read";end if;

translate

Function Translates a text string using a DOC1 Translation Table.

Syntax translate <strTransText> using table numTableID;

Effects The contents of variable <strTransText> are overwritten with the results of translating each character code point of the original string to the appropriate character code point from the DOC1 Translation Table identified by literal numTableID.

Comments Refer to the DOC1 Production Guide for details of the format of these tables.

Example ...translate <BaseText> using table 2;replace "*text to replace*" in <PageData> with <BaseText>;

write

Function Writes one or more data batches (‘items’) to a file.

Syntax write <numBatches> items into file <numFileRef> from <iodWriteData>;


Effects <numBatches> items of data stored in variable <iodWriteData> will be written to the file referenced by <numFileRef>.

Following a successful write, the file pointer of <numFileRef> will be updated to the position immediately after the data written, i.e. if a further write takes place it will commence at the position immediately following the end of the data that was previously written.

If multiple items are specified it is assumed that <iodReadData> is an array and contains sufficient elements to perform the required write operations. Writing will start using the array element specified with <iodReadData> and subsequent items will be taken from the array elements immediately following. For example:

write 5 items into file 1 from <AFPPages>(3);

will write 5 batches of data to file 1 starting with that stored in array element 3 of <AFPPages> and ending with element 7.


Comments Multiple items should only be written if <iodWriteData> has been declared as an array. If this is not the case results will be unpredictable. However, it is possible that a single item can contain datastream equivalent to multiple printable pages.

To assist readability, the operand ‘items’ in the command syntax may be replaced by any other single word. For instance you may want to use ‘pages’ for handling print datastreams.

Example Declare <AFPPages>(4);...// Rerun for summary page (1)if <RerunType1>; write 1 page into file 1 from <AFPData>(0);end if;// Rerun for details pagesif <RerunType2> let <pagecount> = <basecount> + 2 write <pagecount> pages into file 1 from <AFPData>(1);end if;

write DIJentry

Function Writes a DOC1 Interchange Journal entry to file.

Syntax write DIJentry into file <numFileRef> from <xmlRecord>;

Effects The DIJ entry contained in variable <xmlRecord> will be written to the file referenced by <numFileRef>.

64 Programming PCE


Comments: The file to be receive the DIJ entry must have been opened as type DIJ.In the current version of PCE you may only write one entry at a time, i.e. <xmlRecord> must contain a single DIJ entry.


write document

Function Writes a document group to file

Syntax write document into file <numFileRef> from <docGroup>;

Effects All the pages in the AFPDS page group stored as PCE document group <docGroup> will be written to the file referenced by <numFileRef>.




Example See “add document TLE” on page 28


Composition Edit CommandsThis section details the composition edit (CE) commands that may be used with the begin ce/end ce construct within a PCE control file. CE commands have a different general format from regular PCE control file commands that reflects the specialized nature of their function.

Print Positioning ConceptsAll composition edit printing positions are defined as a meeting point between an X coordinate (‘across’ direction) and a Y coordinate (‘down’ direction) on a logical page. The ‘top left’ corner of the logical page is known as the logical page origin, i.e. X=0, Y=0, and is the point from which all positions are measured. EMFE applications normally generate the CE commands for a single logical page.

Logical pages are positioned within the physical page used on the printer. The logical pages generated by PCE are positioned with the logical page origin relative to a physical page origin. The physical page origin is defined as the ‘top left’ corner of the physical page although the actual corner that constitutes top left may differ from printer to printer. Additionally, the physical page origin may be offset from actual top left by printer controls. Consult your printer hardware documentation for details.

A EMFE application with a page orientation of 0° will mean that the logical page origin matches the physical page origin, i.e. it is at the ‘top left’ corner of the page. Other page orientations will mean that the logical page origin is set at a different corner.

The current print position defines the position on the page where the next print object (text, line, etc.) will be placed. Print position coordinates are always relative to the top left corner of the current logical page. If you are generating PostScript or Metacode output, you should use the Set Physical Page Size (SPPS) command before using commands that position objects on the page. This is needed to compensate for the fact that PostScript uses the bottom left corner of the page as the origin.

A Set Current Print Position (SCPP) command should be specified before each use of a composition command. If this is not done PCE will assume a print position of X=0, Y=0. (See “Order of Commands” on page 68.)

The unit of measure used for all CE commands is expressed in inches only. The maximum valid measurement for CE commands is 999.999 inches.

66 Programming PCE

Printer Resource ReferencesUp to 2403 fonts can be included in a Font Metrics file. The Font Metrics file used with a PCE application must list the fonts in the same order as they appear in the font list of the printstream produced by EMFE and which is now being manipulated.

To ensure this is the case you will need to have EMFE use a Font Metrics file where the metrics tables are listed in the sequence indicated on the report generated by the Convert for EMFE process on the DOC1 Workstation. You can then use the same Font Metrics file for both EMFE and PCE.

Previously unused images may be used but must be referenced in the Image Metrics file.

Resource names in CE commands must always be specified exactly as the printer resource name (first parameter) in the Metrics files being used with the application. For instance, when using PostScript fonts you must use the description:size format.

Refer to the "Metrics Files" in the DOC1 Production Guide for details of generating Metrics Files and their format.

Fonts referenced by index

For fonts you can alternatively reference a resource by the appropriate sequence number within the Font Metrics file. As the index can only be two characters, the first 99 fonts are referenced by the number that corresponds to their position in the Font Metrics file – i.e. specifying a reference of '5' indicates the resource associated with the fifth table in the Font Metrics file.

Fonts in position 100 onwards are indexed by a complicated two letter code. It is therefore recommended that fonts in these positions are referenced by name and not index position.

Such references must use a number in the range 1-99 or a valid two letter code. Any characters outside these ranges are assumed to be a font name, (e.g. ‘1’ would be an index, but ‘00001’ would be a font name).

The sample CE commands below illustrates the required formats:

=STL X0FONT01 This is a text line;;=STL C0FONT02:T1FONT02 Reference to a character set/code page pair;;=COMM The following places an image;;=PI S1IMAGE1 001.500 001.500;;=STL Helvetica.8 This is a text line using a typical PostScript font ref.;;

Composition Edit Commands 67

Order of CommandsComposition edit commands must conform to the following order:

• If you intend to call image names (via the PI command) or overlay names (via PPO) you must include a Define Image List command (DIL) and/or a Define Page Overlay List command (DPOL) before the appropriate include commands (PI and/or PPO);

• If you are generating PostScript output, a Set Physical Page Size command (SPPS) must precede any command that places an object on the page, and the SCPP command;

• A Set Current Print Position command (SCPP) must precede any command that places an object other than PI or PPO;

• If an STL command is to follow the SCPP use a Set Text Presentation command (STP) to set the required orientation.

Command StructureAll composition edit commands have a fixed structure and are position sensitive. All commands are introduced with an equals sign ‘=’ in column 1 and are terminated with a double semicolon ‘;;’. Continuation records may be used if a particular command is longer than 80 bytes.

Commands are identified by mnemonic keywords in positions 2 - 5. All keywords must appear in upper case. Both keywords and parameters must occupy a fixed number of positions and trailing spaces must be used to pad the blank positions where necessary.

You can use a PCE variable as part or all of a string in any CE command. Such variables must be prefixed with the characters %@. For example: %@<var1>. Where necessary, such variables must include space padding to allow for position sensitive elements

The Measurement values for positioning commands are always in inches and are expressed as a signed number with three decimal places, i.e. a format of ±nnn.nnn. All numeric positions must be specified in full, e.g. ‘000.010’. In this example ‘.010’ would not be allowed. The sign can be omitted as it is assumed to be positive, however where this is the case the position must be padded with a space.The following examples illustrate these points. Required spaces are indicated by •:

=SCPP••001.500••002.000;;=DHR••+003.000•000.050;;=STP••90;;=STL••X0T05501•the contents of variable var1 is %@<var1>;;=PI•••S1LOGO••••001.000••001.000;;

68 Programming PCE

COLR – Set Color

Purpose To set the color to be used for drawing subsequent PostScript (only) elements

Syntax =COLR•colorcode;;

Where colorcode is one of:

Effects PostScript composition elements following this command but before a further COLR will be created using the color indicated.

Note that color for other output datastreams is not supported in PCE and this command is ignored when working with non-PostScript files.

Example =COLR 1;;=SCPP 000.500 001.500;;=DHR +000.250 000.020;;

DBX – Draw Box

Purpose To draw a box at the current print position and shade it.

Syntax =DBX••shade•thickness•width•height;;

Where shade is the percentage of shading required in the range 0...100.thickness is the thickness of the sides of the box in nnn.nnn units of measure. If this value is set to 0, no sides are drawn.width is the width of the box in nnn.nnn units of measure.height is the height of the box in nnn.nnn units of measure.

Effects A solid rule box will be drawn commencing at the current print position set by the preceding SCPP command and with dimensions as specified.

The box is always drawn left to right and down from the Current Print Position.

The box will be shaded to the percentage specified. Note that Xerox printers can use only a restricted shading range. The percentage is mapped to Metacode values as follows:

1 = Black2 = Blue3 = Brown4 = Green5 = Pink6 = Red7 = Cyan8 = Yellow

0-19% None20-39% Light40-59% Medium60-79% Heavy80-100% Black


The box is drawn so that the lines are within the dimensions specified. For example, if a box is 1" in height and 0.5" in width with a rule thickness of 0.2", the total height of the box would be 1" and the width would be 0.5".

Example =SCPP 001.000 001.000;;=DBX 005 000.020 002.000 001.000;;

DIL – Define Image List

Purpose To declare image names that are to be used in this group of PCE Begin CE into commands.

Syntax =DIL••image001•image2•••Images003...;;

Where ImageX is the name of the image to be used. Up to 127 image names may be specified, each separated by a single space. Each image name is assumed to be 8 characters in length and padding (with spaces) must be used where this is not the case.

Example =DIL S1LOGOA1 S1LOGO %@<Img1>;;=PI S1LOGO1 001.500 001.500;;

DHR – Draw Horizontal Rule

Purpose To draw a horizontal rule at the current position.

Syntax =DHR••±length•thickness;;

Where ±length is the length in + or - nnn.nnn units of measure.thickness is the thickness of the line in nnn.nnn units of measure.

Effects A solid horizontal rule will be drawn at the position specified by the preceding SCPP command with the dimensions specified.

If length is a positive value the rule is drawn from left to right from the Current Print Position, if not it is drawn from right to left.

The thickness of the rule is always drawn down the page.

Example =SCPP 001.000 001.000;;=DHR +003.500 000.050;;

DPOL – Define Overlay List

Purpose To declare overlay names that are to be used in this group of PCE Begin CE into commands.

Syntax =DPOL••overlay1•over02•••overlay3...;;

70 Programming PCE

Where ImageX is the name of the overlay to be used. Up to 2048 overlays names may be specified, each separated by a single space. Each overlay name is assumed to be 8 characters in length and padding (with spaces) must be used where this is not the case.

Example =DPOL O1OVER O1OVERXX %@<Over>;;=PPO O1OVERXX 001.500 001.500;;

DVR – Draw Vertical Rule

Purpose To draw a vertical rule at the Current Print Position.

Syntax =DVR••±length•thickness;;

Where ±length is the length in + or - nnn.nnn units of measure.thickness is the thickness of the line in nnn.nnn units of measure.

Effects A solid vertical rule will be drawn at the position specified by the preceding SCPP command with the dimensions specified.

If length is positive the rule will be drawn downwards (i.e. from top to bottom) from the Current Print Position, if not it will be drawn upwards (i.e. from bottom to top).

The thickness of the rule always goes across the page from left to right.

Example =SCPP 001.000 001.000;;=DVR +003.500 000.050;;

PBIM – Place Barcode – Intelligent Mail

Purpose To insert an Intelligent Mail barcode at the current print position.

Syntax =PBIM••orientation•fullheight•trackerheight•barwidth •density•string;;

Where orientation is the rotation of the barcode:0 - 0 degrees (left to right)1 - 90 degrees (top to bottom)2 - 180 degrees (right to left, upside-down)3 - 270 degrees (bottom to top)

fullheight is the height of the full bar in inches or fractions of an inch

trackerheight is the height of the tracker bar in inches or fractions of an inch

barwidth is the width of the bar in inches or fractions of an inch

density is the width of the space between the bars in inches or fractions of an inch

string is the string to be encoded into the barcode. Can be enclosed in double quotes.


Effects A command is inserted into the current page to draw an Intelligent Mail barcode starting at the position specified by the last SCPP command to be processed.

Example =SCPP 005.100 001.000;;=PBIM 0 000.125 000.039 000.015•000.012 01234567094987654321;;

PI – Place Image

Purpose To place the named image on the page at the defined position.

Syntax =PI•••image••Xposition••Yposition;;

Where image is the image name, which may be up to 8 characters in length. Only those image names specified in a previous DIL command may be used. DOC1 does not require the S1 prefix to be present for AFP images. If the name has less than 8 characters, it must be padded with spaces. The maximum length for Xerox image names is 6 characters.

Xposition/Yposition are the X and Y coordinates for positioning the image. Note the additional space character before these parameters indicating absolute positioning.

Effects The named image will be placed on the page at the position defined by the X and Y coordinates (note that images are placed by their upper left corner). If either of the coordinates is not present, the respective Current Print Position coordinate value is used.

Example =PI S1IMAG01 001.500 001.500;;=PI %@<Img1> +003.000 +002.000;;

PPO – Place Page Overlay

Purpose To place the named overlay on the page with its origin at the defined position.

Syntax =PPO••overlay••Xposition••Yposition;;

Where overlay is the page overlay name, which may be up to 8 characters in length. Only those overlay names specified in a previous DPOL command can be used. DOC1 requires the O1 file name prefix to be present for AFP overlays. If the name has less than 8 characters, it must be padded with spaces.

Xposition/Yposition are the X and Y coordinates representing the offset for the overlay in nnn.nnn units of measure or optionally left blank. Note the additional space character before these parameters indicating absolute positioning.

Effects The named page overlay will be placed at the coordinates defined in the command. If the X and Y coordinates are blank, the Current Print Position is used.

When using this command with PCE, the application that produced the appropriate print datastream(s) must have previously included the required overlay.

72 Programming PCE

Example =PPO O1OVER01 001.500 001.500;;=PPO %@<Over> +003.000 +002.000;;

SBT – Set Boxed Text

Purpose To create a reversed text element centered in a box.

Syntax =SBT••font•width•height•text;;

Where font is the reference to the required font to be used. The reference can be either the font name itself or a number in the range 1-99 (inclusive) which is the index into the Font Metrics table of the font required. Any number outside this range is assumed to be a font name.For PostScript output you can specify any font; for all other types of output you must use a reversed font (see Comments below).width is the width of the box in the X direction, in nnn.nnn units of measure.height is the height of the box in the Y direction, in nnn.nnn units of measure.text is the text to be printed and centered in the black box.

Effects This command centers reversed text in a solid-filled box. The solid fill (the background) will be black or the color of the current toner. The color of the text will be whatever the color of the paper is.

The box is positioned with its top left corner at the Current Print Position.

If the font height is greater than the box height, or if the text width is greater than the box width, the text will extend beyond the bounds of the box, with unpredictable results.

Comments For PostScript any font can be reversed.Reversed text fonts for AFP and Metacode are not commonly available and are normally customized for a specific application. In such fonts each character raster must extend to the maximum ascender and descender of the font otherwise this function will not work properly; a symptom of this would be white bars appearing between characters. You should refer to your DOC1 supplier for more information regarding the use of reversed fonts for AFP and Metacode.

Example =SCPP 001.000 001.000;;=SBT 02 005.000 001.000 White text centered in a black box;;

SBTR – Set Boxed Text Right Justified

Purpose To set reversed text right-justified in a box.

Syntax =SBTR•font•width•height•margin•text;;

Where font is the reference to the required font to be used (see “Printer Resource References” on page 67). The reference can be either the font name itself or a number in the range 1-99 (inclusive) which is the index into the Font Metrics table of the font required. Any number outside this range is assumed to be


a font name. The font used for this function should be a reversed font (see SBT above).For PostScript output you can specify any font; for all other types of output you must use a reversed font (see SBT Comments above).width is the width of the box in the X direction, in nnn.nnn units of measure.height is the height of the box in the Y direction, in nnn.nnn units of measure.margin is the value of the right margin, in nnn.nnn units of measure.text is the text to be printed and centered in the black box.

Effects This command sets reversed text right-justified in a solid-filled box with a specified margin. The solid fill (the background) will be black or whatever the current toner color is. The color of the text will be whatever the color of the paper is.

The box is positioned with its top left corner at the Current Print Position.

If the font height is greater than the box height, or if the text width is greater than the box width, the text will extend beyond the bounds of the box.

Comments For PostScript any font can be reversed.Reversed text fonts or AFP and Metacode are not commonly available and are normally customized for a specific application. In such fonts each character raster must extend to the maximum ascender and descender of the font otherwise this function will not work properly; a symptom of this would be white bars appearing between characters. You should refer to your DOC1 supplier for more information regarding the use of reversed fonts for AFP and Metacode.

Example =SCPP 001.000 001.000;;=SBTR 02 005.000 001.000 White text right justified in a black box;;

SCPP – Set Current Print Position

Purpose To set the Current Print Position used to position elements.

Syntax =SCPP••Xposition••YPosition;;

Where Xposition/Yposition are the X and Y coordinates representing the print position to be used for the composition elements which follow in nnn.nnn units of measure. Note the additional space character before these parameters indicating absolute positioning.

Effects Composition elements coded following this command will be positioned with reference to the SCPP values.

Example =SCPP 001.000 001.000;;

74 Programming PCE

SPPS – Set Physical Page Size

Purpose Defines the size of pages in a PostScript input datastream.

Syntax =SPPS••{width•height|name};;

Where width is the width of the page, in nnn.nnn units of measure.height is the height of the page, in nnn.nnn units of measure.name is the description of the page size. Valid options are:– A4, B4, B5, USLETTER, USLEGAL.

Effects The physical size of the target page is set. If width or height are zero or blank, then that attribute of the page size is not changed. The default page size is A4.Note that this command does not affect the logical page size in any way.

Comments This command is only necessary when you are creating PostScript output. All CE commands which position items on the page use the top left corner of the page as the origin. PostScript uses the bottom left corner of the page as the origin, so the page size defined in this command is used to calculate the correct print position coordinates.

This command must be placed before any drawing commands, including SCCP.

Examples =SPPS 008.500 011.000;;=SPPS A4;;

STL – Set Text Line

Purpose To set a text string in the font specified and print it at the Current Print Position.

Syntax =STL••font•text;;

Where font is the reference to the required font to be used. The reference can be either the font name itself or a number in the range 1-99 (inclusive) which is the index into the Font Metrics table of the font required. Any number outside this range is assumed to be a font name.

text is the text to be printed.

Effects This command sets the text specified in the font referenced by the font identifier and prints it at the Current Print Position. All text is printed as a single line with no line breaks. Strings which are too long simply run off the page.

Example =SCPP 001.000 001.000;;=STP 0;;=STL X0T05500 Page 1 of %@<PageTotal>;;


STP – Set Text Presentation

Purpose To set the orientation of text in subsequent STL commands to the direction (orientation) specified.

Syntax =STP••orientation;;

Where orientation is the required orientation, which may be ‘0’, ‘90’ or ‘270’.

Effects This command defines that text in a following STL command should be printed in the orientation specified.

Comments 180° is not supported.

Example =SCPP 001.000 001.000;;=STP 90;=STL X0T05500 Page 1 of 2;;

76 Programming PCE

Control File SampleThis example of a PCE control file is intended to post-process a single Xerox Metacode file. The host system is assumed to be Windows.

The objectives of the application are to replace certain predefined strings with information from the appropriate records in a journal file and also to add a barcode to each page. The amended pages are output to a new Metacode file ready for printing.

EMFE has generated the Metacode file that is input to the application and also generated a five-field journal file that references each customer who is to receive a bill.

declare <N>;declare <Done>; // this is TRUE when processing is donedeclare <Counter>; // pages per statementdeclare <Input>(5); // journal data is read into this 5 cell arraydeclare <CustID>; // processed journal datadeclare <PageCnt>;declare <SFPage>;declare <CCPage>;declare <OCPage>;declare <APage>; // input data is stored heredeclare <BarCode>; // holds barcode string

declare procedure <Main> is main;

begin procedure <Main>;// open the Metacode datastreamopen "APPLIC1.MTC" for input as file 0 wsmeta/metacode;// open the journal file associated with this datastreamopen "APPLIC1.JRL" for input as file 1 line/delimited(32);// open an output fileopen "NEW.MTC" for output as file 2 wsmeta/metacode;

// loop for each customer...begin loop; // read the journal file entry for this customer let <N> = 5; read <N> items from file 1 into <Input>; // stop if journal doesn’t contain 5 fields let <Done> = <N> NE 5; exit loop when <Done>; // hence journal read 5 entries as expected // store the customer ID from the first entry let <CustID> = <Input>(0);

// copy the remaining 4 journal entries into named vars. let <PageCnt> = <Input>(1); let <SFPage> = <Input>(2); let <OCPage> = <Input>(3); let <CCPage> = <Input>(4);

Control File Sample 77

// convert PageCnt into a number let <Counter> = value <PageCnt>;

// repeat for each page in statement... begin loop;

// don’t process a statement with no pages in it let <Done> = <Counter> LE 0; exit loop when <Done>;

// read a page of the statement read 1 page from file 0 into <APage>;

// quit if nothing to process let <Done> = <N> EQ 0; exit loop when <Done>;

// perform the text substitution overwrite "??PN??" in <APage> WITH <PageCnt>; overwrite "??SF??" in <APage> WITH <SFPage>; overwrite "??OC??" in <APage> WITH <OCPage>; overwrite "??CC??" in <APage> WITH <CCPage>;

// generate the barcode string read 1 items from file 1 into <JournalData>; let <BarCode> = barcode 3of9 using <CustID>;

// add a new text line (barcode string) to the page begin ce into <APage>; =SCPP 001.500 002.500;; =STP 90;; =STL BAR3O9 %@<BarCode>;; end ce;

// output the processed data write 1 items into file 2 from <APage>;

end loop;end loop;

end procedure;

78 Programming PCE

HTML Deployment

As with all other supported datastreams the HTML output produced by DOC1 is created as a single stream containing all the pages generated by the application. The individual pages cannot be browsed without subsequent manipulation.

The HTML pages and associated resources are contained within an XML structure to allow the identification and separation by a user provided system. The use of XML means that the DOC1 ’PAK’ file as this is known can easily be parsed using a range of publicly available utilities.

XML (EXTENSIBLE MARKUP LANGUAGE) PROVIDES A COMMON METHOD OF DESCRIBING DATA FOR INTERNET AND OTHER APPLICATIONS AND IS PUBLISHED AND CONTROLLED BY THE WORLD WIDE WEB CONSORTIUM (W3C). DETAILED INFORMATION ABOUT XML OR HTML IS OUTSIDE THE SCOPE OF THIS DOCUMENT BUT THE USER MUST HAVE A GOOD UNDERSTANDING OF BOTH TO CREATE A CUSTOM EXTRACTION AND PUBLISHING MECHANISM.

To use DOC1 HTML output as part of a web server system you will need to provide a mechanism for extracting, storing and cross-referencing the pages and any resources they require. EDU provides a simple file-based version of this mechanism which can be used to access the DHMTL pages to assist with application development. Refer to the Production Guide for details.

Extract and deployment systems need to do at least the following:

• extract the HTML pages as separate files to your database/file store and log the relevant identifiers so they can be indexed by your web server system.

• extract any chart data objects as separate files to your database/file store at the location specified in the EMFE INI file.

• extract the line and box vector graphics as separate files to your file store at the location defined in the EMFE INI file

• make any static image files referenced by the application available to the web server at the location defined in the EMFE INI file

• access the relevant HTML pages via their logged identifiers when a display request is made.

Note that where charts are used the DOC1 Graphics Applet will also need to be stored in the resource location defined to EMFE so that it can be downloaded on demand.

h

79

Groups and IdentifiersHTML pages within the PAK file are grouped at two levels:

The HTML pages produced by a single data document are stored within a document group.

One or more document groups are stored within an ‘account’ group. All sequential documents sharing the same XML attribute groupID will be placed in the account same group. The groupID attribute can be specified as the keyword parameter of the document attributes object when designing the application in the ALE. If this is omitted a default groupID is assigned by EMFE and each document will be stored in an individual account group.

All elements of the PAK file have unique identifier attributes which you can use to cross-reference and further customize your system as required. See “DOC1 HTML PAK file format” on page 83 in this section for details.

Webbrowser

HTML(XML PAK)

Presentation system

XML parser

Web server repository

File store only

Line & boxvector

graphics

DOC1 Graphics

Applet

Pages reference these files using the ResourceURL EMFE INI keyword

File store or database

HTML pages

Chart data objects

Pages reference CD objects using the location/method specified in

JDataURL EMFE INI keyword

Static images

For each HTML page created the deployment system will need to extract three different object types from the PAK file as indicated in the diagram.

The HTML pages themselves can be extracted to the location required by your presentation system. The two types of dynamically generated resources also created within the PAK must be extracted to the locations indicated by the relevant EMFE INI keywords.

Static images and the DOC1 Graphics Applet used to present charts are assumed by the HTML to be already present at the location indicated by the ResourceURL keyword in the HTML section of the EMFE INI.

The extraction routine will also need to build an index to the HTML files so they can be located by your presentation system. You can use the group, document and page ID attributes within the XML elements to do this and/or use a DOC1 journal file to supply additional references.

Pages index

DOC1journal

DHTML extraction and deployment model

80 HTML Deployment

Graphics handlingUnlike other DOC1 supported datastreams HTML has no concept of vector drawing and special methods need to be employed to deliver such elements to the client system.

Lines and boxes

Native DOC1 lines and boxes required by the application are created as independent vector graphic files (of type GIF) and included in the XML PAK as independent objects. A single object is not repeated and can be referenced by any number of HTML pages.

The HTML pages will reference these files at the URL specified as the ResourcePath keyword in the HTML section of the EMFE INI file.

Static images

In DOC1 terms these are the referenced elements that can be included in document objects.

As with lines and boxes the HTML pages will reference these files at the URL specified as the ResourcePath INI keyword.

DOC1 chart feature

Chart graphics are rendered dynamically on the client system by a Java applet supplied with DOC1 distribution material. The parameter data is passed to the applet either as meta-data within the HTML page itself or, where large amounts of data is involved, via a chart data object that is generated within the XML PAK by EMFE. The decision to produce an independent object is based on the JPThreshold setting in the EMFE INI file which specifies an upper size limit under which in-line data will be used.The chart data objects need to be extracted to database or file store locations that have been anticipated in the EMFE JDataMode and JDataURL keywords.

JDataMode can be either:URL – indicating a URL pathQuery – indicating a query string (for database look-up etc.)

JDataURL contains all or part of the URL path where the chart data objects can be accessed. It can include references to one or more XML attributes that are used to identify a specific resource.

REFER TO APPENDIX A IN THE PRODUCTION GUIDE FOR FULL DETAILS OF THESE KEYWORDS. THE INFORMATION ABOUT THE XML FILE FORMAT IN THIS SECTION PROVIDES DETAILS OF THE ATTRIBUTES WHICH CAN BE USED AS PART OF JDATAURL.

81

Mode URI Description

JDataMode = URL and...

DataURL = http://doc1/resources/&jdUID.dat Example resolution: http://doc1/resources/JD09AFG1.dat

use fully qualified path and jdUID as file name.

DataURL = &jdUID.dat use current path/default location

DataURL = http://doc1/&docUID/&pageUID/&jdUID.datExample resolution: http://doc1/d781122/p87487287/JD09AFG1.dat

use several unique IDs to provide full path

JDataMode = Query and...

JDataURL = http://doc1/scripts/getcd.cgi?&jdUIDExample resolution: http://doc1/scripts/getcd.cgi?getcd.asp?/jdUID=JD09AFG1

call to cgi script in the defined location using the jdUID attribute as the sole parameter.

DataURL = getcd.asp?/&pakUID&docUID&jdUIDExample resolution:getcd.asp?/pakUID=p87487287&docUID=d781122&jdUID=JD09AFG1

call to asp script in the current path/default location using several unique IDs as parameters.

Examples of how chart objects are referenced

82 HTML Deployment

DOC1 HTML PAK file format

The PAK file is an XML construct providing a container for HTML pages and associated resources along with a DTD that describes its structure

Elements and attributes:

dhtmlpak The overall structure of DOC1 HTML PAK file. Will always contain one or more group elements.

jobdata This will describe the environment in which the PAK was generateddate – System datetime – System timeplatform – System platform – Windows, MVS, UNIX, OS/400, OS/390.

group The ‘account’ level group structure. Contains zero or more document elements. Other elements – cpage, fpage, and docmap – are defined for future expansion. All sequential documents that share the same groupID attribute will be contained within the same group. If no groupID is available an account level group will be created for each individual document. attributes:groupUID – a unique identifier for the group generated dynamically be EMFE. This can be used to access the group by the extract mechanism.groupID – the group identifier. If the DOC1 application included a document attributes object the keyword provided as part of this will be used as the groupID. If not a unique identifier will automatically be assigned by EMFE.

document The document level group structure. Will contain one or more dhtmlpage elements. Can also contain zero or more img and jdata elements. Attributes:docUID – a unique identifier for the document generated dynamically be EMFE. This can be used to access the document by the extract mechanism.docID – a reference indicating the sequence of the document within the group.There may be other attributes relating to specific cross application requirements.

dhtmlpage Contains individual HTML pages. Attribute:pageID – a reference indicating the sequence of the page within the document.

graphic Contains individual line and box images as generated by EMFE. Attributes:imUID – a unique reference for the imageurl – the URL reference (built using ResourceURL INI setting)datalen – contains the number of bytes making up the img element (excluding carriage returns)

jdata Contains the data to be used as parameters when constructing a chart object with the DOC1 Graphics Applet. Attributes:jdUID – a unique reference for the objectdatalen – contains the number of bytes making up the jdata element (excluding carriage returns)

83

TOC Appears at the end of each document when document section bookmarks have been defined for the document. When used for DOC1 Present and DOC1 Pay, it is used to build a page navigator for documents. Otherwise it can be used to generate a bookmark structure for those intending to build their own web site map. Consists of Bmark tags which contain:name – is a reference namepageid – which page within doclref – position on the page

cpage, fpage, docmap Future expansion only. No relevant content at this time.

84 HTML Deployment

W o r k s ta t io n U ti l i t ie s

A number of command line utility programs are provided to supplement the features of the DOC1 design modules.

RTF2LDO – import RTFRTF2LDO will convert the text stored in one or more Rich Text Format (RTF) files into one or more document objects. In some bespoke applications DOC1RFC/RFL are used to compile these into production-ready resources for use with EMFE.

RTF2LDO constructs the document objects using controls specified by the user in a script file. References to image files can be included in the document objects as required.

Symbolic links can be imported from RTF files if required. RTF2LDO will search the RTF text for any strings that have the format of a symbolic link as defined in the DOE profile. The default for this format when DOC1 Workstation is installed is [name] but this can be changed by using DOE Settings options.

RTF2LDO either outputs a single file containing all the document objects generated (referred to as a BLOB file elsewhere in this section) or appends the output to an existing file if required.

Fonts in RTF are identified by a description, e.g. Helvetica 10 point bold. This description is not recognized by DOC1 so you must map all RTF fonts referenced in an RTF file to suitable DOC1 font references.

Two files are used to control RTF2LDO processing:

control script identifies the RTF files and associated images to be processed and supplies control information for the document objects to be created and the text elements they are to contain.

font equivalents file maps RTF font descriptions to font names acceptable by DOC1.

RTF2LDO is a batch program run from the command line of a PC running the DOC1 Workstation. It relies on the Workstation modules to be installed and configured for its correct operation.

85

Restrictions

Some features of RTF files are not compatible with the document object format. The following table lists the restrictions:

RTF feature Effects of importing into a document object

Fonts These must be mapped to an equivalent DOC1 font via the Settings notebook.

Text (Fields) All text paragraphs are placed within a single text element in the document object. The ‘first’ text field in the RTF file is used to supply the line spacing, measure and justification values. If page width has not been defined in the RTF file a default width of 8.5 inches is assumed i.e. text blocks will wrap if this measure is exceeded.

Headers & footers Header and footer text is included once only. The position of the text relevant to the other text elements is dependent on where the header or footer was defined in the RTF sequence.

Index text Ignored

Tabs Supported.

Styles Formatting information is not applied.

Tables Supported although some advanced line and cell positioning options may be ignored.

Colors Color settings are mapped to the closest equivalent DOC1 supported colors.

Margins Ignored. Left margins are dictated by the horizontal positioning parameters of TXTBLK commands in the control script. There is no concept of right margins in a document object.

Bitmaps If the image is "linked" (i.e. has an associated filename) an image referenced is created. If it is just an embedded image reference, it is ignored. Any image formatting options are ignored.

Borders Supported.

Shading Ignored.

Pagination Ignored.

Effects of downgrading when using RTF2LDO

86 Workstation Utilities

RTF2LDO control script format

The RTF2LDO control script consists of keywords and associated parameters. Keywords fall into two categories: those related to default settings for the document objects being created and those describing the document objects themselves.

Syntax:

;;Default settings followSEARCHPATH=PathName {PathName...};UNITS={INCH|MM};SIZE=Size[Units] Size[Units];LINESP={INCH|MM|CM|LPI|POINTS};LINESPV=Size[Linesp];MEASURE=Size[Linesp];JUST={LEFT|RIGHT|CENTRE|FULL|SILLY};;DO description followsBEGIN;LOOKUPKEY=String;SIZE=Size[Units] Size[Units];IMAGE=[Pathname]Filename Size[Units] Size[Units] [Size[Units] Size[Units]];TXTBLK=[Pathname]Filename [Size[Units]] [Size[Units]],MEASURE=Size,LINESP={Size[Linesp]|AUTOMATIC},JUST={LEFT|RIGHT|CENTRE|FULL|SILLY};END;

Data types:

PathName is a valid path name, e.g. D:\RTFFILES.

Size is a measurement which is always expressed as a number with three integral and three decimal places and is in the range 000.000 - 999.999.

Units is a unit of measure type from the list valid for the UNITS keyword.

Linesp is a unit of measure type from the list valid for the LINESP keyword.

String is an alphanumeric text string.

Keywords and parameters:

SEARCHPATH PathName is the default directory for the location of RTF files. You can specify up to 32 path names each separated by a space but note that the maximum record length is 256 characters. The entry may be split across multiple lines but any line break must be at the completion of a full directory path. If multiple path names are specified the directories listed will be searched sequentially. The first file with a name matching that specified in the document object description will be used. No further search will be carried out.

RTF2LDO – import RTF 87

UNITS Specifies the unit of measure for all size, coordinates and line measurements (but not line spacing in text blocks). This can be used as a default setting if specified before the first document object description. Options are:INCHMM - millimetersCM - centimeters

SIZE The size of document object to be generated. This can be used as a default setting if specified before the first document object description. The first Size parameter is the width (X direction) and the second is the height (Y direction) of the document object. You may specify a unit of measure using the options from the UNITS list immediately after the parameter or accept the default specified in UNITS. It is permissible to state different units of measure for the width and height.The values must be within the maximum size of a document object which is 28 inches by 28 inches.

LINESP Specifies the unit of measure for all text block line spacing. This can be used as a default setting if specified before the first document object description. Options are:INCHMM - millimetersCM - centimetersLPI - lines per inchPOINTS - 72 per inch (approx.)AUTOMATIC - line spacing is appropriate for the largest font used on a particular line. This option is the default.

LINESPV Size is the default line spacing to be used for text blocks in the document objects to be generated. You may specify a unit of measure using the options from the LINESP list immediately after the parameter or accept the default specified in LINESP.

MEASURE Size is the measure at which a text block in the document object will wrap to a new line (assuming that full justification is being used). This can be used as a default setting if specified before the first document object description. You may specify a unit of measure using the options from the LINESP list immediately after the parameter or accept the default specified in LINESP.


JUST The justification to be applied to a text block. This can be used as a default setting if specified before the first document object description. Options are:LEFT - this is the default setting. Text lines up to the left edge of the first character in the text. RIGHT - text lines up to the right edge of the right-most character in the text element. CENTER - text is centered between the right and left edges of the text element. FULL - text except for the last line is justified to both the right and left edges of the text element. A MEASURE setting must be specified if this option is used.SILLY - text including the last line is justified to both the right and left edges of the text element. A MEASURE setting must be specified if this option is used.

BEGIN Marks the start of a document object description. All subsequent keywords are considered to belong to the same description until an END keyword is encountered.

LOOKUPKEY String is the look-up key is used when referencing the document object by key name when building an Application in the ALE.

IMAGE Filename is a reference to an image file (in the DOE this is a DOC1 LarMeta format .LIM file) which will be included in the document object. If a path is not coded RTF2LDO will search the directories specified in the DOC1PATH system setting with the first occurrence of the specified file being used. Note that DOC1PATH is generated when DOC1 Workstation is installed.

The first two Size parameters relate to the X (horizontal) and Y (vertical) offsets respectively from the top left corner of the image as it will appear in the DOE. The second two Size parameters provide optional default dimensions for the image and are also X and Y respectively. You may specify a unit of measure using the options from the UNITS list immediately after the parameters or accept the default specified in UNITS. It is permissible to state different units for the width and height.

TXTBLK Filename indicates an RTF file, the text from which is to be converted to the document object being described. A file extension of .RTF is implicit. This may be preceded by a Pathname if the file is not located in a directory indicated by SEARCHPATH.The two Size parameters relate to the X (horizontal) and Y (vertical) offsets respectively from the top left corner of the first text block generated as it will appear in the DOE (multiple text blocks may be generated if the RTF contains multiple fields). You may specify a unit of measure using the options from the UNITS list immediately after the parameters or accept the default specified in UNITS. It is permissible to state different units of measure for the X and Y offsets.The values must be within the maximum size of a document object which is 28 inches by 28 inches.


Notes:

Each keyword/parameter must start in column 1 and be terminated by a semicolon.

Default settings keywords must appear before any document object descriptions.

The TXTBLK keyword can have one or more sub keywords/parameters each of which must be preceded by a comma.

Comments can be included as a separate line commencing with a double semicolon.


Example:

;;************Default settings*******************SEARCHPATH=C:\RTF\MSGS E:\XMSGS;UNITS=MM;LINESP=PT;LINESPV=11;MEASURE=006.000IN;SIZE=007.000IN 050.00;JUST=LEFT;;;****** 1st document object***************BEGIN;LOOKUPKEY="00000001";SIZE=030.000 050.000;IMAGE=LOGO 005.000 005.000 012.700 012.700;TXTBLK=RTF001 005.000 010.000,MEASURE=020.000,LINESP=008.000,JUST=FULL;TXTBLK=RTF005 005.000 030.000,MEASURE=020.000,LINESP=012.000,END;;;******2nd document object*************BEGIN;LOOKUPKEY="00000002";SIZE=177.800 100.000;IMAGE=GPIANO01 005.000 005.000 025.400 025.400;TXTBLK=TXTMSG01,MEASURE=080.000, LINESP=012.000,;TXTBLK=TXTMSG02 005.000 050.000,MEASURE=080.000,LINESP=012.000,JUST=LEFT;END;;;*****3rd document object**************BEGIN;LOOKUPKEY="00000003";TXTBLK=F:\NEWMSGS\RTFFILES\MSG00009 045.000 005.000,MEASURE=090.000,LINESP=008.000LPI,JUST=FULL;TXTBLK=MESS01 005.000 030.000,MEASURE=130.000,LINESP=AUTOMATIC,JUST=CENTER;END;;;*****4th document object*************BEGIN;LOOKUPKEY="00000004";SIZE=070.000 050.000;IMAGE=PHONE01 007.000 007.000 012.700 025.400;TXTBLK=RTF0002 050.000 007.000;END;


RTF2LDO Font Equivalents file format

A font equivalents file consists of font descriptions as used by RTF mapped to font references in DOC1 format.

Syntax:

"FamilyName" PointSize [bold italic] = Doc1Font...


FamilyName Is the name by which a font used in an RTF file is known such as "Arial".

PointSize Is the point size of the RTF font. May be up to 36 points.

bold italic You may specify one or both of these keywords to indicate the style of the RTF font. If both are omitted the font is assumed to be "normal".

Doc1Font Is a reference to a LarMeta font which is to be defined as the equivalent of the RTF font. You may specify either a coded font name or a character set/ code page pair. Do not code file extensions.

Example:

"Arial" 10 bold italic = X0A1750C"Monospaced" 12 = C0A005500:T1DCDCFS"Helvetica" 8 italic = FONT01P


RTF2LDO under Windows and Unix

Purpose:

Converts the text stored in one or more Rich Text Format (RTF) files into one or more document objects.

Preparation:

RTF2LDO is supplied as part of DOC1 Workstation distribution material and will be installed in the [DOC1path]/DLLEXE directory. The program must be able to locate and use other modules in this directory as required.

By default RTF2LDO will append the generated output to the target file unless you specifically code the overwrite option.

RTF2LDO is executed from the command line of an operating system window.

Syntax:

RTF2LDO [-o] [-s] [-w{1|2|3}] FeqFile.FEQ CScript Blob

Parameters:

-o indicates that the Blob output file will be overwritten or a new file of the specified name created if it did not previously exist.

-s suppresses information messages.

-wX sets the warning level where X=:1 - stop when error encountered and delete document object file2 - continue if error encountered and delete document object file3 - continue if error encountered and retain document object file

FeqFile is the path/filename of a font equivalents file (with extension FEQ) which containing entries for all fonts referenced by the RTF files to be converted.

Cscript is the path/filename of an RTF2LDO control script

Blob is the path/filename of the output file

Example:

RTF2LDO -o -w2 FONTSREF.FEQ APP1MSGS.LIS F:\BLOBDATA\APP1LDOS.DAT


LOL2LDO – deconstructs document object library

This utility takes an existing document object library in the format used by DLM (file extension LOL) and creates independent document object files in a format suitable for databases supporting binary large objects (BLOBs). These are used in some bespoke DOC1 solutions where DOC1RFC and DOC1RFL are used to merge and build these files into a usable EMFE ready library on the host system.

LOL2LDO can process LOLs with multiple members and multiple sections. You can also specify that multiple LOLs are processed by a single execution of LOL2LDO. However, when deciding how much data to export to a single blob bear in mind that the only way of identifying individual document objects within the file is via its key name and that there is no method of retaining section or member references.

Output File Names

Output files are named automatically by LOL2LDO and are placed in the same directory from which the program was executed. The actual files produced depends on the consolidation level specified. File names are based on the base name of the LOL or LIS file as specified on the command line. For consolidation levels 2 and 3, the base name may be truncated to allow for the unique part of the name as indicated below:

Level 1 - a single file is output as Basename.LDO.

Level 2 - one file is generated for each member in each section of the LOLs being converted. These will have filenames in the format:BaseSsMm.LDOwhere Ss is the section number from which the member was extracted; Mm is the member number; and Base is the base name truncated as necessary to allow for Ss and Mm. The section and member numbers are always at least two characters padded with a leading 0 if necessary.

Level 3 - one file is generated for each section in the LOL’s being converted with each containing the appropriate members. The filenames have the format:BaseSs.LDOwhere the name components are the same as for Level 2.


LOL2LDO under Windows

Purpose:

Converts an existing document object library to the document object (blob) file format.

Preparation:

LOL2LDO is supplied as part of DOC1 Workstation distribution material and will be installed in the [DOC1path]/DLLEXE directory. The program must be able to locate and use other modules in this directory as required.

The program is executed from the command line of an operating system window.

Syntax:

LOL2LDO [-a] [-s] [-c{1|2|3}] [-l] {SingleLol|lolList.LIS}

Parameters:

-a indicates that the document object generated will be appended to the Blob.LDO file. If this option is not coded the Blob output file will be overwritten or a new file of the specified name created if it did not previously exist.

-s suppresses information messages.

-cX sets the consolidation level where X=:1 - all members are written to the same document object file2 - each member is written to a separate document object file3 -all members from a particular section are written to the same document object fileSee below for output file naming conventions.

SingleLol is the path/filename of a single LOL file to be converted.

LolList is the path/filename of a text file (with extension .LIS) that contains a list of LOL files to be converted.

A list file should simply contain the path/filenames of the LOLs to be converted with each entry on a separate line.

Examples:

LOL2LDO -a -c1 ALL.LOLwill produce a single output file named ALL.LDO

LOL2LDO -a -s -c2 LOLLIST.LISwill produce multiple output files such as LOLL0001, LOLL0002, LOLL0101, etc.

LOL2LDO -c3 C:\DOC1\ALLDOJS.LOLwill produce multiple output files such as ALLDOJ00, ALLDOJ01, ALLDOJ03 etc.

LOL2LDO – deconstructs document object library 95

Other Utilities

MAKEBMP – converts images to bitmaps

Purpose:

The MAKEBMP utility allows you to convert GIF, TIFF, JPEG, and PCX image formats to the bitmap (BMP) format supported by the DOC1 Workstation. Note that this function is also incorporated in DOC1PJM. See the DOC1 Designer's Guide for details.

Preparation:

The utility runs from a Windows command prompt.

Syntax:

MAKEBMP [/R Res] InImage OutBmp

Parameters:

Res select this optional parameter to indicate the resolution of the image (e.g. 72, 300, 600) when this information is not stored as part of the input BMP itself.

InImage is the path/filename of the image you wish to convert. The filename must include the appropriate extension. A path identifier may optionally precede the filename. If not specified the file is assumed to be in the current directory.

OutBmp is the path/filename of the new bitmap file to be generated. The filename must include the bitmap (BMP) extension. A path identifier may optionally precede the filename. If the file already exists the command will abort without replacing the existing file.

Examples:

MAKEBMP /R 300 c:\doc1\resource\image.tif image.bmpMAKEBMP image.pcx image.cmpc:\doc1ws\dllexe\MAKEBMP image.jpg image.bmp


DOC1GFC – Changing font references globally

Purpose:

This utility allows the fonts specified in one or more of the files that make up a set of DOC1 Workstation Resource Files (WRFs) to be amended globally. For the purposes of this utility a WRF set consists of the Application Rules file (.LAR) and the referenced Document Object Library (.LOL) plus any overlay resources (.LOMs) referenced by the WRFs or associated files such as Look Information.

Preparation:

To run the font change utility open an operating system window and use the following command format:

Syntax:

DOC1GFC [-rparms] filename oldfont newfont [section]

Parameters:

parms are optional processing parameters. Specify one of the following:A – process the complete WRFs set associated with this file. If the filename specified is an Application Rules file the program will search this file plus the referenced Document Object Library, the Look Information (if any) and all overlays associated with any of these resources for font references. If filename is a Document Object Library only this file plus any associated overlays will be searched.F – search only the file specified by filename plus, if filename is an Application Rules file, the referenced Document Object Library.S – search only the document object library section indicated in the final parameter (section)

filename is the path/filename of either an Application Rules file (.LAR) or a Document Object Library (.LOL). The filename must include the appropriate extension. A path identifier may optionally precede the filename. If not specified the file is assumed to be in the current directory.

oldfont is the font identifier to be amended. See below for the required format.

newfont is the font identifier to be used to replace all occurrences of oldfont. If required, you can replace references formatted as a character set/code page with a coded font name or vice versa.

section the name of a section within document object library filename.

Examples:

DOC1GFC -rA C:\DOC1\RESOURCE\APPLIC1.LAR FONT01 FONT02DOC1GFC -rS APPLIC1.LAR X0FONT01 C0FONT02:T1FONT01 EnglishDOC1GFC -rF C:\DOC1\RESOURCE\APPLIC1.LAR X0FONT01 FONT01P

Other Utilities 97

To use the font change utility effectively you must be aware that most fonts used in the DOC1 environment can be referenced either by a coded font name or a character set/code page pair. Coded fonts will have a single name whereas character set/code page pairs have the format charset:codepage. Note the colon that separates the two elements – this is a required character for this format. Depending how you select your fonts it is possible that the same target font is referred to by both types of format within the same set of WRFs. DBCS fonts can only be referenced by coded font name.

If you are not sure of the reference being used for a particular font you can use the features of DOC1 workstation to identify it.

The font used for a particular text element in a document object can be identified by selecting it in the document object editor. When a character is selected in the text entry field of the Text window, the appropriate font reference is displayed.

The appropriate references are displayed in the ALE as part of an objects full logic map description.

Font References in DOC1 Workstation Resource Files


DOC1GLC – changes language attributes globally

Purpose:

DOC1GLC allows you to change or set the language and automatic hyphenation attributes of a document object. It can be used for assigning these attributes to older document object libraries that do not have them (i.e. they were created using DOC1 3.0M8 or earlier) and can also be used for changing existing settings of later document object libraries.

You can define attributes for text elements in an entire document object library, in sections within the library or in specific document objects.

Preparation:

If you are changing an older document object library that does not yet have these attributes, note that as well as assigning language and automatic hyphenation as specified in the command line, all other text elements in the library will be assigned the default values of ‘no proofing’ and ‘automatic hyphenation off ’.


Syntax:

DOC1GLC -L filename [-C [oldlang] newlang] [-HY {YES|NO}] [-S section -I objectID]

Parameters:

-L filename is the path/filename of the document object library to be updated.

-C is optional and identifies the code of the old and new languages. See the table below for a list of the language codes.If -C is not specified DOC1GLC will list the language and automatic hyphenation setting of each text element in the selected document objects.The parameters are:oldlang – this is optional and identifies the language to be replaced for the specified document object(s). The default is ‘0’, i.e. ‘no proofing’, (or ‘no language’ for older LFLs).newlang – is the language to be applied to text elements in the specified document object(s).

-HY is optional and enables or disables automatic hyphenation for the specified document object(s). If the -HY flag is not specified, existing hyphenation settings will not be altered.Options are:YES – turn automatic hyphenation onNO – turn automatic hyphenation off.

-S section is optional and identifies the section name(s) within the document object library to be changed. If the section name contains any spaces, then each space must be replaced by an underscore character (_). You can specify a list of sections, separated by spaces. Note that this parameter is case-sensitive.If -S is not specified, all sections are changed.

Other Utilities 99

-I objectID is optional and is the ID(s) of the document object within the specified section(s) to be changed. The ID can be found in the Document Library Manager. You can specify a list of objects separated by spaces, or a range of objects separated by a dash 0(-). The range ‘-x’ will change objects up to and including ‘x’. The range ‘y-’ will change objects from ‘y’ to the end.If not specified, all relevant objects within the specified sections are changed.

Language codes:

Examples:

Set ‘UK English’ and ‘no hyphenation’ to the entire document object libraryDOC1GLC -L oldfile.lol -C 1Set ‘US English’ and ‘hyphenation on’ to the section ‘Second Section’ and ‘no proofing’ plus ‘no hyphenation’ to all other sectionsDOC1GLC -L oldfile.lol -C 2 -HY YES -S Second_SectionLists all the attributes of the document object libraryDOC1GLC -L c:\appl\cust\newfile.lolChanges ‘German (Old)’ to ‘German (New)’ in all objects and assigns ‘no hyphenation’ to, document objects 0,1,2,3 and 10 in sections ‘Second’ and ‘Third’DOC1GLC -L newfile.lol -C 11 10 -HY NO -S Second Third -I 0-3 10

Brazilian, Portuguese 27Catalan 18Danish 20Dutch 1996-GB 3Dutch 1996-VD 4Dutch-VL 5Finnish 25French, New (etymological hyphenation) 6French, New (phonetic hyphenation) 8French, Old (etymological hyphenation) 7

French, Old (phonetic hyphenation) 9

German, New 10German, New (old hyphenation) 12German, Old 11Icelandic 26Italian 16Norwegian 21Norwegian (morphological hyphenation) 22Portuguese 19Spanish 17Swedish (-CK hyphenation) 24Swedish (C-K hyphenation) 23Swiss German, New (old hyphenation) 14Swiss German, Old (new hyphenation) 15Swiss German, Old (old hyphenation) 13UK English 1US English 2"No proofing" 0


MERGELAR – merges multiple application rules

Purpose:

The MERGELAR utility allows the logic from multiple Workstation application rules files to be merged together into a single application rules file. It is primarily intended for use with large DOC1 applications that pre-date the Sub-document feature and where individual document layouts have been stored in independent application rules for ease of editing.

The following differences between application rules files are catered for by the utility:

• the order of document object libraries referenced by the various application rules is not important and not all libraries that will be referenced in the merged application rules need to appear in every source rules file.

• varying journal objects can be included.

Preparation:

Application rules files must conform to the following rules if they are to be combined using this utility:

• the name of the data format associated with each application rules must be the same;

• every document layout object that will be included in the merged application rules must be based on a unique data document type;

• the resources required by the merged application rules do not exceed the limits set for a regular application rules, e.g. the maximum number of document object libraries used by the application is still 32.

• Sub-document files cannot be merged.


Syntax:

MERGELAR target_lar source_lar_1 source_lar_2 [source_lar_3...]

Parameters:

target_lar is the path/filename that will receive the merged logic. If it exists it will be overwritten.

source_lar_x are two or more existing application rules files.

Example:

MERGELAR c:\doc1\resource\new.lar dl1.lar dl2.lar d:\testdoc1\dl3.lar

Other Utilities 101

Preview API

The Preview API (Application Programming Interface) is a group of services which allows a Windows client application to use the features of the ALE Preview facility. The services are accessed by calling a range of C language functions provided with the API.

The main control of the Preview API environment is the preview object. API functions allow you to associate an object with an existing set of DOC1 Resource Files and a suitable application data file. Other functions allow you to process the application data using the loaded resources and then present the resultant composed document ‘pages’ in a workstation window using the Preview screen driver.

A preview object can use either logical rules’ or engine rules’ to provide the application controls. These are the equivalent of the Workstation Resource Files (WRF’s) or Host Resource Files (HRF’s) that are referred to throughout the rest of the DOC1 product documentation.

Logical rules are a binary format of DOC1 resource files and are used by DOC1 workstation products to store the controls that make up an application design. These are an application rules file (with extension .LAR), a data format file (.LDF) and one or more Document Object Libraries (.LOL). Before the API can process data using WRF’s they must be converted to HRF format. As this conversion can take some time you may want to save converted files to avoid the need to do it again for a future API session.

Engine rules are the text based equivalents of the logical Rules which, when stored as HRF’s, are used to actually process application data in the production environment. When stored on the workstation these files have extensions .EAR (application rules) .EOL (document object library) and .EDF (Data Format).

This section assumes that the reader has experience of programming the NT interface or the Win 32 API using the C.

EnvironmentThe services controlling the actual presentation of document pages interact directly with the functions controlling the ALE Preview feature and an API application will therefore need to be compiled in the same environment as the DOC1 Workstation.

103

Required Software Products

DOC1 Workstation and API programs have been built using the Microsoft Visual C++ v6 compiler and associated MSDN tools. You will need the same or a compatible environment to build an application using the API.

DOC1 Resources

The API interfaces with program modules provided with regular DOC1 Workstation distribution material. You will need to ensure that the Workstation has been installed and that the program modules are available to your API program.

Files directly related to the API are provided separately. You will need to copy these files to an appropriate directory on the workstation(s) intending to use the API, typically one of the directories listed under PATH in the system environment.

The files of primary importance to the API programmer are:

Header file – CEVAPI.H. This is used by the compiler and provides information about type definitions, data structures and function calls. It is used in the creation of .OBJ files. It allows the user to code calls to the API and access public data structures.

Library file – LADCEV.LIB. This is used in the linking of .OBJ and .LIB files to create an executable and DLL.

DLL file – LADCEV.DLL. This is used to access DOC1 DLLs which are not directly available to the API user. (Note that this file is distributed with the standard workstation install media.)

Sample file – SAMPLE.C. This file contains sample code that can be used as reference when building your own application.

About DOC1 Documents and PreviewA DOC1 document contains the ‘pages’ generated by processing a single data document against the appropriate document layout logic as defined in the application rules. If your application has multiple document layouts, each will take a different type of data document as its input and each will produce a style of output document as dictated by the logic for the appropriate document layout.

When documents are generated using the Preview API certain attributes are stored with each document to enable the client application to identify the type of data document associated with a particular output document. You will need to use ALE to establish the values assigned to these attributes.

104 Preview API

The various types of data document expected by an application are specified in the data format file and are known as data document definitions. Each data document definition can be identified by two attributes:

Key Field This is the contents of the data format Key Field for the record that marks the start of a particular data document definition.

Key ID This is the internal identifier automatically assigned to each data document definition by the data format Editor (DFE). You can view the identifiers used by looking in the Record Descriptor Area of the DFE or the Sample Data Browser window of the Application Layout Editor (ALE).

Additionally, the document layout that is associated with a particular data document definition in the ALE can be identified by attribute:

Label The user-defined description given to a document layout via the Label field of the Document layout dialog box in the ALE.

105

General Principles and Function Overview

InitializationA Presentation Manager thread must first be initialized in the normal manner using the appropriate functions, such as WinInitialise and WinCreateMsgQueue. This may have already been done in another part of your application, but remember to make a note of the HAB and HMQ returned by these calls as you will need to supply them to Preview with the first API function CevInitAPI. This initializes the API as a valid DOC1 process before any other functions can be carried out.

Once initialized, the process will remain valid until the terminate service has been requested or until it detects that the API thread/process is no longer valid.

The API is only available from within the thread/process in which it was initialized. Multiple instances of the API are not allowed.

The path where preview creates temporary work files can be set by using the CevSetEnvironment function

Creating Preview ObjectsEach preview object must first be loaded as a registered object using the CevCreateObject function. This creates a new preview object with a user defined ID that will be included in messages to the client applications window procedure. This function will return a unique object handle, which identifies the object you are working with and which must be specified when requesting any API service. The handle is valid until it is destroyed either by a specific request to the CevDestroyObject function or the API receives a terminate request, upon which all existing handles are destroyed.

Associating control FilesOnce a valid handle has been obtained then the functions CevUseLogicalRuleFiles or CevUseEngineRuleFiles can be used to associate the required application control files with the object. For logical files the application rules has file extension .LAR, the document object library has extension .LOL (or LFL in earlier version) and the data format has extension .LDF. For engine files the set has file extensions .EAR, .EOL and .EDF.

When referencing Document Object Libraries, be aware that logical rules may need to use multiple Libraries (LOLs) if the application has been designed this way. In this instance you will need to use CevAddDocumentObjectLibrary to add the names of additional Document

106 Preview API

Object Libraries to the existing LOL as specified by CevUseLogicalRuleFiles. Engine rules only use a single document object library (EOL) which may be the product of merging multiple LOL’s when the application was generated on the DOC1 Workstation.

Unless the logical files have been previously generated by an earlier Preview API session, they must be converted to Engine files using the CevConvertRules function. If the Engine files are already available you can omit this conversion.

Generating Composed OutputHaving created or located the engine rule files, CevExecuteRules can be used to process an application data file using these controls. To process properly, the application data file must conform to the data format currently loaded and consist of at least one complete data document suitable for a document layout defined in the application rules. Note: a data document is the data that makes up all of the records required for a single iteration of the logic for a document layout. Applications often have multiple document layouts and, as a result, use different types of data documents.

This function will generate the controls required to compose the appropriate document ‘pages’ and store them with the preview object for later presentation.

Both CevConvertRules and CevExecuteRules can take up a significant amount of time and, as a result, are executed on a separate thread. Notification messages regarding the progress of these functions will be sent as WM_Control messages to the status window (hwndStatus). Refer to the “Notification Codes” on page 127 for more information about these messages. Due to this notification mechanism a WndProc for the specified window must be provided to process the notification messages.

Identifying Required PagesA preview window displays a single document ‘page’ at a time. Before any display can take place the required page number must be set via the CevSetActivePage function. You can use CevQueryActivePage to query the document type and document/page numbers of the active page.

To help you identify the parameters required by CevSetActivePage you can use a number of ‘query’ functions. Use CevQueryDataDocCount to establish the number of different document types supported by an application and use the CevQueryDataDocKeyId or CevQueryDataDocLabel functions to establish the identifier required for a particular document type.

Use CevQueryDocCount to establish the maximum number of documents of a particular type stored with a preview object and CevQueryPagesInDoc to establish the number of pages in any document.

General Principles and Function Overview 107

Creating a Preview WindowThe preview object must be associated with a presentation window to enable the screen display of the document ‘pages’ it holds. A preview window can be created with a set of initial attributes using the CevCreateWindow function. Note: this function behaves in the same way as the CreateWindow function and you can refer to the appropriate developers toolkit documentation for details of window behavior, expected parameters, etc.

A preview window has no frame or menu. For most applications some of the ‘page’ will not be visible in a typical window and the use of scroll bars is required. These are one of a number of customizable features, the current settings for which can be established via the functions CevQueryGridInfo, CevQueryResolution, CevQueryRulerInfo and CevQueryScrollInfo. You can change the settings for these features using the CevSetGridInfo, CevSetResolution, CevSetRulerInfo and CevSetScrollInfo functions. You can also determine the background color of the window using CevSetBackColor.

Setting grid information requires the use of the DOC1 internal unit of measure - LUNITS. An LUNIT is a resolution independent unit of measure used in DOC1 resource files wherever positioning and measurement within document pages is required. To convert other units of measure to or from LUNITS you can use the CevDoubleToLu and CevLuToDouble functions.

Displaying PagesTo actually display the page specified by CevSetActivePage, associate the preview object with the appropriate window handle via the CevUseObject function. It is possible to associate one object with several windows, but each window can only have one object. This enables different pages of the same document to be viewed simultaneously.

If you update the customizable preview window settings or load a new page via CevSetActivePage the display in the presentation window is updated automatically.

Proof PrintingThe Cevproof service provided allows all or part of a document to be sent to a specified printer. Note that proof printing can be time consuming and memory intensive.

108 Preview API

DebuggingUse the CevStartTrace function to specify that trace information about the use of Preview API services is written to file. Use CevStopTrace to turn off this feature.

Unloading Objects and Terminating API ServicesA preview object can be dissociated from a preview window at any time using CevDestroyObject. This function frees all resources associated with the object.

To close down the Preview API, use the CevTerminateApi function. The normal procedures to destroy any active windows must then be carried out.

Function Return CodesError handling is assisted by published codes being returned from all functions.

General Principles and Function Overview 109

Function ReferenceThe various types used in the function prototypes are defined in CEVAPI.H. They are explained in “Types and Data Structures” on page 129.

All ‘standard’ data types such as ULONG, SHORT, etc. are specified in header files provided with the Developers Toolkit.

Hungarian Notation has been used when creating the names of most parameters.

CEVRET will be given the return code from each function call. A list of possible return codes is given for each function in terms of constants specified in CEVAPI.H. An explanation of these codes is given in “Return Codes” on page 126.

APIENTRY is the type definition indicating the required linkage convention for the function call. This resolves to _system when using recommended compiler. Refer to the information provided with the compiler for a complete description of this identifier.

HCEV is a handle to a preview object and used by various functions.

HWND is a handle to a window. Refer to the Developers Toolkit for more information on windows, including parentage and ownership issues.

CevAddFirmDataLibrary

Synopsis Adds the name of a document object library to the existing list as specified by CevUseLogicalRuleFiles and previous calls to CevAddFirmDataLibrary.

It must be issued after CevUseLogicalRuleFiles and before CevConvertRules.

Prototype CEVRET_System CevAddFirmDataLibrary (HCEV hcev, PSZ pszlol)

Parameters hcev Handle to preview object

pszlol Pointer to the full filename of a document object library in ‘logical rules’ format or NULL

Return Codes CEVRET_NOERRORCEVRET_NOT_INITIALIZEDCEVRET_INVALID_HANDLECEVRET_INVALID_PARAMETERCEVRET_ERRORCEVRET_TOO_MANY_FIRM_DATA_LIBRARIES

110 Preview API

CevConvertRules

Synopsis Creates engine rules from the logical rules stored with the identified preview object. The resultant engine rules are also stored with the object for the duration of its existence.

The process of converting the rules can take a significant amount of time (up to several minutes) depending on the complexity of the application rules being processed. Therefore the function will complete and issue a return code while the conversion process continues as a separate thread.

Notification messages regarding the progress of the conversion will be sent as WM_Control messages to the status window (hwndStatus). While the client application can continue with other activity while the conversion is taking place, no other functions relating to the preview object should be executed until CEVNOTIFY_CONVERT_FINISHED is issued to the status window. Refer to “Notification Codes” on page 127 for more information about these messages.

Prototype CEVRET_System CevConvertRules (HCEV hcev, HWND hwndStatus)


hwndStatus Window handle to receive WM_Control messages

Return Codes CEVRET_NOERRORCEVRET_NOT_INITIALIZEDCEVRET_INVALID_PARAMETERCEVRET_CONVERT_ERROR

CevCreateObject

Synopsis Creates a new (empty) preview object and assigns a handle for future reference. Each preview object should be allocated a unique numeric identifier for the current session.

Prototype CEVRET_System CevCreateObject (PHCEV phcev, ULONG id)

Parameters *phcev Receives handle to new preview object.

id The numeric identifier for this object to be assigned to Preview API control

Return Codes CEVRET_NOERRORCEVRET_NOT_INITIALIZEDCEVRET_INVALID_PARAMETERCEVRET_MEM_ERRORCEVRET_ERROR

Function Reference 111

CevCreateWindow

Synopsis Creates a preview window/control and initializes it with the supplied parameters.

This function calls on the WinCreateWindow function and you can refer to the appropriate windows documentation for full details of window behavior, expected parameters, etc.

Prototype CEVRET_System CevCreateWindow (HWND hwndParent, HWND hwndOwner, ULONG ulStyle, LONG lSizex, LONG lSizey, LONG lPosx, LONG lPosey, HWND hwndBehind, ULONG ulID, PHWND phwndClient, PCEVGRIDINFO pgrid, PCEVRULERINFO pruler, PCEVSCROLLINFO pscroll, SHORT resolution)

Parameters hwndParent Handle of parent window.

hwndOwner Handle of owner window.

ulStyle Window style flags.

lSizex Window size X dimension.

lSizey Window size Y dimension.

lPosx X offset of window position.

lPosy Y offset of window position.

hwndBehind Handle to an existing window or a system constant that determines the ‘Zorder’ of the preview window.

ulID Number used as a unique ID for the preview window.

phwndClient Pointer to the handle assigned to the new window.

pgrid Pointer to the grid information structure for the new window.

pruler Pointer to the ruler information structure for the new window.

pscroll Pointer to the scroll information structure for the new window.

resolution Number indicating valid screen resolution; zero for system defaults; -1 for ‘scale to fit’.

Return Codes CEVRET_NOERRORCEVRET_NOT_INITIALIZEDCEVRET_WIN_ERRORCEVRET_ERRORCEVRET_MEM_ERROR

CevDestroyObject

Synopsis Automatically disassociates a preview object from any preview window it may be associated with and destroys (frees) all resources associated with it. Any temporary files are deleted.

112 Preview API

Prototype CEVRET_System CevDestroyObject (HCEV, hcev)

Parameters hcev Handle of preview object to destroy.

Return Codes CEVRET_NOERRORCEVRET_NOT_INITIALIZEDCEVRET_INVALID_HANDLE

CevDoubletoLu

Synopsis Converts a value (stored as a double) of the unit of measure specified to a LUNIT.

For example, if the double value is 2.54 and the unit of measure is specified as inches (constant CEVDEF_UnitInch), a LUNIT representing 2.54 inches will be returned. If the same value is specified but the unit of measure is Centimeters (Constant CEVDEF_UnitCm), a LUNIT representing 1.0 inches is returned instead.

Prototype CEVRET APIENTRY CevDoubleToLu (double dValue, ULONG ulMeasure, PLUNIT pulValue);

Parameters dValue Double value to convert.

ulMeasure Unit of measure which dValue represents. Choose one of the following (self explanatory) constants.CEVDEF_UnitInchCEVDEF_UnitCmCEVDEF_UnitMmCEVDEF_UnitPicaCEVDEF_UnitPoint

pulValue Points to converted LUNIT value. Set to zero if there is an error. Refer “Types and Data Structures” on page 129 for details of the LUNIT type.

Return Codes CEVRET_NOERRORCEVRET_INVALID_PARAMETER

CevExecuteRules

Synopsis Processes the application data specified using the engine rules associated with the specified preview object. If the object is not associated with valid engine rules an error will be returned.

The application data may be specified either as an external data file or data in memory. Note: if both are specified the data file will be used. The function assumes that the application data is suitable for the associate rules (i.e. conforms to the data format).

Processing the application data can take a significant amount of time (up to several minutes) depending on the size of the input data file and the complexity of the application rules being processed. Therefore the function will complete and issue a return code while the conversion process continues as a separate thread.


Notification messages regarding the progress of the conversion will be sent as WM_Control messages to the status window (hwndStatus). While the client application can continue with other activity while the conversion is taking place, no other functions relating to the preview object should be executed until CEVNOTIFY_EXECUTE_FINISHED is issued to the status window. Refer to “Notification Codes” on page 127 for more information about these messages.

Prototype CEVRET_System CevExecuteRules (HCEV hcev, HWND hwndStatus, PSZ pszDataFile, PBYTE pbData, ULONG cbData)


hwndStatus Window handle to receive WM_Control messages.

pszDatafile Pointer to fully qualified filename of a suitable application data file.

pbData Pointer to suitable application data in memory; specify NULL if data file is used.

cbData Count of number of records in application data in memory; specify 0 if data file is used.

Return Codes CEVRET_NOERRORCEVRET_NOT_INITIALIZEDCEVRET_INVALID_HANDLECEVRET_ERRORCEVRET_EXECUTE_ERROR

CevInitApi

Synopsis Associates a Preview API session with an NT thread and performs all initialization required to run the API. This function assumes that the windows functions WinInitialize and WinCreateMsgQueue have previously been used to generate a valid Thread within which the API will operate.

CevInitAPI must be issued before any other API function call with the exception of CevStartTrace.

Prototype CEVRET_System CevInitApi (BOOL fDebugMode, HAB hab, HMQ hmq)

Parameters fDebugMode If TRUE when trace is active additional debug information is provided in the trace file.

hab The handle generated by the WinInitialize function for the Thread.

hmq The handle generated by the WinCreateMsgQueue function for the Thread.

Return Codes CEVRET_NOERRORCEVRET_ALREADY_INITIALIZEDCEVRET_MEM_ERRORCEVRET_INIT_FAILED

114 Preview API

CevLuToDouble

Synopsis Converts a LUNIT to a value (stored as a double) of the unit of measure specified.

For example, if the LUNIT value represents one inch and the unit of measure is specified as inches (constant CEVDEF_UnitInch), a value of 1.0 will be returned. If the same LUNIT value is specified but the unit of measure is millimeters (constant CEVDEF_UnitMm), a value of 25.4 is returned instead.

Prototype CEVRET APIENTRY CevLuToDouble (LUNIT luValue, ULONG ulMeasure, double *pdValue);

Parameters luValue LUNIT value to convert. Refer to “Types and Data Structures” on page 129 for details of the LUNIT type.

ulMeasure Unit of measure to be used for pdValue. Choose one of the following (self-explanatory) constants.CEVDEF_UnitInchCEVDEF_UnitCmCEVDEF_UnitMmCEVDEF_UnitPicaCEVDEF_UnitPoint

pdValue Pointer to double to receive the converted value. Set to zero if there is an error.

Return Codes CEVRET_NOERRORCEVRET_INVALID_PARAMETER

CevProof

Synopsis Proofs a range of pages from a document to a supported raster printer.

Prototype CEVRET_System CevProof (HCEV hcev, HWND hwndStatus, LONG idDoc, LONG numDoc, LONG numPageStart, LONG numPageEnd, UINT uiMarkMethod, PSZ szMarkString)

Parameters hcev Handle to preview object.

hwndStatus Window handle to receive messages from proof process.

idDoc ID of document type to be proofed; -1 indicates all document types.

numDoc The sequential number of the required document (within document type if specified); -1 means all documents.

numPageStart Sequential page number (within document if specified) at which proofing is to start; -1 means all pages in specified document(s).

numPageEnd Sequential page number (within document if specified) at which proofing is to end; -1 means all pages in specified document(s).


uiMarkMethod Constant indicating required method for marking proof copies. Specify one of the following:CEVMARK_CrossMarks - proof image has angle marks at each corner.CEVMARK_ProofBackground - proof image has contents of szMarkString across it in large outline font. CEVMARK_None - no marks are generated.

szMarkString String to be used with CEVMARK_ProofBackground.

Return Codes CEVRET_NOERRORCEVRET_NOT_INITIALIZEDCEVRET_INVALID_HANDLECEVRET_ERRORCEVRET_INVALID_PROOF_SPECCEVRET_NOPRINTERSCEVRET_INVALID_PRINTERCEVRET_PRINT_CANCELLED

CevQueryActivePage

Synopsis Queries the document type and document/page numbers of the active page (as selected by CevSetActivePage).

Prototype CEVRET_System CevQueryActivePage (HCEV hcev, LONG *pidDoc, LONG *pnumDoc, LONG *pnumPage)


*pidDoc Pointer to receive document type identifier.

*pnumDoc Pointer to receive sequential document number within document type.

*pnumPage Pointer to receive sequential page number within current document.

Return Codes CEVRET_NOT_INITIALIZEDCEVRET_ERRORCEVRET_INVALID_HANDLECEVRET_NOERROR

CevQueryDataDocCount

Synopsis Queries the number of document types in the output held by the preview object.

Prototype CEVRET_System CevQueryDataDocCount (HCEV hcev, LONG *pcDataDocs)


*pcDataDocs Pointer to receive count of document types.

116 Preview API

Return Codes CEVRET_NOERRORCEVRET_NOT_INITIALIZEDCEVRET_INVALID_HANDLECEVRET_ERROR

CevQueryDataDocKey

Synopsis Queries the value of the Key Field in the record that marks the start of a data document associated with the specified document type.

Prototype CEVRET_System CevQueryDataDocKey (HCEV hcev, LONG idDoc, PSZ pszKey, LONG cbKeyMax)


idDoc Document type identifier.

pszKey Pointer to receive appropriate Key Field value.

cbKeyMax Maximum size of buffer allocated to receive the pszKey string.


CevQueryDataDocKeyId

Synopsis Queries the internal key id (as assigned by the data format Editor) of the specified document type.

Prototype CEVRET_System DataDocKeyId (HCEV hcev, LONG idDoc, ULONG pulKeyId)



pulKeyId Pointer to receive appropriate document type key ID.

Return Codes CEVRET_NOERRORCEVRET_NOT_INITIALIZEDCEVRET_ERRORCEVRET_INVALID_HANDLE

CevQueryDataDocLabel

Synopsis Queries the user-defined label of the document layout associated with the specified document type.


Prototype CEVRET_System CevQueryDataDocLabel (HCEV hcev, LONG idDoc, PSZ pszLabel, LONG cbLabelMax)



pszLabel Pointer to receive label string.

cbLabelMax Maximum size of buffer allocated to hold the pszLabel string.


CevQueryDocCount

Synopsis Queries the number of documents of the specified data document type in the preview object.

Prototype CEVRET_System CevQueryDocCount (HCEV hcev, LONG idDoc, LONG *pcDocs)



*pcDocs Pointer to receive count of documents.


CevQueryGridInfo

Synopsis Queries the grid information being used by the specified preview window.

Prototype CEVRET_System CevQueryGridInfo (HWND hwnd, PCEVGRIDINFO pgridinfo)

Parameters hwnd Window handle for preview window.

pgridinfo Pointer to receive grid information structure.

Return Codes CEVRET_NOERRORCEVRET_NOT_INITIALIZEDCEVRET_INVALID_WINDOWCEVRET_ERRORCEVRET_INVALID_STRUCTURE

118 Preview API

CevQueryPagesInDoc

Synopsis Queries the number of pages in a document.

Prototype CEVRET_System CevQueryPagesInDoc (HCEV hcev, LONG idDoc, LONG numDoc, LONG *pcPages)



numDoc Sequential document number (of the above type).

*pcPages Pointer to receive page count.


CevQueryResolution

Synopsis Queries the resolution being used by the specified preview window.

Prototype CEVRET_System CevQueryResolution (HWND hwnd, SHORT *psResolution)


*psResolution Pointer to receive screen resolution constant. This will be one of:CEV_ResolutionScreen - the current screen resolutionCEV_Resolution240 - 240 dpiCEV_Resolution300 - 300 dpiCEV_ResolutionFit - the resolution will be generated so that the image fits the window.

Return Codes CEVRET_NOERRORCEVRET_NOT_INITIALIZEDCEVRET_INVALID_WINDOWCEVRET_ERROR

CevQueryRulerInfo

Synopsis Queries the ruler information being used by the specified preview window.

Prototype CEVRET_System CevQueryRulerInfo (HWND hwnd, PCEVRULERINFO prulerinfo)


prulerinfo Pointer to receive ruler information structure.


Return Codes CEVRET_NOERRORCEVRET_NOT_INITIALIZEDCEVRET_INVALID_WINDOWCEVRET_INVALID_STRUCTURECEVRET_ERROR

CevQueryScrollInfo

Synopsis Queries the scroll information being used by the specified preview window.

Prototype CEVRET_System CevQueryScrollInfo (HWND hwnd, PCEVSCROLLINFO pscrollinfo)

Parameters hwnd Window handle for preview window

pscrollinfo Pointer to scroll information structure


CevSetActivePage

Synopsis Determines the page to be displayed either by an existing preview window or when such a window is created for the specified object.

Prototype CEVRET_System CevSetActivePage (HCEV hcev, LONG idDoc, LONG numDoc, LONG numPage)


idDoc Document type identifier. If this is set to 0 (zero) the API will search from the start of Preview ‘output’ looking for the values numDoc and numPage.

numDoc Sequential document number (of the above type).

numPage Sequential page number (within the above document).

Return Codes CEVRET_NOERRORCEVRET_NOT_INITIALIZEDCEVRET_INVALID_HANDLECEVRET_INVALID_PARAMETERCEVRET_ERROR

120 Preview API

CevSetBackColor

Synopsis Sets the background color to be used with a preview window.

Prototype CEVRET_System CevSetBackColor (HWND hwnd, LONG color)


color Presentation Manager color number (refer to your windows literature for details).


CevSetEnvironment

Synopsis Sets environment settings.

Prototype CEVRET_System CevSetEnvironment (PCEVENVINFO penvinfo)

Parameters penvinfo Pointer to environment information structure.

Return Codes CEVRET_NOERRORCEVRET_NOT_INITIALIZEDCEVRET_INVALID_STRUCTURE

CevSetGridInfo

Synopsis Sets the grid information used by the specified preview window.

Prototype CEVRET_System CevSetGridInfo (HWND hwnd, PCEVGRIDINFO pgridinfo)


pgridinfo Pointer to grid information structure.



CevSetResolution

Synopsis Sets the resolution used by the specified preview window.

Prototype CEVRET_System CevSetResolution (HWND hwnd, SHORT sResolution)


sResolution Number indicating valid screen resolution; zero for system defaults; -1 for ‘scale to fit’.


CevSetRulerInfo

Synopsis Sets the ruler information used by the specified preview window.

Prototype CEVRET_System CevSetRulerInfo (HWND hwnd, PCEVRULERINFO prulerinfo)


prulerinfo Pointer to ruler information structure.


CevSetScrollInfo

Synopsis Sets the scroll information for the specified preview window.

Prototype CEVRET_System CevSetScrollInfo (HWND hwnd, PCEVSCROLLINFO pscrollinfo)


pscrollinfo Pointer to scroll information structure.


122 Preview API

CevStartTrace

Synopsis Starts a trace of information about the use of Preview API services. The trace is always written to file CEVAPI.TRC in the current directory. This function may be issued before CevInitApi.

Prototype CEVRET_System CevStartTrace (BOOL bFlush, HWND hwndTraceApi)

Parameters bFlush Clear any existing trace records

hwndTraceApi Window handle of a listbox to display trace records or NULL if not required

Return Codes CEVRET_NOERRORCEVRET_FILE_OPENCEVRET_FILE_WRITE

CevStopTrace

Synopsis Stops a trace previously started by CevStartTrace.

Prototype CEVRET_System CevStopTrace (VOID)

Return Codes CEVRET_NOERRORCEVRET_FILE_WRITE

CevTerminateApi

Synopsis Terminates the current Preview API session. Following this function call all other Preview API functions are invalid until another call of CevInitAPI.

Prototype VOID_System CevTerminateApi (VOID)

CevUseEngineRuleFiles

Synopsis Associates the specified set of engine rules files with the preview object. When this function is called, any logical rules associated with the object are disassociated and calls to CevConvertRules will not be valid.

The application rules directly references the other two files and it is the programmers responsibility to ensure that the set of files are compatible.

Prototype CEVRET_System CevUseEngineRuleFiles (HCEV hcev, PSZ pszEar, PSZ pszEol, PSZ pszEdf)



pszEar Pointer to the fully qualified filename of an application rules file in ‘engine rules’ format.

pszEol Pointer to the fully qualified filename of a document object library file in ‘engine rules’ format.

pszEdf Pointer to the fully qualified filename of a data format file in ‘engine rules’ format.


CevUseLogicalRuleFiles

Synopsis Associates the specified set of logical rules files with the preview object. When this function is called, any engine rules associated with the object are disassociated and it will be necessary to call CevConvertRules before application data can be processed by the API.

Prototype CEVRET_System CevUseLogicalRuleFiles (HCEV hcev, PSZ pszLar, PSZ pszLol, PSZ pszLdf)


pszLar Pointer to the fully qualified filename of an application rules file in ‘logical rules’ format.

pszLol Pointer to the fully qualified filename of a document object library file in ‘logical rules’ format.

pszLdf Pointer to the fully qualified filename of a data format file in ‘logical rules’ format.


Note Multiple Document Object Libraries can be used when specifying an application via logical rules but only a single reference can be made in this function call. To add further Libraries use the CevAddFirmDataLibrary function before using CevConvertRules

124 Preview API

CevUseObject

Synopsis Associates an object with a preview window.

Prototype CEVRET_System CevUseObject (HWND hwnd, HCEV hcev)

Parameters hwnd Window handle of preview window.

hcev Preview object to be displayed.

Return Codes CEVRET_NOERRORCEVRET_NOT_INITIALIZEDCEVRET_INVALID_HANDLECEVRET_INVALID_WINDOWCEVRET_ERROR


Return CodesEach Preview API function will return one of the following constants (defined in CEVAPI.H) to indicate the result of the relevant service. A brief explanation of each return code is given below:

CEVRET_ALREADY_INITIALIZED The API is already initialized.

CEVRET_CONVERT_ERROR Cannot convert because logical rules are not associated with object.

CEVRET_ERROR API function call resulted in unspecified error.

CEVRET_EXECUTE_ERROR Error locating engine rules files for CevExecuteRules.

CEVRET_FILE_OPEN Error opening file.

CEVRET_FILE_WRITE Error writing to file.

CEVRET_INIT_FAILED API Initialization failed.

CEVRET_INVALID_HANDLE Invalid object handle specified.

CEVRET_INVALID_PARAMETER Invalid function parameter specified.

CEVRET_INVALID_PRINTER Printer not found during call to proof print.

CEVRET_INVALID_PROOF_SPEC Invalid specification for proof print.

CEVRET_INVALID_STRUCTURE Caller has supplied an invalid structure.

CEVRET_INVALID_WINDOW Invalid window handle specified.

CEVRET_MEM_ERROR Unable to allocate sufficient memory for the required service.

CEVRET_NOERROR The API function call was successful.

CEVRET_NOPRINTERS No printers available for proof print.

CEVRET_NOT_INITIALIZED API not initialized.

CEVRET_PRINT_CANCELLED Print selection dialog cancelled.

CEVRET_TOO_MANY_LOLS More than 32 document object libraries have been specified.

CEVRET_WIN_ERROR Call to create a preview window failed.

126 Preview API

Notification CodesThe following codes are sent to the Status window identified to CevConvertRules and CevExecuteRules. They will be sent in a WM_CONTROL message in the following format:

WM_CONTROL param1, param2

CEVNOTIFY_CONVERT_FINISHEDCevConvertRules has terminatedparam1

USHORT Control IDUSHORT Notification code

param2 Object handleLONG

CEVNOTIFY_CONVERT_FAILEDCevConvertRules has failedparam1


param2LONG Object handle

CEVNOTIFY_CONVERT_COMPLETE CevConvertRules has completed at step ‘Conversion step’ out of ‘Maximum steps’param1


param2USHORT Conversion stepUSHORT Maximum steps

CEVNOTIFY_EXECUTE_FINISHEDCevExecuteRules has terminatedparam1


param2LONG Object handle

CEVNOTIFY_EXECUTE_FAILEDCevExecuteRules has failedparam1


param2 LONG Object handle

Notification Codes 127

CEVNOTIFY_EXECUTE_COMPLETECevExecuteRules has completed after processing ‘Document number’ out of ‘Total document count’param1


param2USHORT Document numberUSHORT Total document count

128 Preview API

Types and Data StructuresThe C language data structures detailed here are provided in the header file, CEVAPI.H. These are the structures specific to the CEV API. Note that the Presentation Data is not available to the user.

Hungarian Notation has been used extensively to identify data types. All ‘standard’ data types such as ULONG, SHORT, etc. are specified in the header files supplied with the appropriate Developers Toolkit.

It is important that the size of structures are available to the operating system and the structures detailed below have a cb component to contain this value. Be sure to use the sizeof C command to generate the required value whenever appropriate.

Type LUNIT

Use An LUNIT is a resolution-independent unit of measure. It is used in the LarMeta Architecture wherever positioning and measurement for document pages are required.

It comprises a 4-byte signed binary integer. Its base unit of measurement is 1/6,553,600 of an inch. This means that the maximum distance that can be contained within an LUNIT is 327.67 inches.

Another way to look at the 4-byte field is as two integers. The most significant 2 bytes are interpreted as a signed integer containing a count of 1/100 inches. The least significant two bytes are treated as an unsigned integer defining a count of 1/65, 536’s of 1/100 inches.

Declaration typedef LONG LUNIT, *PLUNIT;

Enumerated type CEVUOM

Use Required for rulers unit of measure specification.

Declaration typedef enum tagCEVUOM {CEV_UnitInchCEV_UnitCmCEV_UnitMmCEV_UnitPicaCEV_UnitPointCEV_UnitPel} CEVUOM, *PCEVUOM;

Types and Data Structures 129

Structure CEVENVINFO

Use Holds information relating to the working environment of a Preview API session.

Declaration typedef struct tagCEVENVINFO {UINT cb;ULONG flApplicable;CHAR szUserId[8];CHAR szWorkPath[300];} CEVENVINFO, *PCEVENVINFO;

Components cb Structure size.

flApplicable The parts of the structure applicable to following operations. Assign one or more of the following constants (self-explanatory in terms of the fields affected) in a single operation separated with the logical OR operator:CEVENV_WorkPathCEVENV_All

szUserId Not currently used.

szWorkPath Fully qualified path name to be used as working directory.

Structure CEVGRIDINFO

Use Used to channel information regarding a preview window grid between the API and the client application.

Declaration typedef struct tagCEVGRIDINFO {UINT cb;ULONG flApplicable;LUNIT luStepX;LUNIT luStepY;BOOL fShow;} CEVGRIDINFO, *PCEVGRIDINFO;


flApplicable The parts of the structure applicable to following operations. Assign one or more of the following constants (self-explanatory in terms of the fields affected) in a single operation separated with the logical OR operator:CEVGRID_StepXCEVGRID_StepYCEVGRID_ShowCEVGRID_All

luStepX Vertical increment of grid.

luStepY Horizontal increment of grid.

fShow Grid is displayed if TRUE.

130 Preview API

Structure CEVRULERINFO

Use Used to channel information regarding the on-screen rulers used in a preview window between the API and the client application.

Declaration typedef struct tagCEVRULERINFO {UINT cb;ULONG flApplicable;CEVUOM uom;UINT cDivisions;BOOL fShowRuler;BOOL fShowIndicator;BOOL fCrossHairs;UINT cRulerThickness;} CEVRULERINFO, *PCEVRULERINFO;


flApplicable The parts of the structure applicable to following operations. Assign one or more of the following constants (self-explanatory in terms of the fields affected) in a single operation separated with the logical OR operator:CEVRULER_UOMCEVRULER_DivisionsCEVRULER_ShowRulerCEVRULER_ShowIndicatorCEVRULER_CrossHairsCEVRULER_ThicknessCEVRULER_All

uom Unit of measure to be used on rulers. Code one of the (self-explanatory) identifiers from enumerated type “Enumerated type CEVUOM” on page 129 (see above).

cDivisions Number of division steps to be marked on rulers between each major unit measure.

fShowRuler TRUE if ruler is to be shown.

fShowIndicator TRUE if indicators on rulers are to be shown as mouse moves in preview window.

fCrossHairs TRUE if cross hairs are to be shown on presentation space as mouse in preview window.

cRulerThickness Thickness of rulers in terms of uom.

Types and Data Structures 131

Structure CEVSCROLLINFO

Use Used to channel information regarding a preview window scroll bars between the API and the client application.

Declaration typedef struct tagCEVSCROLLINFO {UINT cb;ULONG flApplicable;BOOL fHorzShow;BOOL fVertShow;SHORT sHPosition;SHORT sVPosition;SHORT sHCommand;SHORT sVCommand;} CEVSCROLLINFO, *PCEVSCROLLINFO;

Components cb Structure size. Needed for backwards compatibility.

flApplicable The parts of the structure applicable to following operations. Assign one or more of the following constants (self-explanatory in terms of the fields affected) in a single operation separated with the logical OR operator:CEVSCROLL_HShowCEVSCROLL_VShowCEVSCROLL_HPositionCEVSCROLL_VPositionCEVSCROLL_SetAll

fHorzShow Horizontal scroll bar displayed if TRUE.

fVertShow Vertical scroll bar displayed if TRUE.

sHPosition Position of horizontal slider *** in terms of what ****

sVPosition Position of vertical slider.

sHCommand Horizontal scroll reposition. Assign one of the following constants representing standard WM_HSCROLL parameters:SB_LINELEFTSB_LINERIGHTSB_PAGELEFTSB_PAGERIGHTSB_SLIDERPOS

sVCommand Vertical scroll reposition. Assign one of the following constants representing standard WM_VSCROLL parameters:SB_LINEUPSB_LINEDOWNSB_PAGEUPSB_PAGEDOWNSB_SLIDERPOS

132 Preview API

Coding a Character Layout File

You can customize the layout of the Characters dialog that is used when selecting special characters for a Text element in DOE. You do this by creating user defined pages that include the characters you want to use frequently or to fulfil any other layout requirement. User defined pages are created by coding a Character Layout file for each page you want to add to the Characters dialog. Such pages are displayed in addition to the pages that represent the font character sets. All user defined pages appear after the ‘most recently used’ page but before the character set pages.

Location and Naming Convention

You will need one Character Layout file for each user defined page you want to appear in the Characters dialog. Such files must conform to the following path and file naming convention:

Doc1Path\SYSTEM\FONTDATA\Fontname.Unn

where:

Doc1Path is the pathname under which the DOC1 workstation was installed.

Fontname is the font basename.

Unn is a file extension in the form of ‘U’ followed by a two digit number indicating the position where the page will appear within the user defined pages of the Characters dialog. ‘.U01’ will be the first page, ‘.U02’ the second and so on. The number must be unique but not necessarily in strict sequence (see below).

Example

Character Layout files with names X0ADB50.U02, X0ADB50.U05 and X0ADB50.U16 are present in SYSTEM\FONTDATA but no other files with a basename of X0ADB50 exist. These files will be used to format the first, second and third user defined pages respectively in the Characters dialog whenever the font X0ADB50 is being referenced.

133

Character Layout File format

A Character Layout File defines the layout of user defined pages to be used with the Characters dialog in DOE.

Syntax:

VERSION 1TITLE BITMAP FileNameTITLE TEXT "String"CHAR HexCode...CHARS HexCode-HexCode...FORCE LINE BREAK...;Comment


VERSION 1 Must be the first command (version number may change in the future).

TITLE BITMAP FileName indicates the path/filename of a windows bitmap file (BMP) that will be used to label the associated page tab in the Characters dialog. If no path is specified then Doc1Path\SYSTEM\FONTDATA will be assumed.

TITLE TEXT String indicates a text string that will be used to label the associated page tab in the Characters dialog if TITLE BITMAP is not coded or the associated file is not found or is not valid.

CHAR or CHARS HexCode indicates the hex numbers of the section (character set reference) and code point of a character to be included in the user defined page. This code always takes the form 0xsscc where ss is the section number and cc is the code point. For example 0x02A0 indicates code point A0 within section 02. Single byte fonts always have only one section which is considered to be number 00. You can use the CHAR keyword to indicate an individual character or the CHARS keyword to indicate a range of characters that have sequential code points.The maximum number of characters indicated in all CHAR and CHARS keywords must not exceed 256.

FORCE LINE BREAK indicates that the next character coded in the file will be placed on a new line. The standard layout of a page in the Characters dialog is 16x16 grid of character images. Unless FORCE LINE BREAK is coded, the characters indicated in a Character Layout file will be placed starting at top left and will wrap to a new line automatically.

134 Coding a Character Layout File

Example

VERSION 1;Character Layout for Page 1 of DBCS fontsTITLE BITMAP D:\DOC1\PAGEFILE\PAGE1.BMPTITLE TEXT "Useful chars"CHARS 0x00a0-0x00a9FORCE LINE BREAKCHAR 0x0091CHAR 0x0097

135

136 Coding a Character Layout File

Integrating with third party products

The DOC1 environment provides a number of programmable features intended to allow more efficient relationships with DOC1 and a number of non-Group1 products.

The EDINAT©/DOC1 Production Bridge uses the production capabilities of DOC1 to manipulate and print AFPDS documents generated by the EDINAT system.

The Reformat utility allows conversion of DOC1 data format files and an associated application data file to an independent format thus supporting data interchange with other systems.

OTS Finishing Line support is provided by DOC1 specifically related to applications maintained by the OTS agency on behalf of their clients. This feature allows extra information to be inserted automatically into the printstream which is then used by the printer or output device to perform specific actions, for example, print a separate summary page, or check the accuracy of an address before mailing. See “Generating an OTS Finishing line” on page 160 for further information.

137

EDINAT©/DOC1 Production BridgeThe DOC1 environment provides support for production style manipulation and printing of AFPDS documents generated by Business Document’s Electronic Document Interchange for letters (EDINAT©) system. The aim of this support is to:

• automatically capture AFP documents generated by a number of EDINAT clients

• merge them into a single AFP file that also contains index and page count information

• transport the merged file to a designated host system

• prepare the file for printing or further processing by PCE.

The additional software required for this model is provided on separate media from the regular DOC1 distribution CD. This will need to be distributed to all EDINAT client machines intended to take part in the process.

Note the current release supports production bridge on MVS/OS390, AIX and Windows host platforms. Please refer to your DOC1 supplier if support for other host platforms is required. However, the READYEDI utility is available for all supported platforms.

DOC1 Host

Holding server

Workstation

Workstation

WorkstationEDINAT client

DOC1 Port Monitor

Print to

DOC1 Upload Service

Mergedoutputs

Other server

Other server

Other server

JobOutput

JobOutput

JobOutput

JobOutputMergedoutputs

ReadyEDIutility

PreparedAFPDS

DOC1Journal

PCEEMFE batchoutputs

PSF

JobOutput

EDINAT/DOC1 Production bridge environment

Concatenate as required

DOC1 APPC client

138 Integrating with third party products

The DOC1 Upload ServiceThe DOC1 Upload Service monitors a user specified spool directory to which output from Edinat sessions is directed. These outputs are merged and uploaded to a host system according to a user configurable schedule. The upload service can be configured to use either APPC or FTP protocols to upload the accumulated output to a specified dataset or directory on the host system. It will either append output to, or overwrite the target file. Note that the dataset is not cleared as part of the ReadyEDI utility that prepares the output for processing on the host system. Note that under Windows the Upload service is only required if the merged output is to be transferred to a different network.

VERY IMPORTANT: the Upload Service must be configured before any workstations attempt to install the port monitor. It is assumed the Upload Service will run on a server to which all Edinat clients will have access and that the server will have the necessary access rights to the host system.

APPC transactions on the OS/390 host system are handled by an additional program which must be made known to the operating system before it can be used. Note that, if your DOC1 environment already makes use of APPC transfer via the Workgroups or Message1 products then the necessary configuration may already have been carried out.

Installing

Upload Service on the Windows server

If transactions are to be processed for upload to a OS/390 host you will need to install Microsoft SNA Server and Client on the machine that is to run the DOC1 Upload Service. Please refer to the relevant Microsoft documentation for details.

Both the SNA software and Upload Service must be installed by the same user account and this account must have administrator privileges on the server.

It is recommended that the directory structure shown in the adjacent diagram is set up on your server to cater for installation, error, journal and output spool files.

To install the DOC1 Upload Service to process transactions for OS/390, AIX or Windows hosts.

1. Create a directory on the server for the Upload Service

This location will act as the workspace for the merge process and therefore must have enough disk space to handle all the expected output files from the predicating EDINAT clients. Copy the Upload Service program from the distribution media into this directory. The program name is doc1upld_service.exe.

EDINAT©/DOC1 Production Bridge 139

2. Create error, journal and spool subdirectories under the Doc1Upload directory created in step1.

3. Copy the Upload Services configuration file from the distribution media to the <Windows>\System32 directory. The file name isdoc1uploadconfig.cpl.

This will make the DOC1 Upload Service applet available in the system control panel.

4. Run the following command from the Doc1Upload directory:doc1upld_service -installThis will install the service into the servers registry.

5. Use the Services applet in the system Control Panel (e.g. Start/Settings/Control Panel/Services) to configure start-up options for the service.Note that under Windows 2000 the Services applet can be found in the system Control Panel under the Administrative tools folder.

Select the DOC1 Upload Service from the list. Specify the account name that is authorized for the server as This account along with the relevant password.

6. Return to the Control Panel and configure the service by running the DOC1 Upload Services applet. You will need to supply the following information:

Spool directory - enter the directory you created in step 1.

Host file - the fully qualified dataset/file name on the host system that is to receive the uploaded output.

If File Exists - values as follows:

Append - output will be appended to the existing host file.

Overwrite - data in the host file will be overwritten.

Upload mode - must be Timed in the current release.

Cycle time - the interval (in minutes) at which the Service will check the spool directory for new files to upload.

Protocol - transmission protocol, select from FTP or APPC.

LU Name/Host - the label of this entry field is dependant on the setting of the protocol field as follows:

APPC - field label is set to LU Name and must contain the name of the Logical Unit that will handle the APPC transfer.

FTP - field label is set to Host and must contain the FTP host name/IP address information.

Enter a valid username and password to gain access to the DOC1 host environment.


APPC client on the OS/390 host

This consists of a single additional program which must be configured as a logical unit (LU) on the OS/390 host. This work will normally need to be carried out by your system programmer.

STEP 1: define a suitable LU to VTAM. For example, in a member of SYS1.VTAMLST add the following:

Note: to activate the LU in this example issue the following operator command:V NET,ACT,ID=A0600

STEP 2: make the LU known to APPC. For example, create or edit a SYS1 PARMLIB member with name APPCPMxx (last two characters may vary) and add the following:

STEP 3: add a scheduler class to ASCH. For example, create or edit a SYS1.PARMLIB member with name ASCHPMxx (matching the APPCPM member) and add the following:

A0600 VBUILD TYPE=APPL*MVSLU01 APPL ACBNAME=MVSLU01, ACBNAME FOR APPC C APPC=YES, C AUTOSES=0, C DDRAINL=NALLOW, C DLOGMOD=APPCHOST, C DMINWNL=5, C DMINWNR=5, C DRESPL=NALLOW, C DSESLIM=10, C LMDENT=19, C MODETAB=APPCTAB, C PARSESS=YES, C SECACPT=CONV, C SRBEXIT=YES, C VPACING=1

LUADD ACBNAME(S43APP1) SCHED(ASCH) TPDATA(SYS1.APPCTP)

CLASSADD CLASSNAME(A) MSGLIMIT(1000) MIN(1) MAX(10) RESPGOAL(1)

Then issue the following operator command using the variable characters:SET ASCH=xx


STEP 4: execute the ATBSDFMU utility with the following input:

Running the Service

On the Windows server go to the system control panel and select the Services shortcut. Select the DOC1 Upload Service from the list and click on the Start button.

Once set up, the DOC1 Upload Service will operate automatically as scheduled, automatically retrying if it is not immediately successful. If for any reason an upload is not successful an event is registered on the Windows event log to identify the failure.

You can also explicitly start and stop the service using the following command lines:NET START DOC1UPLD_SERVICENET STOP DOC1UPLD_SERVICE

You can monitor the upload process via the Windows event viewer.

The DOC1 Port MonitorThe model requires output from EDINAT clients to be directed to a Windows port which is running the DOC1 Port Monitor software provided. The Port Monitor itself requires an AFP print driver (applicable to your Windows system) to be already installed on each client machine.

The following actions need to be taken on each EDINAT client machine intending to send output via the production bridge.

The DOC1Holding.inf file from the distribution media must be copied to the spool directory. Remove the read-only attributes of the file DOC1Holding.inf and audit.log. You will need to modify the ErrorPath and JournalPath settings in these files to reflect the error and journal directory paths previously set up, see “Upload Service on the Windows server” on page 139.

TPADD TPNAME(DFWAFTP) ACTIVE(YES) TPSCHED_DELIMITER(##) CLASS(A) TPSCHED_TYPE(STANDARD) JCL_DELIMITER(++)//DFWAFTP JOB//FTP EXEC PGM=AFTPD//STEPLIB DD DSN=[location of DOC1 APPC program as provided],DISP=SHR//SYSPRINT DD SYSOUT=X++##


This is a text file that can be modified with any standard editor, be sure not to use a word processor that may add unwanted control codes to the file. Refer to “Example DOC1holding.inf file” on page 144 for further information.

Now continue the steps below for Windows NT or go to “Port Monitor installation for Windows 2000 & XP” on page 144.

Port Monitor installation for Windows NT1. Start the Add Printers wizard (e.g. via Start/Settings/Printers) and select

the My computer option.

2. Select Add port.

3. Select New monitor from the Printer ports dialog.

4. In the Installing print monitor dialog browse for and open the monitor.inf file as provided on the distribution media. Click OK.

5. From the Printer Ports dialog highlight the DOC1 Port Monitor and select New Port.

6. In the DOC1 Port Monitor Configuration dialog browse for and open the DOC1holding.inf file on the server where the DOC1 Upload Service was previously installed. Click OK.

7. Close the Printer Ports dialog.

8. DOC1 is now listed in the Add Printers wizard. Click Next.

9. Select IBM as the Manufacturer and select any valid AFP driver from the list – e.g. "IBM AFP 3130". Click Next.

10. Select Keep existing driver and give the printer a name by which it will be recognized by the EDINAT user. Click Next.

11. Select Not shared. Click Next. Click Finish.


Port Monitor installation for Windows 2000 & XP1. Copy monitor.inf from the distribution media to the directory created in

the Upload Service - see “Upload Service on the Windows server” on page 139.

2. Copy audit.log to the path information specified in the DOC1Holding.inf file.

3. Select Printers and Faxes (e.g. via the Control Panel).

4. Select File, Server Properties.

5. Select the Ports tab and click Add Port.

6. Select New Port Type and use the Browse button to select monitor.inf from the directory created in the Upload Service - see step 1. Click OK

7. Select New Port. Add the path to where you copied the DOC1Holding.inf file. Click OK.

8. Close the Printer Ports dialog.

9. Close Printer Server Properties dialog. Click Next.

10. Start the Add Printer Wizard (e.g. via the Control Panel) and select the Printers and Faxes option. Click Next.

In this example the upload service directory structure has been set up on the server’s d drive, this may vary depending on the server’s drive mappings. Note that the lines marked with have to be modified to reflect the location of your journal and error paths. The Logfile entry must point to your upload service directory, in this case Doc1Upload

Example DOC1holding.inf file

; Group 1 Software (Europe) Ltd; Production Bridge configuration file;; Port Monitor resides on each workstation.;; This file is held in the port monitor's Holding Path; Set via Port's Configuration on each workstation.

;

[doc1mon]

JournalExt=".jnl"

JournalPath="d:\Doc1Upload\journals"

ErrorAction="Save"

ErrorPath="d:\Doc1Upload\error"

LogFile="d:\Doc1Upload"


11. Under Local Printer make sure that Automatically detect and Install Plug and Play is not selected.

12. Select DOC1 Port. Click Next.

13. Select Have Disk and using the browse button select the AFP printer driver relevant to your system from the folder set up in the Upload Service - see step 1. Select Replace Existing Driver if instructed.

14. Assign a valid name for the printer, such as DOC1 Printer. Click Next.

15. Click No and then click Next.

16. Select Do not share this printer.

17. Do not print a test page.

18. Click Finish.


Preparing the EDINAT output on the host systemUploaded EDINAT output in the merged file on the host system needs to be prepared before it can be printed or post-processed. The READYEDI utility re-blocks the AFPDS from the stream format produced on the Workstation and also splits out the journal information so that it can be used as an index into the output by the DOC1 Post Composition Engine (PCE) if required.

By default the AFPDS output by READYEDI is formatted as a VSAM RRDS file with each document stored as a separate VSAM record. The AIX version of READYEDI stores AFPDS output in STANDARD DOC1 output datasteam format with each document stored as a separate record in the output file. These formats are suited to the manipulation of AFPDS by PCE as documents can be directly accessed via the vector offset stored in the journal file which is also output by READYEDI. Refer to Output datastream types in the DOC1 Production guide for further information.

If you want to go straight to print or need the AFPDS to be structured differently you will need to use the -f parameter to specify a different formatting command. These formatting commands are exactly the same as used by EMFE and PCE when producing output from regular DOC1 applications. Specify STANDARD to produce AFPDS directly acceptable to PSF or use other formatting commands as required for specialized structures.The Journal file produced by READYEDI will always contain vector offsets for the documents within the AFPDS file produced. The format of the vector information will be automatically adjusted if non-VSAM output is defined. The journal will also contain the number of pages in each document plus thecontents of the journal string which can be input into the EDINAT client when a document is generated. Overall, READYEDI will produce one record of the following format for each document in the merged AFPDS file.

You may need to be aware of this structure if you need to parse the various fields when programming PCE.

M ergedoutpu ts

R eadyED Iutility

P reparedA FP D S

D O C 1Journa l

Structure of DOC1 Journal files as produced by READYEDI

S = user defined separator character. This will only be included if specifically requested when starting READYEDI

SVector offset (10 characters) Page count (5) S EDINAT journal string (variable length)


READYEDI under OS/390

Purpose:

Restructures AFPDS output from the EDINAT/DOC1 production bridge to be suitable for this platform and for onward processing. Also splits out journal information into a separate file.

Preparation:

The journal and AFP output files must be allocated with attributes and size suitable for the expected output. If VSAM data is to be generated the dataset must be pre-allocated using IDCAMS.

JCL:

//Jobname JOB (Rest of Job Card parms)//READYEDI EXEC PGM=READYEDI,PARM=(/[‘-s separator’’ ‘-f format’])//STEPLIB DD DISP=SHR,DSN=DOC1 Load Library + C run-time libs if required//SYSPRINT DD SYSOUT=*//AFPIN DD DISP=SHR,DSN=Dataset//AFPOUT DD DISP=(NEW,CTLG),DSN=Dataset//JOURNAL DD DISP=(NEW,CTLG),DSN=Dataset//*

Parameters:

-s separator is a single character or EBCDIC hex character code which will be used to separate the various parts of the DOC1 Journal generated in DD:JOURNAL. If using a hex code use the format 0Xnn.

-f format is a DOC1 printstream formatting keyword or formatting codes as documented in the DOC1 Production Guide (previously Host Modules User’s Guide). This will be used to format the AFPDS produced in DD:AFPOUT.The default is RRDSAFP which will place each document within a separate record of a VSAM relative record dataset. Note that if VSAM is used the DD:AFPOUT dataset must be pre-allocated using IDCAMS in a previous step.

DD References:

AFPIN The dataset containing the uploaded merged outputs from EDINAT.

AFPOUT The dataset that will receive the prepared AFPDS.

JOURNAL The dataset that will receive the DOC1 Journal as disseminated from AFPIN.


Example:

...//* CREATE NEW RRDS DATASET FOR READYEDI AFP OUTPUT//DEFRRDS EXEC PGM=IDCAMS//SYSPRINT DD SYSOUT=*//SYSOUT DD SYSOUT=*//SYSIN DD * DEFINE CLUSTER - (NAME(READYEDI.OUT.RRDSAFP) - CYL(10 1) - VOL(USER92) - RECORDSIZE(80 80) - NUMBERED ) //* RUN READYEDI//READYEDI EXEC PGM=READYEDI,PARM=’-s %’//STEPLIB DD DSN=DOC1.LOADLIB(READYEDI),DISP=SHR//SYSPRINT DD SYSOUT=*//* THE INPUT FILE FROM UPLOAD SERVICE //AFPIN DD DSN=DOC1.BRIDGE.AFP,DISP=SHR//* READYEDI OUTPUT FILES//AFPOUT DD DSN=READYEDI.OUT.RRDSAFP,DISP=SHR//JOURNAL DD DSN=READYEDI.OUT(JOURNAL),DISP=(NEW,CATALG)//*


READYEDI under OS/400

Purpose:


Preparation:

READYEDI can be executed either directly via a program call or indirectly via a command optionally using panel input. The panel can be invoked by entering the READYEDI command with no parameters and pressing F4. The subsequent panel allows you to identify the required parameters. You can also use READYEDI from the command line with parameters specified.

Syntax (program call method):

CALL READYEDI PARM(‘-I’ ‘Inputfile’ ‘-O’ ‘Outputfile’ ‘-J’ ‘Journalfile’ ‘-S’ ‘Separator’ ‘-F’ ’Format’)

Parameters:

-I Inputfile the file containing the uploaded merged outputs from EDINAT.

-O Outputfile the file that will receive the prepared AFPDS.

-J Journalfile the file that will receive the DOC1 Journal as disseminated from the Inputfile.

-S Separator is a single character or ANSI hex character code which will be used to separate the various parts of the DOC1 Journal produced in Journalfile. If using a hex code use the format 0Xnn. The default is no separator defined.

-F Format is a DOC1 printstream formatting keyword or formatting codes as documented in the DOC1 Production Guide. This will be used to format the AFPDS produced in Outputfile. The default output format is STANDARD. Refer to Output datastream types in the DOC1 Production guide for more information on formatting keywords.

Example:

CALL READYEDI PARM(‘-I’ ‘AFPIN’ ‘-O’ ‘AFPOUT’ ‘-J’ ‘JOURNAL’ ‘-S’ ‘%’ ‘-F’ ’CRLF’)


READYEDI under UNIX and OpenVMS

Purpose:


Preparation:

READYEDI is run from the command line of an appropriate operating system window.

Syntax:

readyedi -i <input_file> -o <output_file> -j <journal_file> -s <separator> -f <fmt>

Parameters:

-i <input_file> the file containing the uploaded merged outputs from EDINAT.

-o <output_file> the file that will receive the prepared AFPDS.

-j <journal_file> the file that will receive the DOC1 Journal as disseminated from the <input_file>.

-s <separator> is a single character or ANSI hex character code which will be used to separate the various parts of the DOC1 Journal produced in <journal_file>. If using a hex code use the format 0Xnn. The default is no separator defined.

-f <fmt> is a DOC1 printstream formatting keyword or formatting codes as documented in the DOC1 Production Guide (previously Host Modules User’s Guide). This will be used to format the AFPDS produced in <output_file>. The default output format is STANDARD. Refer to Output datastream types in the DOC1 Production guide for more information on formatting keywords.

Example:

UNIX:readyedi -i afpin -o afpout -j journal -s % -f CRLF

OpenVMS:readyedi -i []afpin -o []afpout -j []journal -s % -f CRLF


READYEDI under Windows, OS/2 and DOS

Purpose:


IMPORTANT: If the upload service is not required you will need to perform the following manual process from the spool directory to ensure the individual spool files are merged into one AFP file (UPLOAD.AFP) prior to running readyedi:

Copy /B *.SPL UPLOAD.AFP

The individual spool files will then need to be deleted to avoid duplication in the merged AFP file.

Preparation:

READYEDI is run from the command line of the operating system window.

Syntax:

readyedi -i <input_file> -o <output_file> -j <journal_file> -s <separator> -f <fmt>

Parameters:

-i <input_file> the file containing the uploaded merged outputs from EDINAT.

-o <output_file> the file that will receive the prepared AFPDS.

-j <journal_file> the file that will receive the DOC1 Journal as disseminated from the <input_file>.

-s <separator> is a single character or ANSI hex character code which will be used to separate the various parts of the DOC1 Journal produced in <journal_file>. If using a hex code use the format 0Xnn. The default is no separator defined.

-f <fmt> is a DOC1 printstream formatting keyword or formatting codes as documented in the DOC1 Production Guide (previously Host Modules User’s Guide). This will be used to format the AFPDS produced in <output_file>. The default output format is STANDARD. Refer to Output datastream types in the DOC1 Production guide for more information on formatting keywords.

Example:

readyedi -i afpin -o afpout -j journal -s % -f CRLF


Sharing application dataThe Reformat utility (DOC1RFMT) is provided to allow the structure and content of DOC1 application data to be shared with partner products. This is achieved by converting a DOC1 data format file to another file format and populating it with a suitable application data file. In the current release only Extensible Markup Language (XML) is supported as the output file format.

Reformat takes as input an EMFE ready data format file (EDF). It cannot work with the Workstation version of a data format (LDF). If required a further utility – MAKEEDF – can create an EDF from an LDF without the need to use the regular Workstation Build process.

Reformat is a command line utility which is available for all DOC1 supported host platforms. Its execution is controlled using an Initialization file similar to that used with EMFE and PCE.

REFORMAT IS A LICENSED DOC1FEATURE AND IS ENABLED BY THE RELEVANT SETTINGS IN YOUR EMFE KEYCODE. IF YOUR KEYCODE DOES NOT SUPPORT THIS FEATURE YOU WILL NOT BE ABLE TO START THE DOC1RFMT PROGRAM. CONTACT YOUR DOC1 SUPPLIER IF YOU WANT TO ACTIVATE REFORMAT.

XML outputThe structure of the XML file produced by Reformat is governed by the selected schema.

A generic DOC1 schema known as dXML is available for general use. A Data Type Definition (DTD) to assist with interpreting and working with dXML files can be supplied on request.

Other schemata may be added to support specific applications or environments. Please contact your DOC1 supplier for more information.

h


Reformat Initialization File format

The Initialization file (INI) specifies the environment for a particular execution of DOC1RFMT. Note that this is a subset of the main DOC INI file format which has features not documented here including the use of symbols to provide parameter substitution. Refer to the Production Guide for complete details of INI features.

Syntax:

; The LicenseInfo section is often in an Include file thus:#Include FileName

<LicenseInfo>CustomerName="String" ;no defaultKeycode=Keycode ;no default

<Files>Messages=Filename ;mandatory - no defaultInput=FileName ;mandatory - no defaultDataFormat=FileName ;mandatory - no defaultReformatOutput=Filename ;mandatory - no default

<Reformat>FormatType=XMLKeyField=FieldNameShowEmptyRecords={YES|NO} ;default NOShowKeyDefField={YES|NO} ;default NODateFormat=DateCode ;default %Y/%m/%dSymbols="Controls" ;default "{}[]" i.e. "x’47',x’48',x’49',x’50'"CompactSpaces={YES|NO} ;default YES

<XML>Schema=SchemaName ;default DOC1DefinitionName=String ;no defaultDocumentDate=Date ;no default

Data types:

Filename is a path/file name or label conforming to the convention required for the host operating system. The Preface of this document contains the file naming conventions expected on all supported host platforms.

String is a string of 0 or more alphanumeric characters, optionally enclosed in double quotes.

Keycode is a DOC1 keycode. This must be entered exactly as provided in the keycode report including all hyphens

FieldName is the description of a field defined to the data format as it was entered in the Data Format Editor.

Date is a date that must use the following format: yyyy/mm/dd.

Sharing application data 153

SchemaName is the name of an XML schema supported by Reformat.

DateCode is a sequence of codes plus optional text to represent the date. The formatting codes are preceded by a percent sign (%) and characters that do not have this prefix are copied unchanged to the output. Valid codes are:%a Abbreviated weekday name%A Full weekday name%b Abbreviated month name%B Full month name%d Day of month as decimal number (01 to 31)%m Month as decimal number (01 to 12)%w Weekday as decimal number (0 to 6; Sunday is 0)%y Year without century, as decimal number (00 to 99)%Y Year with century, as decimal number%% Percent signExamples:DateFormat="%m/%d/%Y" e.g. 04/13/2000DateFormat="%A, %B %d" e.g. Thursday, April 13

Controls Four characters or their hex equivalent values (see Syntax guide) representing left brace, right brace, left square bracket and right square bracket. Enclose in quotes.


CustomerName String is the name of your installation exactly as set out in your DOC1 keycode report including any punctuation.

Keycode Keycode is a DOC1 keycode that supports the Reformat feature.

Messages Filename is the DOC1 diagnostic message file. You must specify the Messages file provided for use with your current version of DOC1.

Input Filename is the path/filename that contains the application data to be processed by Reformat.

DataFormat Filename is the path/filename that contains the DOC1 data format to be processed by Reformat.

ReformatOutput Filename is the path/filename that will receive the reformatted data.

FormatType Indicates the type of output to be created. This must always be XML in the current release.

KeyField If specified, only data documents that contain the defined FieldName will be included in the XML output. The selected field must be within the first record of a data document in order for this filter to work. It need not be the same field that was defined as the key in the original data format.

ShowEmptyRecords If NO, records that have no content (other than the key field) will not be included in the output file. If YES Reformat will create an entry in the output file for all records regardless of content.

ShowKeyDefField If NO, the contents of the key field (as defined to the data format) will excluded from the entry in the output file. If YES it will be included.

Schema Specifies the type of XML structure to be created. Specify DOC1 to create generic DOC1 XML (dXML) or the name of a custom schema supported by Reformat.


DefinitionName If specified, this string will be included as the definition name attribute in the XML header.

DocumentDate If specified, this date will be used as the document date attribute in the XML header. If this is not specified, the current system date is used for this purpose. Note that the keyword StatementDate may alternatively be used to set this value.

Symbols Controls indicates the codepoints to be used for left brace, right brace, left square bracket and right square bracket within the output file. These are used as XML control characters. If you generate XML on non-ASCII based platforms and/or where the system uses a non-Latin based code page you may need to customize the values to be used for these controls.

CompactSpaces If YES is specified multiple spaces between words in the content of fields passed to Reformat will be compacted such that a single space only is always used in the XML output.

Example:

#Include doc1\resource\keycodes.ini

<Files>Messages=\doc1\run\messages.datInput=\production\input511.datDataFormat=\doc1\resources\app511.edfReformatOutput=\xmlout\app511.xml

<Reformat>FormatType=XMLKeyField="Account number"ShowEmptyRecords=YESShowKeyDefField=YESDateFormat="%m/%d/%Y"CompactSpaces=NO

<XML>Schema=DOC1DefinitionName="Ref:511"DocumentDate=2000/06/01


Running DOC1RFMT under UNIX, OpenVMS, OS/2, Windows and DOS

Purpose:

Converts a DOC1 data format file to another file format and populates it with the application data file specified.

Preparation:

DOC1RFMT is run from the command line of an appropriate operating system window.

Syntax:

doc1rfmt ini=Ini

Parameter:

Ini is the path/filename of the Reformat Initialization File to control this execution of the program. All other parameters are specified within the INI.

Example:

doc1rfmt ini=\doc1host\run\app511.ini


Running DOC1RFMT under OS/400

Purpose:


Preparation:

DOC1RFMT can be executed either directly via a program call or indirectly via a command optionally using panel input. The DOC1RFMT start-up panel can be invoked by entering the DOC1RFMT command with no parameters and pressing F4. The subsequent panel allows you to identify the required parameters. You can also use DOC1RFMT from the command line with parameters specified.

Syntax (program call method):

CALL DOC1RFMT PARM(‘INI=Ini’)

Parameter:

INI Ini is the library/file/member name of the Initialization File to control this execution of DOC1RFMT.

Example:

CALL DOC1RFMT PARM('INI=DOC1HOST/INI(RFMTINI)')


Running DOC1RFMT under OS/390

Purpose:


Preparation:

The INI file for Reformat under OS/390 typically references the required files by referencing DD labels specified in the JCL. The DD labels below are therefore examples only

JCL:

///Jobname JOB (Rest of Job Card parms)//DOC1RFMT EXEC PGM=DOC1RFMT,PARM=’INI=DD:IniDD’//STEPLIB DD DISP=SHR,DSN=DOC1 Load Library + Run-time libs//IniDD DD DISP=SHR,DSN=Dataset containing Reformat INI file//RFTINPUT DD DISP=SHR,DSN=Dataset containing application data//RFTLDF DD DISP=SHR,DSN=Dataset containing DOC1 data format //RFTXML DD DISP=SHR,DSN=Dataset to receive Reformat output//*

Parameters:

IniDD identifies the DD name used to define the dataset containing the Reformat Initialization File.

DD References:

All references other than that for the Initialization file itself are coded in the Reformat Initialization file.


MAKEEDF – Windows only

Purpose:

The MAKEEDF utility converts a DOC1 data format file in Workstation format (LDF) to ‘EMFE Ready’ format (EDF).

The EDF will be created in the same location as the LDF.

Preparation:

The utility is provided as part of DOC1 Workstation distribution material and runs from a Windows command prompt.

Syntax:

MAKEEDF [-e] [-d Directory] DataFormat

Parameters:

-e if this parameter is coded the EMFE Ready data format will be created suitable for EBCDIC hosts (OS/390 or OS/400). If it is omitted the data format will be suitable for ASCII hosts (all other supported platforms).

-d Directory is the path where the LDF to be converted can be found. If the parameter is not specified the file is assumed to be in the current directory.

DataFormat is the filename of the data format to be converted without extension

Example:

MAKEEDF -e -d\doc1\resource app511


Generating an OTS Finishing lineA finishing line is intended to control a user maintained post-process such as enveloping applications or checking the accuracy of an address before mailing. Output generated by DOC1 applications that use a finishing line object include additional controls within the output datastream that can be used to control the appropriate equipment/process at the customer site.

ONLY FINISHING LINES PREDEFINED TO THE DOC1 ENVIRONMENT CAN BE USED FOR THIS PURPOSE AND IT IS NOT POSSIBLE TO CREATE YOUR OWN. IF YOU ARE INTERESTED IN FINISHING LINE SUPPORT PLEASE CONTACT YOUR DOC1 SUPPLIER.

DOC1 provides specific support for finishing lines used in relation to applications maintained by the OTS agency on behalf of their clients. This section covers some of the considerations that you should bear in mind when creating an application with a finishing line for production at OTS. It is not an exhaustive list; a lot of the information required, for example, physical layout considerations, fonts etc., is beyond the scope of this document. Please contact OTS for full details.

See also the "Customizing the Run-time Environment/Customizing a Finishing line" section in the Production Guide and "Changing the EMFE Run-time Environment/Preparing for a finishing line" and other sections on Finishing line and Address block in the Designer’s Guide.

Available Finishing LinesThe finishing lines, or product lines, available for OTS are:

CFN-M continuous-form, non-integrated, multi-up, simplex

CFN-MD continuous-form, non-integrated, multi-up, duplex

CFN-MD2 continuous-form, non-integrated, multi-up, duplex, 2-form

where:

h

continuous-form means a roll-feed or fan-fold printer configuration.

non-integrated means that the printer is not integrated with the finishing equipment.

multi-up means that two or more logical pages are printed on one physical sheet side.

simplex means printing is done on the front sheet side only.

duplex means printing is done on both the front- and back-sheet sides.

2-form means two different forms of paper, each with a different appearance of some kind, are used to print the OTS summary and detail pages.


Restrictions

• Only AFPDS is supported.

• DOC1 does not support OTS disaster recovery records. Other arrangements will have to be made with OTS.

• Do not use MergeIAR.

• DOC1 does not provide the fonts to be used at OTS. These fonts need to be licensed from OTS or through a third-party.

Summary PagesFor CFN-M, the first logical page is always the summary page. For CFN-MD and CFN-MD2, the first two logical pages are the front and back of the summary page. The other pages in the document layout, if any, comprise the detail pages of the statement.

Address BlockThe Address Block object must be used for the statement and must appear on the first logical page. It is necessary even if OTS won’t be CASSing the data. An address block does not automatically generate OTS CASSing records. This is because the address block object is also used for documents that do not require OTS to CASS the statements.

OTS CASSingCASSing by OTS is controlled using the OTS CASS flag. This is part of the finishing line information and can have the following values:

Y indicates OTS CASSing. All OTS CASSing records will be generated.

However, CASSing will be disabled for an instance of a document when the country code in the address block is anything other than "" (blank), "US" or "USA", even though the OTS flag is Y.

THE POSTNET COMPONENT MUST BE SELECTED FROM THE ADDRESS BLOCK DIALOG IN THE ALE IF THE INITIALIZATION FILE SETTING OTS CASS = Y. REFER TO "REFERENCE/ADDRESS BLOCK " IN THE DESIGNER’S GUIDE FOR FURTHER DETAILS

C indicates that the statements have already been CASSed by the user. No OTS CASSing records will be generated.

If the initial value is C OTS CASSing is disabled for all documents in the file.

N indicates that the data hasn’t been CASSed and that OTS should not CASS it. No OTS CASSing records will be generated.

h

Generating an OTS Finishing line 161

If the initial value is N no further checking of the flag is performed during the run, and OTS and user CASSing are disabled for all documents in the file.At start-up, the initial value of the OTS CASS flag is used to set the field in the FILEHEAD record.

Document Layouts

Statements

Because of the OTS format requirements, a statement must be composed within a single document layout. It is not possible to use multiple document layouts to create a single statement (such as one for summary page and another for detail pages).

Multiple Document Layouts

If there are multiple document layouts within an application, they must all use the same finishing line. Note that referring to "no finishing line" is considered to be a type of finishing line.

Finishing line information fields

These can be set either in the ALE using the Action/Set finishing line info option or in the <FinishingLine> section in the EMFE initialization file. Note that if a field is set to spaces or is empty, it will be treated as though it hasn’t been specified.

Mandatory fields

The following fields must be set.

Corp IdRun DateResource SetCycle #

Job-level fields

The following fields are queried either at the end of the first page generated or at the end of the first data document, whichever comes first and the FILEHEAD record is generated.

Corp IdRun DateResource SetTransmission NumberOTS CASSCycle #

Changing the fields subsequently will have no effect other than the OTS CASS flag – see “OTS CASSing” on page 161.


Parallel Support

If you intend to run EMFE as a parallel process, then the following restrictions apply. Full details of parallel processing can be found in the "Alternative methods of running EMFE/Parallel processing mode" section in the Production Guide.

Synchronization point

If there is a Synchronization Point document layout that sets up global data for the job run, only job-level finishing line fields can be set. These are listed in the Finishing line information fields section above.

NOTE THAT SETTING DOCUMENT-LEVEL VALUES SET IN A SYNCHRONIZATION POINT WILL NOT WORK WHEN EMFE IS RUNNING IN PARALLEL MODE.

Document layouts

When producing an application that will be run in Parallel mode, a maximum of two document layouts can be used. If there are two, then one must be a synchronization point used to set global data.

Account number validation

Account number checking in successive documents is not always possible in parallel mode. This is because, in parallel mode, documents are not processed in the same order as the input data or the output datastream. If you want to guarantee account number validation, you must use standard EMFE.

FormDefs

DOC1 provides the following FormDefs to be used with the OTS product lines:

CFN-M F1D1M.AFP

CFN-MD F1D1MD.AFP

CFN-MD2 F1D1MD2.AFP

FormDefs are included by using the <Files>InlineResource option in the EMFE initialization file.

NOTE THAT FORMDEFS ARE NOT INCLUDED IN THE INSTALLATION PROCESS. THEY MUST BE COPIED TO THE HOST MANUALLY FROM THE \OTS DIRECTORY ON THE CD.

h

h


OTS RecordsThis section shows the different records generated for OTS support in which the user has control over one or more fields within the record. Each field shows whether it is generated by DOC1 or provided by the user, and how the user can set it. If a record type is not shown, it is because all its contents are generated automatically by DOC1 and cannot be controlled by the user.

DOC1 uses NOP, or comment, records which are inserted into the output datastream to hold the information that is required by OTS.

In the details for each record, the Set by column uses the terms:

System – to indicate a DOC1 automatically generated value.

Info – to indicate that the user sets the value using the Action/Set Finishing Line Info option in the ALE.

Address – to indicate that the user sets the value using an Address block object.

<section>keyword – to indicate that the user sets value in the EMFE initialization file.Note that <> means the <FinishingLine> section.

The Validation column specifies action taken by DOC1 if the value is validated while being processed.

Note that in some cases an incorrect value will be treated by EMFE as zero, for example, an incorrectly code packed number). If zero is a valid value for that field, then the finishing line validation will accept it.


File Header

The file header record is always generated and is inserted at the start of the datastream. It contains runtime information.

1 <> means the <FinishingLine> section in the initialization file.2 Whenever a value is detected as invalid, a message will be output to the user explaining why the value is invalid.

Field Name Length Description Values Set by1 Validation2

Record Length 05 Maximum length of record "512"– 32759

System (defaults to "8196") <AFPDS>MaxRecordSize

Cycle 02 Numeric cycle withinthe month

"01"–"31" <>CycleInfo (Cycle)

Aborts ifout of range

OTS Corp ID 05 The unique, OTS-assigned Corporate ID number

<>CorpIdInfo (Corp Id)

Aborts if not numeric

Run Date 08 The customer’s billing run date in the format mmddyyyy

System (Run Date)<>Run DateInfo(Run Date)

Aborts ifdate is.invalid

SummaryResource Rev #

06 The OTS-assigned printprofile ID

<>ResourceSet Info (Resource Set)

CASS Flag 01 "C" and "N" means that noCASS-related NOPs aregenerated.

"Y", "C",or N

"System (defaults to "Y")<>OTSCASSInfo (OTS CASS)

Uses defaultvalue if invalid.

TransmissionNumber

03 Incremented Transmission Sequence Number

System (defaults to "001")<> Transmission NumberInfo (Transmission Number)

Uses defaultvalue if out of range.

File Header Record (FILEHEAD)


Address2 InformationThis record is generated automatically when the OTS CASS Flag is set to "Y" and the Address Block object is processed. The NOP will not be generated unless the OTS CASS Flag is set to "Y".

1 <> means the <FinishingLine> section in the initialization file.2 Whenever a value is detected as invalid, a message will be output to the user explaining why the value is invalid.

EVEN THOUGH THE TABLE STATES THAT ADDRESS 1, ADDRESS 2, ETC. ARE STORED IN PARTICULAR FIELDS, THIS IS ONLY TRUE IF THE USER HAS PROVIDED DATA FOR EVERY AVAILABLE ADDRESS LINE. OTS REQUIRES ANY BLANK LINES BE SET IN THE LEADING FIELDS. SO IF THERE ARE ONLY 5 LINES OF ADDRESS DATA, ADDRESS LINE 1 WILL BE BLANK AND THE NAME WILL BE STORED IN ADDRESS LINE 2, AND SO ON.

Field Name Length Description Values Set By1 Validation2

Address Line 1 60 Customer name, business name, an address line, or blanks if not used

Address (Name)


Address (Address 2)


Address (Address 3)


Address (Address 4)


Address (Address 5)

Address Line 6 60 City/State/Zip line – comprisedCity name, a two-char State codeand a 10-char ZIP code

Address (City)Address (State)Address (Zip)

Address Type 1 Residential orBusiness address type

"R""B"

System (Defaults to "R")Info (Business/Residential Flag)

Uses defaultvalue if out of range.

Address2 Information Record

h


Postal Information NOP/PTX

This data is stored in the PTX stream printed on the page and not in a NOP. The data value is generated automatically when the Address Block is used.

EVEN IF THE USER SETS THE OTS CASS FLAG TO "C", THE APPLICATION MUST CONTAIN AN ADDRESS BLOCK OBJECT SO THAT THIS BARCODE WILL BE GENERATED.

Zip Code NOP/PTX

This data is stored in the PTX stream printed on the page and not in a NOP. Even though OTS may overwrite the field, the data value is populated with the value of Address (Zip Code) if they are doing the CASSing.

The NOP is generated automatically when the OTS CASS flag is set to "Y" and the Address Block object is processed. This NOP will not be generated unless the OTS CASS flag is set to "Y".

h


Statement Trailer

This record is always included once per document and contains details of that document.


Account Number 50 Unique tracking number System (defaults to Statement sequence)Info (Account Number)

If not unique, a warning message

is produced

Statement Type 01 Bill Type Handling GroupIf Special Handling Code is set to other than "99", valueis set to "H" for Normal billsor "G" for Forced Flat Bills.

"0", "H""A", "G"

System (defaults to "0"Info (Statement Type)

Invalid values default to "0" (zero) for Normalbills and "H" for NormalHeld/Special Handled

bills.

Number ofCopies

02 The number of copies ofthis statement includingthe original

"01-99" System (defaults to "01")<>CopiesInfo (Copies)

Uses default value if invalid

ZIP Code 12 The ZIP+4 Code Address (Zip Code)

Special HandlingCode

02 Special handling option3, 4 "01-79" System (defaults to "99")Info (Special Handling Code)

Invalid values default to "99".

No-Print Switch 01 Whether statement shouldbe printed or not.

"Y""N"

System (defaults to "N")<>NoPrintFlagInfo (No Print Flag)


Country Code 03 See note 5. System (defaults to Blanks)Info (Country Code)

Original Insert Combo

11 Bill Inserts System (defaults to all "N"s)Info (Insert Combo 1-11)

At most 5 of the flags 1-10 can be Y. The rest

will be forced to N if necessary and warning

message produced.

State Code 02 See note 6. System (defaults to Blanks)Address (State) if two lettersotherwise Info (State Code)

Total DollarAmount

10 Total monies due on this

particular statement/document7System (defaults to Zeros)Info (Total Dollar Amount)


Statement Trailer Record


1 <> means the <FinishingLine> section in the initialization file.

2 Whenever a value is detected as invalid, a message will be output to the user explaining why the value is invalid.

3 Bulkies have a "G" Statement Type and a "99" Special Handling Code and override any user set value.

4 A "spoiled" document is one which has had some kind of problem during composition or with incoming data that cannot be overridden with a known valid value. The strategy being employed by the initial release of the DOC1 Interface is that there will be no known spoilable conditions, i.e., that would force DOC1 to set the Statement Type to "H" and the Special Handling Code to "00". If a data override/default value is used instead of incoming data, this will be flagged by a message indicating what has happened and to which document. The user will then be responsible for determining what to do with the "offending" or "spoiled" document.

5 Must be a valid 2-byte or 3-byte Country Code. See OTS and UPU documentation for a list of country codes. Non-US countries should be set to "H" or "G" (HELD) to ensure correct handling. DOC1 does not validate this field.

6 Must be a valid 2-byte State Code. See OTS documentation for a list of state codes. DOC1 does not validate this field.

7 This must not contain any currency symbol. Valid characters are numbers, ‘+’ (plus),’-’ (minus) and ‘.’ (decimal point). The number must have 2 decimal places; if there is no decimal point then one is assumed, for example, 123 is taken to mean 1.23.

Dollar Sign Value

01 " ""-"

System (defaults to Blank)Info (Total Dollar Amount)


Carrier Route 04 The carrier route populatedNote: This field is not tied to CASSing

System (defaults to Blanks)Info (Carrier Route)

Product Code 03 " " or"E01"

System (defaults to Blanks)Info (Product Code)Info (E-Bill Flag) when set to Y will set this to "E01".

Uses default value if invalid


Statement Trailer Record


Initialization File Settings

This section within the EMFE initialization file allows you to define settings specific to finishing line processing. Refer to "Appendix A/FinishingLine Section" in the Production guide for further details.

Syntax and defaults:

<FinishingLine>Cycle=Number ;no defaultCorpId=Number ;no defaultRunDate=Datecode ;no defaultResourceSet="String" ;no defaultOTSCASS={Y|C|N} ;default YTransmissionNumber=Number ;default 1Copies=Number ;default 1NoPrintFlag={Y|N} ;default N

Data types:

Number is a positive integer.

String is a string of alphanumeric characters.

Datecode date in the format MMDDYYYY.


Cycle Number is the cycle within the month.

CorpId Number is the OTS assigned corporate-id number.

RunDate Specifies the Datecode to be used as the customer billing date.

ResourceSet Number is the OTS assigned print profile-id.

OTSCASS If set to C or N then no CASS related NOPs are generated. If set to Y then the PostNet component must be selected in the Address Block dialog, refer to "Reference/Address Block" in the Designer’s guide for further details on PostNet processing.

TransmissionNumber Incremented transmission sequence Number.

Copies Number of copies of statement.

NoPrintFlag If set to N then statements will be printed.

Example:

<Finishingline>Cycle=15CorpId=5339RunDate="01152001"ResourceSet=3297OTSCASS=YTransmissionNumber=1Copies=1NoPrintFlag=N


User Exits

This section describes the programming requirements for DOC1 applications using the user exit feature.

A user exit initiates an external user–defined program which, typically, performs functions which are outside the scope of DOC1 features as externalized in the ALE or the PCE script language.

There are three main types of user exit that perform particular functions:INSTRUCTION exits allow EMFE and PCE to simply execute a user program and optionally return a value that can be used within the DOC1 application; DATA_INPUT exits allow a user program to directly provide the application data to processed by EMFE;PRINTSTREAM exits allow pre-composed print elements to be added to some types of composed output datastream.

DOC1 programs interface with user programs by calling with a specific invocation mode indicating the expected function. For instance, all user programs will first be called in initialization mode to give the program the opportunity to perform any required set-up functions. Other calls with different modes are made as appropriate to the type of exit. The user program must be coded to handle all such calls

If you want to pass or receive values to/from user programs you will need to use the functions provided with the User Exit Data Exchange API.

Summary of RequirementsTo set-up a user exit for use with a DOC1 program you must:

1. Create the program(s) to be called by EMFE/PCE. You will need to:

• allow for all invocation modes;

• note which DOC1 memory cells are used (if any) and what they are used for;

• link the program with the Data Exchange API if required.

2. Reference the user exits in the DOC1 application design –

For EMFE this will be in the application rules via the ALE.

• create User Function or User Value objects as appropriate in the Application Layout Editor;

171

• ensure that all the parameters required in the user program are passed in the correct memory cells.

For PCE this will be with the let...call userexit command.

• include the LET … CALL USEREXIT command at the appropriate place in the PCE script;

• ensure that all the parameters required in the user program are passed in the correct memory cells.

Note that DATA-INPUT exits do not require such an interface.

3. Setup the EMFE/PCE environment:

• create a User Exit control file that has entries for all functions in the user programs to be used;

• reference the User Exit control file in the Initialization or Configuration file to be used with the EMFE/PCE application.

172 User Exits

Types and purpose of user exitsIn the User Exit Control File programs are identified as being of a specific type. The various user exit types indicate specific functionality and are handled differently by the DOC1 application.

Instruction typeAn INSTRUCTION exit is a straightforward call to an external user program within a DOC1 application. The program can optionally return a value that can be used within the DOC1 application.

The function of the program is completely at the discretion of the user but typically involves the manipulation of data using specialized procedures.

Data_Input typeA DATA_INPUT exit allows the user program to provide the application data that is the input to EMFE applications. Each call to the exit must return one complete data record which must have a structure and sequence that matches the data format being used with the application. Note that, when used, a DATA_INPUT user exit must completely replace the EMFE input process, i.e. you cannot mix a regular application data file with records provided via the exit.

EMFE may only use a single DATA_INPUT user exit per application.

Printstream typeA PRINTSTREAM exit allows the user program to create or reference a self-contained segment of print datastream and then return it to the DOC1 application for inclusion in the page being composed when the exit is called. The value returned by such an exit is a pointer to the required object/segment.

PRINTSTREAM user exits are supported only if your application is generating AFPDS, Metacode, PostScript or PDF. Additionally, they can only return the specific datastream segments (objects) identified below

The data to be included in the print datastream must be self-contained in as much as it must contain all commands necessary to position and format the required output independently of the DOC1 application and must leave the datastream in the same state as when the exit was called.

The following are general rules that should be adhered to regardless of the datastream being generated:

Types and purpose of user exits 173

• The object being returned must be of the same type of print datastream being generated by the calling application.

• Return data must not generate a new page or close the current document.

• Any text returned must only use fonts already used by the application, i.e. that are referenced in the font metrics file being used.

• If a user exit is called as part of a relative positioning operation, you may need to pass your program dynamic positioning coordinates.

AFPDS

You must return a complete object recognized by the AFPDS architecture such as a GOCA image.

The object will be inserted after the Active Environment Group records. It must contain an MCF-1 record with the list of fonts used within it. Any font used in the GOCA object (but not the page) is added to the page MCF and given an index of 0xFE.

Providing you follow the documented architecture you can be confident that the returned object is compatible with the state of the existing datastream. Refer to the appropriate AFP reference manual for details.

You should ensure that the maximum possible record produced by the user exit is supported by the file system.

PostScript and PDF

You must return one or more valid datastream commands ensuring they form a valid and complete sequence and contain appropriate positioning commands.

Any fonts, images or dictionaries referenced must be appended to the output file (using DOC1PJC) at the end of the run. PDF only supports Base 14 fonts or fonts used within the current page and can only reference images used within the page. Additional image data must be in-line.

Metacode

The user program must return only a complete in-line IMG graphics object – other Metacode or Xerox structures are not supported. Additionally, it must be prefixed with the user exit object header to inform the DOC1 program where to place the graphic on the current page.

174 User Exits

User exit object header

This structure is used as part of printstream user exit return data to provide additional positioning information. It is only required where the object being returned contains insufficient information for the DOC1 environment – see the information for the appropriate output datastream above.

Structure:

32 bytes as follows

Position Name Type Min Max Value Description

0 Printstream Id Byte n/a n/a 0 Defines Metacode.

1 Object type UChr n/a n/a ’G’ Defines graphic object

2-7 Name UChr6 n/a n/a n/a Reference name for the object. Note that for Metacode applications this must be in upper case characters only.

8-11 X Offset Ulong 0 n/a n/a X offset for positioning object specified as PELS

12-15 Y Offset Ulong 0 n/a n/a Y offset for positioning object specified as PELS

16-19 X Size Ulong 0 n/a n/a Width of the object specified in PELS

20-23 Y Size Ulong 0 n/a ’n/a Height of the object specified in PELS

24-27 Object length Ulong 0 n/a n/a Length of the object being returned as a number of bytes. Note that this value should not include the size of the object header itself.

28-31 Reserved Ulong n/a n/a 0 Reserved for expansion. Must be 0 (zero)

Types and purpose of user exits 175

Preparing DOC1 applications for user exitsThis is a summary of the information provided in the relevant sections of the Designers Guide, Production Guide and the “Programming PCE” on page 13 of this guide. Refer to these for full details.

EMFE applicationsUser exits of type DATA_INPUT have no interface to the application other than through program calls. Refer directly to “Creating the user program” on page 180 for details.

For user exits of type INTRUCTION or PRINSTREAM the required calls are included in application logic using one of two objects in the Application Layout Editor (ALE) on the Workstation:

• User Value performs a function which returns a value that may be used in ALE logic

• User Function performs a function but does not return a value that can be used in ALE logic. However, a user function can return a segment of AFPDS, PDF or PostScript datastream if you are calling a PRINTSTREAM user exit.

The memory cells to be accessed by a user program plus the name by which the program is referred to in the User Exit control file are defined as part of the ALE objects.

When creating a User Function or User Value object in the ALE, the user needs to provide the following information in the appropriate dialog box:

EMFE IdentifierEnter the Identifier that has been specified for the function in the User Exit control file.

Parameter referencesUse the Name entry field to generate an ID for each parameter. Note that this is only used as a reference in the ALE and does not affect user exit processing. Specify a Cell identifier for the parameter in the range 9900-9998. This must match the value specified for the parameter in the Data Exchange API function being used with the user program. Use the Add push button to create the parameter reference. Repeat for each required parameter.

Example return valueThis is required for User Value objects only. Use the Editor Value entry field to provide a string which will be used when evaluating the object in the ALE. This is used on the workstation only and in no way affects EMFE host processing where the user exit should provide the returned value.

176 User Exits

In the logic map view an independent User Parameters will be generated as child objects to user exit objects for each parameter reference used. When expanded the User Parameter will have a Place Holder which can be resolved with a further object as required.

PCE applicationsIn a PCE control file you need to code a let … call userexit command to execute a user program via the user exit feature. You should refer to “Programming PCE” on page 13 of this guide for full details of PCE command structure and syntax. However, the following summarizes the format of the required command:

[let <Result> = ]call userexit {"Identifier"} [[with <Parameter> in nnnn]…];

The user defined program specified by "Identifier" in the User Exit control file being used by the PCE application will be executed. Any value returned by the user exit program will be stored in <Result> if this is coded. Optional parameters <Parameter> are passed to the program via PCE memory cell nnnn.

The program name must be an identifier specified in the appropriate User Exit control file. The parameter can only contain a STRING or PAGE data type; NUMBER and DATE data types are not supported. The PCE memory cell for the parameter must be in the range 9900–9998 and must match the appropriate number specified in the UEDEA function being used by the user program. The result value, if used, will always be interpreted as type STRING.

Preparing DOC1 applications for user exits 177

User Exit control file format

Purpose:

This file is the interface between EMFE or PCE and any user defined program functions that need to be called.

Preparation:

A call to a user exit program is specified via the ALE User Function and User Value for EMFE applications or the PCE let...call userexit command. All three specifications are dealt with in exactly the same manner as far as the User Exit control file is concerned.

Syntax:

Identifier Exit_type Call_type Module Function...Identifier Exit_type Call_type Module Function

Parameters:

Identifier is a string identifying the name used in the user exit object in the ALE or the PCE let...call userexit command.

Exit_type is a string identifying the type of DOC1 user exit used by this call. Options are:INSTRUCTION - the user program optionally returns a value that is used by EMFE or PCE logic.PRINTSTREAM - the user program always returns a self-contained segment of output datastream for inclusion in the page currently being composed.DATA_INPUT – the user program provides the application data for EMFE (only). It returns one or more complete records in the sequence expected by the data format being used with the application.

Call_type is a string specifying a code that identifies the required type of system linkage. Options are:MVS_C – C language call from OS/390 or equivalentMVS_COBOL – Cobol call from OS/390 or equivalentNT_SYSTEM - any call from Windows NT or equivalentOS2_SYSTEM – any call from OS/2AS400_ILE – C language call (ILE compiler only) under OS/400.UNIX_SYSTEM – any call from any supported UNIX variant

Module is a string identifying the filename of the load module containing the user routine.Under OS/390 this will be the name of a member in a load library assigned to STEPLIB in EMFE or PCE start-up JCL.Under OS/2 or Windows this is the path/filename of a .DLL file (no file extension required). The path may be omitted if the DLL is in a path identified in an environment setting such as LIBPATH under OS/2.

178 User Exits

Under OS/400 this is the path/filename of a *PGM file. The path may be omitted if the file is in a library that is part of *LIBL.Under UNIX this is the path/filename of a program file.

Function is a string which identifies the function that is the required entry point into the load module (e.g. the C language function name).

other syntax Comments can be included by coding an asterisk in column 1.

Examples:

*ID Exit Type Call Type Module Function*******************************************************************CALL1 INSTRUCTION NT_SYSTEM MYDLL MainCALL2 INSTRUCTION MVS_COBOL DOC1EXIT GoExitCALL3 PRINTSTREAM UNIX_SYSTEM /DOC1EXIT/AFPSUPP AddGocaCALL4 DATA_INPUT AS400_ILE DOC1PROG Doc1Call

Preparing DOC1 applications for user exits 179

Creating the user programThe user program can be written in C or Cobol when intended to execute under OS/390 or in C only when intended to execute on OS/400, NT, OS/2 or supported UNIX platforms.

Note the following:

• The user program should not terminate the DOC1 program even if it is believed the application has completed. This may result in the output datastream being generated by the application being incomplete.

• If the program calls modules in other languages it is the users responsibility to ensure that all inter-language linking issues are properly resolved.

• Under OS/390 you may only initiate one user exit function for each load module referenced in the user exit control file.

• Under Windows all user exit functions called by a single DOC1 program should be contained within a single DLL to prevent memory fragmentation.

About memory cellsDOC1 applications uses memory cells to retain data. Such memory cells can contain all required data types (number, string, date, etc.) plus the supported PRINTSTREAM objects. Each cell is given a number in the range 0–19999 and is referred to by this number in the application rules.

Memory cells 9900–9999 are reserved for communication with user programs. Memory cell 9999 is specifically reserved for return values from user exit programs including PRINTSTREAM objects where it acts as a pointer to the required data.

N.B. The effects of a user program not returning a value to a User Value object (as it is known in the ALE) is undefined. The Workstation Build process has no way of knowing if the user program used will return a value and thus cannot perform any error checking.

Other memory cells in the valid range can be used with the Data Exchange API to pass values between the user program and the DOC1 application. You do not have to use memory cell numbers in successive order although it is recommended to do so.

IMPORTANT: DO NOT USE MEMORY CELLS OTHER THAN 9900–9999! DOING SO MAY CAUSE DATA ERRORS ELSEWHERE IN AN APPLICATION.

You do not normally need to work with memory cells when coding a DATA_INPUT user exit.

h

180 User Exits

InitiationEach program to be used with user exits must be referenced in the User Exit Control File assigned to the application in the Initialization File. The Control File contains the name of the program to be used plus the function name which is the required entry point within the user program. On platforms other than OS/400 the function will automatically be called if it is specified.

Under OS/400 this function name is passed as a null terminated string which must be handled by the main function of the program. Main must call function UxitCallFunction (provided within DOC1FUNC) with a pointer to the function intended to act as the entry point. UxitCallFinction will then call the named function with the three environment parameters as usual. For example:

void main(int argc, char *argv[]){... if (strcmp(argv[1],"EntryPointFunction") == 0) UxitCallFunction(EntryPointFunction); ...}

Program calls and data exchangeThe DOC1 application will make a series of calls to each user program referenced in the user exit control file. The type and number of these calls will depend on the exit type indicated – see “Invocation modes” below for details

Each time a call is made three parameters are passed to the user program which are pointers to pre-defined structures. The user program must be able to interpret and manipulate these structures

For exits of type INSTRUCTION and PRINTSTREAM the following structures are passed:InvocationMode, ApiData and ReturnStatus

For exits of type DATA_INPUT the following structures are passed:InvocationMode, EmfeInputData and ReturnStatus

Details of these can be found in “Structures used with program calls” on page 184.

Where values not catered for by these structures need to be passed between the DOC1 and user program you will need to be aware of the structures and functions of the Data Exchange API. You will also need to include a reference to the user exit definition file that is provided on all platforms as part of DOC1 distribution material. Refer to “User Exit Data Exchange API” on page 188 in this section for details.

Creating the user program 181

Invocation modesThe InvocationMode structure is passed to the user program with each call made by the DOC1 application. This indicates the function that is currently being processed and thus the expected operation by the user program. The user program must be coded to respond to every mode that might occur for the exit type being used.

The following lists the possible invocation modes (identified by the keywords within the InvocationMode structure):

INIT Initialization. Whenever a user program is first referenced by the DOC1 application it will be called in the initialization mode. This gives the user program the opportunity to perform any necessary initialization. If the user program is defined but the opportunity for it to be called never occurs, it will never be initialized.

EXEC Execution. This mode is invoked for INSTRUCTION or PRINSTREAM exits when the DOC1 application needs the user program to perform its primary task. The number of times the user program is called in this mode depends on how often the instruction(s) referring to it are executed. This mode is never called for DATA_INPUT exits.

DIED Fatal termination. If the DOC1 application is terminating in abnormal circumstances (i.e. when the complete application run is not yet complete for some reason) this mode is called. This gives the user program the opportunity to perform any tidying up. If the user program is never initialized, it cannot die.

TERM Normal termination. When the DOC1 application is about to complete successfully the user program will be invoked in the termination mode. This gives the user program the opportunity to perform any necessary clean up operations. If the user program is never initialized, TERM will not be called.

OPEN Open data input channel. If a DATA_INPUT exit is specified this mode will be called prior to a first request for application data. The user program should open the appropriate input channel in response to this call. When OPEN is called the following fields in the EmfeInputData structure provide information:pbData – contains a pointer to a buffer containing the name of the input file (null terminated) specified in the Initialization fileCbData – contains the length of the name referenced by pbData (excluding the null terminator)

TELL Report offset within data input. If a DATA_INPUT exit is specified this call is made prior to a READ call so that the DOC1 application can cache the relevant offset. The user program must update the ulLocation field with the offset value within the EmfeInputData structure. If your environment does not support Seek functions (e.g. the user exit is accessing a database) you should return 0xffffffff as ulLocation to indicate this to the DOC1 application. You should be aware however, that the application will fail should it become necessary to perform a seek.

182 User Exits

READ Read a record. If a DATA_INPUT exit is specified this mode will be called whenever a new record is required for processing. The user program must update the following fields in the EmfeInputData structure:pbData – a pointer to the buffer holding the input recordcbMax – indicate the size of the buffer holding pbData.

SEEK Seek within data input file. If a DATA_INPUT exit is specified this call requests the user program to move the file pointer of the input file. The ulLocation field within the EmfeInputData structure will provide the requested offset. Note that this call is not made regularly but due to the way DOC1 applications store data it may be necessary to reprocess input records in some circumstances.

CLSE Close data input file. If a DATA_INPUT exit is specified this call will be made when the DOC1 application believes it has reached the end of the data file. It will also be called prior to DIED in an abnormal termination situation if a data file is open.

Return DataUser exit functions that are marked as type INSTRUCTION in the User Exit control File can optionally return a value that can be used in EMFE or PCE application logic. The value returned must be compatible with the DOC1 logic being used, e.g. if you have created a User Value object as part of an Arithmetic group in the ALE then the user function must return a number for results to be predictable.

Functions that are marked as type PRINTSTREAM are intended to return a pointer to a complete object (or other valid segment of print datastream) held in memory which will then be incorporated into the page of print datastream being composed when the exit is called.

Return data from both the above must be loaded into memory cell 9999 so that it can be accessed by the DOC1 application.

CALLS TO THE DATA EXCHANGE API MAY RETURN VALUES TO OTHER MEMORY CELLS. REFER TO “USER EXIT DATA EXCHANGE API” ON PAGE 188 IN THIS SECTION FOR DETAILS.

Functions of type DATA_INPUT return the required application data records as part of the EmfeInputData structure. Memory cells are not used when returning this type of data.

h


Structures used with program calls* Note that the byte offset values indicated by the Position fields do not apply under OS/400 where all offsets commence on a 16-byte boundary.

InvocationMode

This structure specifies the mode in which the DOC1 application is calling the user program. The user program must be able to respond to all invocation modes that may occur.

Structure:

Five bytes as follows

ApiData

The API data structure contains information needed to access data stored within memory cells. The precise format is outside the scope of this document.

The user program accesses data contained within this data structure through the Data Exchange API.

Structure:

128 bytes as follows

Position* Name Type Min Max Value Description

0-3 Mode Chr4 n/a n/a Invocation mode.

"INIT" Initialization command.

"TERM" Normal.

"DIED" Fatal termination notification.

"EXEC" Execute command.

"OPEN" Open a file for use with DATA_INPUT functions

"READ" Read a record from a DATA_INPUT file

"TELL" Return current offset in a DATA_INPUT file

"SEEK" Move file pointer within a DATA_INPUT file

"CLSE" Close a DATA_INPUT file

4 Null Chr1 x00 x00 Null termination byte. Always hex 00.


0-128 Reserved Bin128 n/a n/a n/a Private data.

184 User Exits

EmfeInputData

The EmfeInputData data structure provides a shared buffer when working with a DATA_INPUT type user exit. Note that some of the fields within the structure are used for different purposes depending on the invocation mode.

Structure:

17 bytes as follows

ReturnStatus

The Return Status data structure allows the user program to specify a return code indicating the success of the user program invocation as well as an optional message which can be displayed through EMFE or PCE reporting functions.

Structure:

136 bytes as follows


0 Id UBin4 0 0 0 Always 0 in current implementation

4 pbData SBin4 n/a n/a n/a Pointer to data buffer.

8 cbMax UBin4 n/a n/a n/a Maximum size of buffer referenced by pbData. Note that when reading from a data file this value should match the <System>MaxRecordSize setting in the Initialization file being used with the DOC1 application.

12 cbData UBin4 n/a n/a n/a The amount of valid (relevant) data currently held at pbData.

16-19 ulLocation UBin4 n/a n/a n/a Contains a byte offset to indicate location within data input file


0 Return Status UBin4 0 4 Return Status

0 OK - Sucessful completion.

1 Pass - Declines open invocation.

2 Warning - Error occurred but EMFE/PCE should not terminate.

3 Fatal - Error occurred and EMFE/PCE should terminate.

4 Msg Length UBin4 0 128 Count of valid bytes in message. Only checked if Return Status is 2 or 3.

8 Message Chr128 n/a n/a n/a Optional message text. Only characters up to Msg Length are considered valid.


Compiling & linkingIf you want to pass or receive values to/from user programs you will need to work with the additional files provided as the DOC1 Data Exchange API. These are provided with DOC1 host distribution material.

Windows & OS/2

User programs coded in C only are supported. The program must be exported as a DLL.

Programs using the Data Exchange API must include a reference to the user exit definiton file edxc.h and must be linked with the C language support module edxc.obj.

edxc.obj is built using the Microsoft Visual C++ compiler for Windows and the IBM Visual Age C++ compiler for OS/2.

UNIX

User exits can be used on all DOC1 supported UNIX platforms with the exception of SCO. User programs must be coded in C only and must be generated as UNIX shared objects or equivalent.

On most supported UNIX platforms shared object status is achieved by using an appropriate link option:

Digital: -msym -sharedHPUX -bSun: -G -K pic -lelfUnder AIX the module must be exported. For example:AIX: -bE:name.exp -bM:SRE

Programs using the Data Exchange API must include a reference to the user exit definition file edxc.h and must be linked with the C language support module edcx.o.

OS/390

User programs can be coded in C or Cobol. Cobol modules must be compiled using the Apostrophe, Reentrant and Reusable options as in the following JCL fragment:

//COMPILE EXEC PGM=IGYCRCTL,REGION=512K,PARM=(APOST,RES,RENT)

C programs using the Data Exchange API must include a reference to the user exit definition file EDXCH and must be linked with the C language support module EDXC.

Cobol programs using the Data Exchange API must be linked with the Cobol language support module EDXCOB.

186 User Exits

Regardless of the language used for the user program, it must always be linked to the C run-time library as this is the language in which the API module communicates with it. Cobol user programs must additionally link with the Cobol run-time library as in the following example JCL fragment:

//LKED EXEC PGM=IEWL,PARM=’AMODE(31)’//SYSLIB DD DSN=SYS1.COB2.COB2LIB,DISP=SHR// DD DSN=EDC.V2R1M0.SEDCBASE,DISP=SHR// DD DSN=PLI.V2R3M0.SIBMBASE,DISP=SHR//SYSLIN DD DSN=USER001.MYLIB.OBJ(MYPROG),DISP=SHR// DD DSN=USER001.EMFE.OBJ(EDXCOB),DISP=SHR//* DD DDNAME=SYSIN//SYSLMOD DD DSN=USER001.MYLIB.LOADLIB(MYPROG),DISP=SHR//SYSPRINT DD SYSOUT=*//SYSUT1 DD DSN=&SYSUT1,SPACE=(32000,(30,30)),UNIT=VIO,// DISP=(NEW,DELETE)//SYSIN DD * ENTRY MYPROG/*//*

OS/400

User programs must be coded in C only.

Programs using the Data Exchange API must include a reference to the user exit definition file EDXCH and must be linked with the C language support module EDXC.

The EDXC module is compiled using the ILE C/400 compiler and has type *MODULE and an attribute of CLE.

You can link with this module using the CRTPGM command with the DOC1 and user programs referenced in the module list parameter. The program must have an activation group of *CALLER. For example:

‘CRTPGM PGM(USERPROG) MODULE(EDXC USERPROG) ACTGRP(*CALLER)

Run-time requirementsThe following rules apply to the location of the user program:

OS/390: it must be included in the load library concatenation in the STEPLIB statement of the appropriate EMFE or PCE start-up JCL or in the active link list.

OS/400: both the user program and the DOC1 program module DOC1FUNC must be in a library referenced in the active library list (*LIBL).

Windows, UNIX or OS/2: it must be in a path identified in an environment setting such as the PATH.


User Exit Data Exchange APIThe User Exit Data Exchange API is provided as a mechanism for user programs to access run-time data stored within the memory cells used by EMFE and PCE. The following table summarizes the available functions.

Details for each function follows below.

Array Functions

The array related functions provided are specific to PCE and intended only to operate with predefined types of element. For the current implementation the array can only be a segment of a print datastream supported by PCE and an element is considered to be an individual record within the datastream.

Operation Available for ’C’ function Cobol Function

Read a string EMFE & PCE UxitGetString LEMGSTR

Return a string/object EMFE & PCE UxitPutString LEMPSTR

Get array count PCE UxitGetArraySize LEMGSIZ

Get array elementt PCE UxitGetArrayElement LEMGELM

Data Exchange API functions to access memory cells

188 User Exits

C Functions

UxitGetString

Synopsis Gets a string from a memory cell. UxitGetString copies the contents of the memory cell into puchString; not exceeding the number of bytes specified in cbMax. The number of characters copied is put into *pcbString. If cbMin is non-zero, UxitGetString will pad the difference between cbMin and *pcbString with spaces.

Prototype void UxitGetString (PEMFEEXITDATA ped, unsigned int idCell, unsigned char *puchString, unsigned int cbMin, unsigned int cbMax, unsigned int *pcbString);

Parameters ped Pointer to EMFEEXITDATA.idCell EMFE memory cell id.puchString Points to string to store string.cbMin Minimum size of string.cbMax Maximum size of buffer pointed by puchString.*pcbString Count of bytes in string.

Return Codes None

Example // Get the string in memory cell 9900UxitGetString (ped, 9900, szBuffer, 0, sizeof (szBuffer), &cbBuffer);

UxitPutString

Synopsis Puts a string into a memory cell. UxitPutString copies the string data specified by puchString for the length of cbString. Terminating null should not be included in the string size.

Prototype void UxitPutString (PEMFEEXITDATA ped, unsigned int idCell, unsigned char *puchString, unsigned int cbString);

Parameters ped Pointer to EMFEEXITDATA.idCell EMFE memory cell id.puchString Points to string to putcbString Count of bytes in string.

Return Codes None

Example // Return a string in memory cell 9999UxitPutString (ped, 9999, szBuffer, cbBuffer);

User Exit Data Exchange API 189

UxitGetArraySize — PCE only

Synopsis Gets the number of predefined elements in a predefined array structure stored in a memory cell. See “Array Functions” on page 188 above for definitions. UxitGetArraySize returns in *pcElements the number of elements in the array. If the memory cell idCell does not contain a predefined array type then zero will be returned.

Prototype void UxitGetArraySize (PEMFEEXITDATA ped, unsigned int idCell, unsigned int *pcElements);

Parameters ped Pointer to EMFEEXITDATA structure (private).idCell Memory cell id.*pcElements Number of elements in the array to be returned.

Return Codes None

Example // Get the number of elements in the array in memory cell 9930// ped has been previously passed to the main functionUxitGetArraySize (ped, 9930, &cElement);

UxitGetArrayElement — PCE only

Synopsis Reads a predefined element from a predefined array structure stored in a memory cell. See “Array Functions” on page 188 above for definitions.UxitGetArrayElement copies the contents of the array element into a buffer *puchData. If the memory cell does not refer to a predefined array type or the requested element does not exist, 0 bytes are returned.

Prototype void UxitGetArrayElement (PEMFEEXITDATA ped, unsigned int idCell, unsigned int nElement, unsigned char *puchData, unsigned int cbMax, unsigned int *pcbData);

Parameters ped Pointer to EMFEEXITDATA structure (private)idCell PCE/EMFE memory cell id.nElement Element of the array. The first element is 0.*puchData Buffer to store array element.cbMax Maximum size of buffer pointed to by puchData.*pcbData Number of bytes in element to be returned

Return Codes None

Example // Get the 3rd element of an array in memory cell 9940// ped has been previously passed to the main functionvoid UxitGetArrayElement (ped, 9940, 2, auchData, sizeof (auchData), &cbData);

190 User Exits

C Definitions

Invocation mode

typedef struct { unsigned char auchMode[5]; // Null terminated string. } MODE, *PMODE;

EMFE Data

typedef struct { unsigned char abReserved[128]; // Unknown structure. } EMFEEXITDATA, *PEMFEEXITDATA;

EMFE Input Data

typedef struct { unsigned long int id; // Internal identifier (unused) unsigned char* pbData; // Data buffer unsigned long int cbMax // Max size of data buffer signed long int cbData; // Size of relevant input data unsigned long int ulLocation; // Current offset within input file } EMFEINPUTDATA, *PEMFEINPUTDATA

Return Status

typedef struct { unsigned long int ulReturnStatus; // Return status unsigned long int cbMessage; // Number of bytes in message unsigned char szMessage[128]; // Message string } EMFESTATUSDATA, *PEMEFSTATUSDATA;


Cobol Functions

LEMGSTR

Synopsis Gets a string from a memory cell.

Call CALL 'LEMGSTR' USING W-RESERVED-AREA W-MEMCELL-ID W-TEXT-BUFFER W-MIN-BUFF-SIZE W-MAX-BUFF-SIZE W-TEXT-LENGTH

Parameters 01 W-MEMCELL-ID PIC S9(9) COMP VALUE ZERO. 01 W-TEXT-BUFFER PIC X(200) VALUE SPACES. 01 W-TEXT-LENGTH PIC S9(9) COMP VALUE ZERO. 01 W-MIN-BUFF-SIZE PIC S9(9) COMP VALUE +200. 01 W-MAX-BUFF-SIZE PIC S9(9) COMP VALUE +200.

Return Codes None

Example * Get the string in memory cell 9900 MOVE 9900 TO W-MEMCELL-ID. MOVE 'Some text string .... ' TO W-TEXT-BUFFER. MOVE +22 TO W-TEXT-LENGTH. CALL 'LEMGSTR' USING W-RESERVED-AREA W-MEMCELL-ID W-TEXT-BUFFER W-MIN-BUFF-SIZE W-MAX-BUFF-SIZE W-TEXT-LENGTH

192 User Exits

LEMPSTR

Synopsis Puts a string into a memory cell.

Call CALL 'LEMPSTR' USING W-RESERVED-AREA W-MEMCELL-ID W-TEXT-BUFFER W-TEXT-LENGTH.

Parameters 01 W-MEMCELL-ID PIC S9(9) COMP VALUE ZERO. 01 W-TEXT-BUFFER PIC X(200) VALUE SPACES. 01 W-TEXT-LENGTH PIC S9(9) COMP VALUE ZERO

Return Codes None

Example * Return a string in memory cell 9999 MOVE 9999 TO W-MEMCELL-ID. MOVE +22 TO W-TEXT-LENGTH. CALL 'LEMPSTR' USING W-RESERVED-AREA W-MEMCELL-ID W-TEXT-BUFFER W-TEXT-LENGTH

LEMGSIZ — PCE only

Synopsis Gets the number of predefined elements in a predefined array structure stored in a memory cell. See “Array Functions” on page 188" for definitions.LEMGSIZ returns in W-ELEMENT-COUNT the number of elements in the array. If the memory cell W-MEMCELL-ID does not contain a predefined array type then zero will be returned.

Call CALL 'LEMGSIZ' USING W-RESERVED-AREA W-MEMCELL-ID W-ELEMENT-COUNT

Parameters W-RESERVED-AREA PIC X(128) API data (private)W-MEMCELL-ID PIC S9(9) COMP Memory cell to be queriedW-ELEMENT-COUNT PIC S9(9) COMP Buffer for memory count to be returned

Return Codes None


Example WORKING-STORAGE SECTION. ********************************************************************** * Parameters for call to LEMGSIZ ********************************************************************** * 01 WS140-GETSIZE-PARAMS. 03 WS140-RESERVED-AREA PIC X(128). 03 WS140-MEMCELL-ID PIC S9(9) COMP. 03 WS140-ELEMENT-COUNT PIC S9(9) COMP. * **********************************************************************

PROCEDURE DIVISION. ********************************************************************** * Processing call to LEMGSIZ * WS020-RESERVED-AREA is passed as a parameter in the linkage section * Print datastream has been stored in memory cell 9901. ********************************************************************** * MOVE WS020-RESERVED-AREA TO WS140-RESERVED-AREA. MOVE 9901 TO WS140-MEMCELL-ID. MOVE ZERO TO WS120-ELEMENT-COUNT. * CALL ‘LEMGSIZ’ USING WS140-RESERVED-AREA WS140-MEMCELL-ID WS140-ELEMENT-COUNT. * * Test for zero elements returned, ie. no data accessed * IF WS140-ELEMENT-COUNT = ZERO MOVE ‘Y’ TO WS190-ERROR-FLAG **********************************************************************

194 User Exits

LEMGELM — PCE only

Synopsis Reads a predefined element from a predefined array structure stored in a memory cell. See “Array Functions” on page 188 for definitions. LEMGELM copies the contents of an array element from a memory cell W-MEMCELL-ID into a buffer W-BUFFER. If the memory cell does not refer to a predefined array type or the requested element does not exist 0 bytes are returned.

Call CALL 'LEMGELM' USING W-RESERVED-AREA W-MEMCELL-ID W-ELEMENT W-BUFFER W-MAX-BUFF-SIZE W-BUFFER-LENGTH

Parameters W-RESERVED-AREA PIC X(128) API data (private)W-MEMCELL-ID PIC S9(9) COMP Memory cell to be readW-ELEMENT PIC S9(9) COMP Element number to be read (the first element is 0)W-BUFFER PIC X(n) Buffer to store array element where n is large enough

to store element contents W-MAX-BUFF-SIZE PIC S9(9) COMP Maximum size of W-BUFFER.W-BUFFER-LENGTH PIC S9(9) COMP Number of bytes in element to be returned

Return Codes None

Example WORKING-STORAGE SECTION. ********************************************************************** * Parameters for call to LEMGELM ********************************************************************** * 01 WS150-GETELM-PARAMS. 03 WS150-RESERVED-AREA PIC X(128). 03 WS150-MEMCELL-ID PIC S9(9) COMP. 03 WS150-ELEMENT-COUNT PIC S9(9) COMP. 03 WS150-BUFFER PIC X (2120). 03 WS150-MAX-BUFF-SIZE PIC S9(9) COMP VALUE 2120. 03 WS150-BUFFER-LENGTH PIC S9(9) COMP. * **********************************************************************PROCEDURE DIVISION. ********************************************************************** * Processing call to LEMGELM * WS020-RESERVED-AREA is passed as a parameter in the linkage section * Print datastream has been stored in memory cell 9901. * This call reads the first element (0) from the cell contents. ********************************************************************** * MOVE WS020-RESERVED-AREA TO WS150-RESERVED-AREA. MOVE 9901 TO WS150-MEMCELL-ID.


MOVE ZERO TO WS150-ELEMENT-NUMBER. MOVE SPACES TO WS150-BUFFER MOVE ZERO TO WS150-BUFFER-LENGTH. * CALL ‘LEMGELM’ USING WS150-RESERVED-AREA WS150-MEMCELL-ID WS150-ELEMENT-NUM WS150-BUFFER WS150-MAX-BUFF-SIZE WS150-BUFFER-LENGTH. * * Test for zero elements returned, ie. no data accessed * IF WS150-ELEMENT-COUNT = ZERO MOVE ‘Y’ TO WS190-ERROR-FLAG **********************************************************************

Cobol Definitions

Invocation mode

01 L-COMMAND-ID PIC X(4).

EMFE Data

01 L-RESERVED-AREA PIC X(128).

Return Status

01 L-MESSAGE-PARAMETERS.03 L-RETURN-STATUS PIC S9(9) COMP VALUE ZERO.03 L-MESSAGE-LENGTH PIC S9(9) COMP VALUE ZERO.03 L-MESSAGE-TEXT PIC X(128) VALUE SPACES.01 L-COMMAND-ID PIC X(4).

196 User Exits

User program examples

C Example#define UXIT_StatusOk 0#define UXIT_StatusPass 1#define UXIT_StatusWarning 2#define UXIT_StatusFatal 3//==========================================================================// Function: DoMyStuff// Synopsis: Example of user program functionality.// Description: This example converts the passed string to uppercase.// Entry: puchBuffer Pointer to buffer string.// cbBuffer Size of buffer.//==========================================================================static void DoMyStuff (unsigned char *puchBuffer, unsigned int cbBuffer){ int i; for (i = 0; i < cbBuffer; i++) // Convert the string to uppercase. puchBuffer[i] = toupper (puchBuffer[i]);}//==========================================================================// Function: InstructFunc// Synopsis: Example EMFE user program wrapper.// Descrip: Example of user program for EMFE. It determines the invocation// mode and takes the appropriate action.// Entry: pszMode Invocation mode.// ped Pointer to EMFE exit data.// pes Pointer to EMFE exit status data.//==========================================================================void _System InstructFunc (unsigned char *pszMode, PEMFEEXITDATA ped, PEMFEEXITSTATUS pes){ unsigned char szBuffer[1024]; unsigned int cbBuffer; if (strcmp (pszMode, "INIT") == 0) // Perform initialisation? { // Do any initialisation tasks needed.and set return code to ok. pes->ulReturnStatus = UXIT_StatusOk; } else if (strcmp (pszMode, "EXEC") == 0) // Perform user program task? { // Get the string in memory cell 9900,convert to uppercase,return in cell 9999 UxitGetString (ped, 9900, szBuffer, 0, sizeof (szBuffer), &cbBuffer); DoMyStuff (szBuffer, cbBuffer); UxitPutString (ped, 9999, szBuffer, cbBuffer); pes->ulReturnStatus = UXIT_StatusOk; } else if (strcmp (pszMode, "DIED") == 0) // Abnornal termination? { // Do the ‘died’ (abnormal termination) tasks and set return code to ok. pes->ulReturnStatus = UXIT_StatusOk; } else if (strcmp (pszMode, "TERM") == 0) // Normal termination? { // Do (normal) terminate tasks and set return code to ok.

User program examples 197

pes->ulReturnStatus = UXIT_StatusOk; } else // Invocation mode not recognized { // Set warning return status and create an error message for unknown function pes->ulReturnStatus = UXIT_StatusWarning; sprintf (szBuffer, "InstructFunc: Unsupported mode [%4.4s] ignored!\n", pszMode); strcpy (pes->szMessage, szBuffer); pes->cbMessage = strlen (szBuffer); pes->ulReturnStatus = UXIT_StatusWarning; }}

198 User Exits

Cobol Example IDENTIFICATION DIVISION. PROGRAM-ID. LEVEL2. AUTHOR. MKC. DATE-WRITTEN. 25/02/94. ENVIRONMENT DIVISION. CONFIGURATION SECTION. SOURCE-COMPUTER. IBM-PC. OBJECT-COMPUTER. IBM-PC. INPUT-OUTPUT SECTION. FILE-CONTROL. DATA DIVISION. FILE SECTION. WORKING-STORAGE SECTION. 01 LEMGSTR-PROG-ID PIC X(7) VALUE 'LEMGSTR'. 01 LEMPSTR-PROG-ID PIC X(7) VALUE 'LEMPSTR'. 01 W-COMMAND-ID PIC X(4). 01 W-RESERVED-AREA PIC X(32). 01 W-MESSAGE-PARAMETERS. 03 W-RETURN-STATUS PIC S9(9) COMP VALUE ZERO. 03 W-MESSAGE-LENGTH PIC S9(9) COMP VALUE ZERO. 03 W-MESSAGE-TEXT PIC X(128) VALUE SPACES. 01 W-MEMCELL-ID PIC S9(9) COMP VALUE ZERO. 01 W-TEXT-BUFFER PIC X(200) VALUE SPACES. 01 W-TEXT-LENGTH PIC S9(9) COMP VALUE ZERO. 01 W-MIN-BUFF-SIZE PIC S9(9) COMP VALUE +200. 01 W-MAX-BUFF-SIZE PIC S9(9) COMP VALUE +200.* LINKAGE SECTION.* L-COMMAND-ID will = INIT, EXEC, DIED or TERM 01 L-COMMAND-ID PIC X(4).* Do not alter the contents of the following area in any way! 01 L-RESERVED-AREA PIC X(32). 01 L-MESSAGE-PARAMETERS. 03 L-RETURN-STATUS PIC S9(9) COMP. 03 L-MESSAGE-LENGTH PIC S9(9) COMP. 03 L-MESSAGE-TEXT PIC X(128). PROCEDURE DIVISION USING L-COMMAND-ID L-RESERVED-AREA L-MESSAGE-PARAMETERS.* MAIN-PROCEDURE SECTION. MAIN-START. MOVE L-COMMAND-ID TO W-COMMAND-ID. MOVE L-RESERVED-AREA TO W-RESERVED-AREA. MOVE L-MESSAGE-PARAMETERS TO W-MESSAGE-PARAMETERS.TEST-FOR-INIT. IF W-COMMAND-ID = 'INIT' PERFORM INIT-PROCEDURE GO TO EXIT-PROCEDURE. TEST-FOR-EXEC. IF W-COMMAND-ID = 'EXEC'


PERFORM EXEC-PROCEDURE GO TO EXIT-PROCEDURE. TEST-FOR-DIED. IF W-COMMAND-ID = 'DIED' PERFORM DIED-PROCEDURE GO TO EXIT-PROCEDURE. TEST-FOR-TERM. IF W-COMMAND-ID = 'TERM' PERFORM TERM-PROCEDURE GO TO EXIT-PROCEDURE.* INVALID-COMMAND. PERFORM INVALID-COMMAND-PROCEDURE. EXIT-PROCEDURE. MOVE W-COMMAND-ID TO L-COMMAND-ID. MOVE W-MESSAGE-PARAMETERS TO L-MESSAGE-PARAMETERS.* MAIN-EXIT. EXIT PROGRAM.* INIT-PROCEDURE SECTION. INIT-START.* Do the initialisation processing here MOVE ZERO TO W-RETURN-STATUS. MOVE 'INIT process completed' TO W-MESSAGE-TEXT. MOVE +22 TO W-MESSAGE-LENGTH. INIT-EXIT. EXIT.* EXEC-PROCEDURE SECTION. EXEC-START.* Do the EXEC processing here MOVE 9900 TO W-MEMCELL-ID. MOVE 'Some text string .... ' TO W-TEXT-BUFFER. MOVE +22 TO W-TEXT-LENGTH. CALL 'LEMGSTR' USING W-RESERVED-AREA W-MEMCELL-ID W-TEXT-BUFFER W-MIN-BUFF-SIZE W-MAX-BUFF-SIZE W-TEXT-LENGTH.* Do your stuff here! MOVE 9999 TO W-MEMCELL-ID. MOVE +22 TO W-TEXT-LENGTH. CALL 'LEMPSTR' USING W-RESERVED-AREA W-MEMCELL-ID W-TEXT-BUFFER W-TEXT-LENGTH.* Check if all is OK here? MOVE +1 TO W-RETURN-STATUS. MOVE 'EXEC process completed' TO W-MESSAGE-TEXT. MOVE +22 TO W-MESSAGE-LENGTH. EXEC-EXIT.

200 User Exits

EXIT.* DIED-PROCEDURE SECTION. DIED-START.* Do the died processing here MOVE +2 TO W-RETURN-STATUS. MOVE 'DIED process completed' TO W-MESSAGE-TEXT. MOVE +22 TO W-MESSAGE-LENGTH. DIED-EXIT. EXIT.* TERM-PROCEDURE SECTION. TERM-START.* Do the termination processing here MOVE +3 TO W-RETURN-STATUS. MOVE 'TERM process completed' TO W-MESSAGE-TEXT. MOVE +22 TO W-MESSAGE-LENGTH. TERM-EXIT. EXIT.* INVALID-COMMAND-PROCEDURE SECTION. INVALID-START.* Do the invalid command processing here MOVE +4 TO W-RETURN-STATUS. STRING W-COMMAND-ID DELIMITED BY SIZE ' - ' DELIMITED BY SIZE 'command id not valid' DELIMITED BY SIZE INTO W-MESSAGE-TEXT. MOVE +27 TO W-MESSAGE-LENGTH. INVALID-EXIT. EXIT.**


202 User Exits

Index
Symbols
%@ in PCE composition edit commands 68.BMP 134.EAR 103.EDF 103.EOL 103.LAR 103.LDF 103.LIM 89

A

Account group 80add DJDE, PCE command 27add document id, PCE command 27add document name, PCE command 28add document TLE, PCE command 28add medium map, PCE command 29add TLE, PCE command 29Address block 161Address2 Information 166AFP Index 21AFPDS

Attribute Name triplet 28Attribute Qualifier triplet 28Attribute Value structured field 28Begin Named Page Group structured field 59End Named Page Group structured field 59Manipulating with PCE 13Named group structured field 21Opening with PCE 53PCE operand 55TLE structured field 30, 42, 62

AIX 186and not, PCE operator 39and, PCE operator 39ApiData Data structure 184Application Layer Editor. See ALEApplication Rules 103Arrays of PCE variables 15, 34atrim, PCE parameter 47Attribute Name, TLE attribute 28, 30, 42, 62Attribute Value, TLE attribute 28, 30, 42, 62

B

Barcodes 19BCOCA 49begin CE, PCE command 30begin loop, PCE command 31Begin Named Page Group structured field 59begin procedure, PCE command 31BEGIN, RTF2LDO keyword 89Bitmap used with Characters dialog 134Block headers In PCE 16Boolean evaluation in PCE 14, 39

C

call procedure, PCE command 32Call Type, User Exit Control file 178

Cell parameter 176CevAddFirmDataLibrary

Reference 110CevAddFirmDataLibrary API function

Usage 106CEVAPI.H 104CevConvertRules API function

Reference 111Usage 107

CevCreateObject API functionReference 111Usage 106

CevCreateWindow API functionReference 112Usage 108

CevDestroyObject API functionReference 112Usage 106

CevDoubleToLu API functionReference 113Usage 108

CEVENVINFO structure 130CevExecuteRules API function


CEVGRIDINFO structure 130CevInitApi API function


CevLuToDouble API functionReference 115Usage 108

CevProof API functionReference 115Usage 108

CevQueryActivePage API functionReference 116Usage 107

CevQueryDataDocCount API functionReference 116Usage 107

CevQueryDataDocKey API functionReference 117Usage 107

CevQueryDataDocKeyId API functionReference 117Usage 107

CevQueryDataDocLabel API functionReference 117Usage 107

CevQueryDocCount API functionReference 118Usage 107

CevQueryGridInfo API functionReference 118Usage 108

CevQueryPagesInDoc API functionReference 119Usage 107

CevQueryResolution API functionReference 119Usage 108

CevQueryRulerInfo API functionReference 119

203

Usage 108CevQueryScrollInfo API function


CEVRULERINFO structure 131CEVSCROLLINFO structure 132CevSetActivePage API function


CevSetBackColor API functionReference 121Usage 108

CevSetEnvironment API functionReference 121Usage 106

CevSetGridInfo API functionReference 121Usage 108

CevSetResolution API functionReference 122Usage 108

CevSetRulerInfo API functionReference 122Usage 108

CevSetScrollInfo API functionReference 122Usage 108

CevStartTrace API functionReference 123Usage 109

CevStopTrace API functionReference 123Usage 109

CevTerminateApi API functionReference 123Usage 109

CEVUOM enumerated type 129CevUseEngineRuleFiles API function


CevUseLogicalRuleFiles API functionReference 124Usage 106

CevUseObject API functionReference 125Usage 108

change DIJelement, PCE command 32CHAR(S) keywords in Character Layout file 134Character Layout file 133Characters dialog 11, 133Chart data object 81Charts, with DHTML 81close, PCE command 33CLSE user exit invocation mode 183Cobol Functions with user exits 192, 196, 199Coding a Character Layout File 133COL, CE command 69Color, setting in PCE 69Comments in PCE Control file 25CompactSpaces

Reformat Initialization file keyword 155Composition edit 66Conditions in PCE routines 14Consolidation level in LFL2FDO 95contains, PCE parameter 39Control file

Comments 25Concepts 14Filenames 24

Literals 23Procedure 14Sample 77Variables 14, 23

Declaring 34Control Files for Preview API 106Control script for RTF2FDO 87Convert images to bitmaps 96Copies, Initialization file keyword 170CorpId, Initialization file keyword 170Current print position 66CustomerName

Reformat Initialization file keyword 154Cycle, Initialization file keyword 170

D

Data Format Editor 105Data format file 103Data structures within a user program

'C' definition 191Data Type Definition 152Data types in PCE 26DATA_INPUT user exit 173DataFormat

Reformat Initialization file keyword 154Dataset names in PCE Control file 24date environment value 43DBCS 19DBCS-HEX, PCE operand 48DBX, CE command 69DD label in PCE Control file 24declare procedure, PCE command 33declare, PCE command 34Define Image List 70Define Overlay List 70DefinitionName

Reformat Initialization file keyword 155Delimited file types 16Delimited, PCE operand 55DFE 105DHR, CE command 70DIED user exit invocation mode 182Digital UNIX 186DIJ 18

opening in PCE 55DIJelement 32, 40DIL, CE command 70DJDE, adding to print datastream 19DLL file

For Preview API 104DLM 94DOC1 for Workgroups. See WorkgroupsDOC1 Interchange Journal. See DIJDOC1 PCE. See PCEDOC1 Port Monitor 142DOC1 Production Bridge 138DOC1 Upload Service 139DOC1GFC 97DOC1GLC 99DOC1RFC. See RFCDOC1RFL. See RFLDOC1RFMT 152DOC1RFP. See RFPdocoffset environment value 43document attributes object 80Document layouts 162Document Library Editor 94

204 Index - D

Document Object Editor. See DOEDocument object library 103

Extracting objects 94, 95Document objects

Creating from Firm Data Libraries 94Document Repository 18DocumentDate

Reformat Initialization file keyword 155Documents, grouping in PCE 20DOE

Creating customized pages for Characters dialog 11, 133DOS

Filename convention 12, 24PCE read offsets 58Running DOC1RFMT 156

DPOL, CE command 70Draw Box 69Draw Horizontal Rule 70Draw Vertical Rule 71DTD 152DVR, CE command 71dXML 152

E

EDINAT 138else, PCE command 37EMFE Identifier for user functions 176EmfeInputData data structure 185end ce, PCE command 34end if, PCE command 37end loop, PCE command 35End Named Page Group structured field 59end procedure, PCE command 35Engine rules 103Environment values in PCE applications 42eq, PCE operator 39Errors during PCE applications 51Exception dictionary file 47Execution invocation mode 182exit loop, PCE command 35Exit type, User Exit Control file 178

F

False comparison using PCE 39File Header, OTS 165Files

Naming conventions 12PCE concepts 15Pointers and offsets 17

Firm DataBLOB support 138

Firm Data Objects 138Font

Mapping names from RTF style 85Reversed text 74

Font Equivalents File 92Font Metrics 67Font Reference by Index

in CE commands 67Font references - changing 97for...next, PCE command 36FORCE LINE BREAK 134format, PCE sub-command 54FormatType

Reformat Initialization file keyword 154Function, User Exit Control file 179

G

ge, PCE operator 39Group level TLE’s 21Grouping documents in PCE 20gt, PCE operator 39

H

Header data in print datastreams 16Header file

For Preview API 104Host Resource Files 103HPUX 186HTML 79

I

Identifier, User Exit Control file 178if, PCE command 37Image Metrics 67Image resources

Converting images to bitmaps 96Image used with Characters dialog 134IMAGE, RTF2LDO keyword 89in range, PCE operand 39Indexing for AFP 21INI. See Initialization fileINIT invocation mode 184INIT user exit invocation mode 182Initialization File

For Reformat 153Initialization invocation mode 182Input

Reformat Initialization file keyword 154insert object, PCE command 37INSTRUCTION

User exit 173User Exit Control file 178

Invocation modesData structure 184of user exits 182

InvocationMode structure 175, 184is Main, PCE parameter 33

J

Java applet for DHTML deployment 81JDataMode 81JDataURL 81Journal Files, In PCE 17JPThreshold 81JUST, RTF2LDO keyword 89

K

Key Field 105Key ID 105Keycode

Reformat Initialization file keyword 154KeyField

Reformat Initialization file keyword 154ksdsafp, PCE parameter 54ksdsmeta, PCE parameter 54

Index - K 205

L

Labels of Document Layouts 105LADCEV.DLL 104LADCEV.LIB 104le, PCE operator 39LEMGSIZ 193, 195LEMGSTR 192LEMPSTR 193Length of strings with PCE 44let (boolean), PCE command 39let (copy), PCE command 49let (number functions), PCE command 44let (string manipulation), PCE command 45let … (environment values), PCE command 42let … call userexit, PCE command 40let … DIJelement, PCE command 40let … document id, PCE command 41let … document name, PCE command 41let … document TLE, PCE command 42let … page count, PCE command 44let...TLE..., PCE command 48Level, TLE attribute 28, 30, 42, 62Library file

For Preview API 104line, PCE operand 53LINESP, RTF2LDO keyword 88LINESPV, RTF2LDO keyword 88Linking with Data Exchange API 186Literals in PCE routines 23Log file

With PCE Control file 20Logical page 66Logical rules 103LOL2LDO 94LOOKUPKEY, RTF2FDO keyword 89Looping in PCE routines 14lt, PCE operator 39ltrim, PCE parameter 46LUNIT type 129

M

Main procedure in PCE Control file 33MAKEBMP utility 96MAKEEDF utility 159mapp, PCE parameter 46MEASURE, RTF2LDO keyword 88Medium map, adding reference to AFPDS 19Memory cells 180

For Return Data 183Memory requirements of PCE 15Merge Application Rules Utility 101merge, PCE command 49MERGELAR 101Messages

Reformat Initialization file keyword 154Metacode

Identifying in PCE Control file 55Manipulating with PCE 13

mixc, PCE parameter 47Module, User Exit Control file 178move page, PCE command 51move, PCE command 50

N

Name parameterUser Function object 176

ne, PCE operator 39next, PCE command 36NoPrintFlag, Initialization file keyword 170not, PCE operator 39Notification Codes from Preview API 127NT. See WindowsNumeric computations in PCE 44

O

Object header 175Objects for Preview API 106Offsets for IO operations in PCE 17On error call, PCE command 51OPEN user exit invocation mode 182open, PCE command 53OpenVMS

Filename convention 12, 25Running DOC1RFMT 156

or not, PCE operator 39or, PCE operator 39OS/2

Filename convention 12Location of user exit programs 187Running DOC1RFMT 156

OS/390Filename convention 12, 24Linking with user programs 186Location of user exit programs 187Opening files with PCE 53PCE read offsets 57, 59Running DOC1RFMT 158Running READYEDI 147

OS/400Filename convention 12, 24Linking with user programs 187Location of user exit programs 187Opening files with PCE 54PCE read offsets 57, 59Running DOC1RFMT 157

OTSCASS, Initialization file keyword 170overwrite, PCE command 56

P

Page level TLE’s 21pageoffset environment value 42Pages with PCE 15

Changing 19Counting number in document 44Moving into a document 51

PAK file 79Panels for DOC1RFMT under OS/400 157Parameters

User Function object 176PCE

Adding AFP index fields 29, 61Adding AFP medium maps 29Adding DJDEs to Metacode datastream 27Adding document names 27, 28Adding print elements to existing pages 30Boolean evaluation 39Calling error routine 51

206 Index - L

Calling user exits 37, 40Closing files 33Concepts 14Conditional statements in Control file 37Copying variables 49Counting pages in document groups 44Declaring variables in Control file 34Document groups 20for...next loops in Control file 36Getting environment information 42Memory requirements 15Merging pages 49Moving pages into a document group 51Moving printable elements 50Numeric computation 44Opening Files 53Overwriting strings 56Quitting a process 57Reading AFP indexes 48Reading from files 57Replacing a string 60Returning from procedures 60Set page name for postscript 61String functions 45Text manipulation 45Translating text strings 63Writing to files 63Writing trace information 63

Physical page 66PI, CE command 72Place Image 72Place Page Overlay 72plain, PCE parameter 55Pointers in files used by PCE 17Port Monitor 142

Windows 2000 & XP 144Windows NT 143

Postal Information 167PostScript

Font names 67PCE operand 55

PPO, CE command 72Preview API 103Preview object 103Preview Window 108Print datastream

Formatting with PCE 16Header data 16

Print Positioning for composition edit 66Printer controls, adding with PCE 19Printer resource references in PCE 67PrintOutput, Initialization file keyword 170PRINTSTREAM

User exit 173User Exit Control file 178

Procedures in PCE Control file 14Production Bridge 138

doc1holding.inf 142Proof printing 108

Q

quit, PCE command 57

R

read … DIJentry, PCE command 59read … document, PCE command 59

READ user exit invocation mode 183read, PCE command 57READYEDI

Running on OS/390 147Running on OS/400 149Running on UNIX and OpenVMS 150Running on Windows, OS/2 and DOS 151

Record headers with PCE 16record, PCE parameter 53Reformat utility 152ReformatOutput

Reformat Initialization file keyword 154replace, PCE command 60ResourcePath 81ResourceSet, Initialization file keyword 170Return codes

From Preview API 126Return Data from user exits 183return, PCE command 60ReturnStatus data structure 185Reversed text fonts 74Right brace 154Right square bracket 154RRDS VSAM format 13RTF 85RTF2LDO 85rtrim, PCE parameter 47Rules files for Preview API 103RunDate, Initialization file keyword 170

S

Sample filefor Preview API 104

SAMPLE.C 104SBT, CE command 73SBTR, CE command 73Schema 152

Reformat Initialization file keyword 154SCPP, CE command 74SEARCHPATH, RTF2FDO keyword 87SEEK user exit invocation mode 183Sequence Number

TLE attribute 28, 30, 42, 62Set Boxed Text 73Set Boxed Text Right Justified 73Set Current Print Position 74set page name, PCE command 61Set Physical Page Size 75Set Text Line 75Set Text Presentation 76ShowEmptyRecords

Reformat Initialization file keyword 154ShowKeyDefField

Reformat Initialization file keyword 154SIZE, RTF2LDO keyword 88SPPS, CE command 75Statement Trailer 168, 170STL, CE command 75STP, CE command 76String functions in PCE 45String, PCE operand 47substring, PCE parameter 47Summary Pages 161Sun 186Symbol PCE operand 48Symbols

From Initialization file 48

Index - S 207

Reformat Initialization file keyword 155Sys_last_error 51

T

TELL user exit invocation mode 182TERM user exit invocation mode 182Text

Manipulating in PCE 45Translating 63

time environment value 43TITLE keyword in Character Layout file 134TITLE TEXT keyword in Character Layout file 134TLE, AFPDS structured field 21, 30, 42, 62

Identifying with PCE 48TLE, PCE command 61Trace file

With PCE Control file 20trace, PCE command 63translate, PCE command 63Translation Tables

With PCE Control file 63TransmissionNumber, Initialization file keyword 170True comparison using PCE 39TXTBLK, RTF2LDO keyword 89

U

Unit of measure 66UNITS, RTF2LDO keyword 88UNIX

Filename convention 12, 25Opening files with PCE 53PCE read offsets 58Running DOC1RFMT 156

Upload Service 139User 171User defined pages 133User Exits 171, 175

Control file 176Control File reference 178Data Exchange API 188In PCE 22Set-up 171

User Function object 176User Value object 176UxitGetArrayElement 190UxitGetArraySize 190UxitGetString 189UxitPutString 189

V

value, PCE parameter 44Variables

in PCE 26in PCE Control file 14

Arrays 15, 34Copying 15

VERSION keyword in Character Layout file 134VPS

PCE operand 55VSAM

As print datastream file 13Opening with PCE 53Using offsets with document groups 59

vsamafp, PCE parameter 53vsammeta, PCE parameter 53

W

WindowsFilename convention 12, 24Linking with user programs 186Location of user exit programs 187Opening files with PCE 53PCE read offsets 59Running DOC1RFMT 156

Workstation Resource Files 103Workstation resources 97write DIJentry, PCE command 64write document, PCE command 65write, PCE command 63wsafp, PCE parameter 54wsmeta, PCE parameter 54

X

XML 79Produced by Reformat 152

Z

Zip Code 167

208 Index - T