Doc1 v4 5 0 Programmers Guide 7d

®
DOC1 Suite 4
Programmer’s
Guide
Issue 7d
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, Netherlands
Copyright © 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 derivations

Copyright 1981 - 1983, 1989, 1993 Heidelberger Druckmaschinen AG.
All rights reserved.
Maxicode encoding, Datamatrix and PDF417 encoding, fonts and derivations
Copyright (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.
2
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 .......................................................................................................................17
DIJ 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 ..................................................................................... 23

General ........................................................................................................................23
Variables and Arrays ....................................................................................................23
Literals ........................................................................................................................23
File Names ..................................................................................................................24
Comments ...................................................................................................................25
Conventions .......................................................................................................................26
add DJDE ....................................................................................................................27
add document id ..........................................................................................................27
add document name .....................................................................................................28
add document TLE ......................................................................................................28
add medium map .........................................................................................................29
Contents 3
add TLE ......................................................................................................................29
begin ce ........................................................................................................................30
begin loop ....................................................................................................................31
begin procedure ............................................................................................................31
call procedure ...............................................................................................................32
change DIJelement .......................................................................................................32
close ............................................................................................................................33
declare procedure .........................................................................................................33
declare (variable) ..........................................................................................................34
end ce ..........................................................................................................................34
end loop .......................................................................................................................35
end procedure ..............................................................................................................35
exit loop .......................................................................................................................35
extract document page ..................................................................................................36
for…next ......................................................................................................................36
if…else…end if .............................................................................................................37
insert object ..................................................................................................................37
let … barcode ...............................................................................................................38
let (boolean evaluation) ................................................................................................39
let … call userexit .........................................................................................................40
let … DIJelement .........................................................................................................40
let … document id ........................................................................................................41
let … document name ...................................................................................................41
let … document TLE ....................................................................................................42
let (environment values) ................................................................................................42
let (number functions) ...................................................................................................44
let … page count ..........................................................................................................44
let (text functions) .........................................................................................................45
let … TLE … ...............................................................................................................48
let (variable copy) .........................................................................................................49
merge ...........................................................................................................................49
move ............................................................................................................................50
move page ....................................................................................................................51
on error call ..................................................................................................................51
open .............................................................................................................................53
overwrite ......................................................................................................................56
quit ..............................................................................................................................57
read .............................................................................................................................57
read … DIJentry ...........................................................................................................59
read … document .........................................................................................................59
4 Contents
replace .........................................................................................................................60
return ...........................................................................................................................60
set page name ...............................................................................................................61
TLE .............................................................................................................................61
trace .............................................................................................................................63
translate .......................................................................................................................63
write ............................................................................................................................63
write DIJentry ..............................................................................................................64
write document ............................................................................................................65
Composition Edit Commands ................................................................................ 66
Print Positioning Concepts ..................................................................................................66
Printer Resource References ................................................................................................67
Fonts referenced by index .............................................................................................67
Order of Commands ...........................................................................................................68
Command Structure ...........................................................................................................68
COLR – Set Color ........................................................................................................69
DBX – Draw Box .........................................................................................................69
DIL – Define Image List ...............................................................................................70
DHR – Draw Horizontal Rule ......................................................................................70
DPOL – Define Overlay List ........................................................................................70
DVR – Draw Vertical Rule ...........................................................................................71
PBIM – Place Barcode – Intelligent Mail .......................................................................71
PI – Place Image ..........................................................................................................72
PPO – Place Page Overlay ............................................................................................72
SBT – Set Boxed Text ...................................................................................................73
SBTR – Set Boxed Text Right Justified .........................................................................73
SCPP – Set Current Print Position ................................................................................74
SPPS – Set Physical Page Size ......................................................................................75
STL – Set Text Line .....................................................................................................75
STP – Set Text Presentation ..........................................................................................76
Control File Sample ............................................................................................ 77
HTML DEPLOYMENT ...............................................................................................79

Groups and Identifiers ........................................................................................................80
Graphics handling ..............................................................................................................81
Lines and boxes ............................................................................................................81
Static images ................................................................................................................81
DOC1 chart feature ......................................................................................................81
DOC1 HTML PAK file format ...........................................................................................83
Contents 5
WORKSTATION UTILITIES ........................................................................................ 85
RTF2LDO – import RTF ...................................................................................... 85
Restrictions ..................................................................................................................86
RTF2LDO control script format ..........................................................................................87
RTF2LDO Font Equivalents file format ..............................................................................92
RTF2LDO under Windows and Unix .................................................................................93
LOL2LDO – deconstructs document object library ...................................................... 94

Output 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 ....................................................................................................................103
Required Software Products ........................................................................................104
DOC1 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 ............................................................................................... 139
Installing ....................................................................................................................139
Running the Service ................................................................................................... 142
The DOC1 Port Monitor .................................................................................................. 142
Port Monitor installation for Windows NT ................................................................. 143
Port 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 .........................................................................160

Available Finishing Lines ........................................................................................... 160
Summary Pages .......................................................................................................... 161
Address Block ............................................................................................................ 161
OTS CASSing ............................................................................................................ 161
Document Layouts ..................................................................................................... 162
Finishing line information fields ................................................................................. 162
Parallel Support .......................................................................................................... 163
FormDefs .................................................................................................................. 163
Contents 7
OTS Records ....................................................................................................................164
File Header ................................................................................................................165
Address2 Information .................................................................................................166
Postal Information NOP/PTX ....................................................................................167
Zip Code NOP/PTX ..................................................................................................167
Statement 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 ................................................................................................................173
AFPDS ......................................................................................................................174
PostScript and PDF ....................................................................................................174
Metacode ...................................................................................................................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 .........................................................................................................186
Windows & OS/2 ......................................................................................................186
UNIX ........................................................................................................................186
8 Contents
OS/390 ...................................................................................................................... 186
OS/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 conventions
The 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 conventions
The following conventions are expected whenever you need to specify file
names in the DOC1 environment.
OS/390
All files are referenced by Data Definition (DD) labels with actual datasets
being assigned to these labels in start-up JCL. Example:
Rules=DD:EMFERULE
OS/400
Files are referenced by the libname/filename(member) convention. The
Library specification can be omitted if it is in the *LIBL list. Example:
Rules=DOC1HOST/EMFERULE(APPLIC1)
Windows, OS/2 or DOS

Files 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:
Rules=C:\DOC1HOST\EMFERULE\APPLIC1.EAR
UNIX
specified EMFE will search the current directory (from which EMFE was
started) for the filename. Example:
Rules=/doc1host/emferule/applic1.ear
OpenVMS
specified EMFE will search the current path (from which EMFE was started)
for the filename. Example:
Rules=[doc1host.emferule]applic1.ear
Updates to this manual

This 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.
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 Overview
For 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 control

To 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 Arrays

As 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 Handling
Files 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 Writing

As 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 Files
When 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 Manipulation
The 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 Pages

Although 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

Information
Syntax 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 Groups
If 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 Indexing

Several 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 Exits
User 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 memory

declare <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 memory

declare <PageOfPrintData>[5];

Conventions
Variables <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.
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 group
let <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 it
add 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 Box
DIL – Define Image List
DHR – Draw Horizontal Rule
DPOL – Define Overlay List
DVR – Draw Vertical Rule
PI – Place Image
PPO – Place Page Overlay
SBT – Set Boxed Text
SBTR – Set Boxed Text Right Justified
SCPP – Set Current Print Position
STL – Set Text Line
STP – 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 journal
open "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 group
let <pagecount> = 6;
read <pagecount> document from file 1 into <document2>;
...
// Get the page from the document group
extract 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 file
move 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 file
for 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 count
let <Page1> = <Count> lt 1;
// Over write text as appropriate
if <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 data
read 1 page from file 0 into <AFPDSPage>;
// Read barcode info from journal
read 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 journal
read 5 items from file 1 into <Input>;
// Check page number is less than 100
let <PageNumber> = <Input>(0);

let <Check1> = <PageNumber> lt 100;
// If OK check for batch type
if <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.
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/plain
open <AFPInFile> for input as file 1 wsafp/afpds;
open <AFPOutFile> for output as file 2 wsafp/afpds;
// Read and write first page of AFP
read <ReadNumber> page from file 1 into <AFPData>;
write 1 page into file 2 from <AFPData>;
//Get and write document offset to output
let <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> |
} ;
num1
the 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>.
achieve the desired calculation.
Example ...
// Read page number from journal and convert to number
read 1 items from file 1 into <Input>;
let <PageCount> = value <Input>;
// Compute number of pages
let <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 entries
day Wednesday
month June
period quarterly
1. <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@@";
3. <var3> will be given "Accounting period is quarterly"
let <var1> = "period"
let <var2> = "Accounting period is @@I<var1>@@";
4. Assuming the initialization file contains
UserValue3 = 2
<var2> will be given "The month is June":
let <var1> = "The month is @@M3@@";
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.
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: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: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.

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
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;
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:
line
Indicates 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)

wsafp
Indicates 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))
wsmeta
Indicates 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:
plain
The 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.
afpds
The file contains AFP datastream file. Each read/write operation will get/put the data structures that
make up a single composed AFPDS page.
metacode
The file contains Metacode datastream file. Each read/write operation will get/put the data
structures that make up a single composed Metacode page.
postscript
The file contains PostScript datastream file. Each read/write operation will get/put the data
structures that make up a single composed PostScript page.
VPS
The file contains VPS datastream file. Each read/write operation will get/put the data structures that
make up a single composed VPS page.
DIJ
The 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 variable
let 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 program
if <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 journal
read <ReadNumber> items from file 0 into <JournalData>;
// Check that a full read took place...
let <BadRead> = <ReadNumber> lt 2;
// ... if not abort program
if <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 offset
if <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 group
read 5 document from file 1 into <AFPPages>;
//Add a new document level TLE before these pages
TLE 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 TLEs
TLE 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 message
if <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 pages
if <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 Commands
This 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 Concepts

All 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 References
Up 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 Commands
Composition 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 Structure
All 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:

1 = Black
2 = Blue
3 = Brown
4 = Green
5 = Pink
6 = Red
7 = Cyan
8 = Yellow
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:
0-19% None
20-39% Light
40-59% Medium
60-79% Heavy
80-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 Sample
This 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 done
declare <Counter>; // pages per statement
declare <Input>(5); // journal data is read into this 5 cell array
declare <CustID>; // processed journal data
declare <PageCnt>;
declare <SFPage>;
declare <CCPage>;
declare <OCPage>;
declare <APage>; // input data is stored here
declare <BarCode>; // holds barcode string
declare procedure <Main> is main;
begin procedure <Main>;

// open the Metacode datastream
open "APPLIC1.MTC" for input as file 0 wsmeta/metacode;
// open the journal file associated with this datastream
open "APPLIC1.JRL" for input as file 1 line/delimited(32);
// open an output file
open "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;
// read a page of the statement

read 1 page from file 0 into <APage>;
// quit if nothing to process

let <Done> = <N> EQ 0;
// 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
h 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.
79
DHTML extraction and deployment model
For each HTML page created the

HTML deployment system will need to
(XML PAK) extract three different object types
from the PAK file as indicated in the
diagram.
DOC1 The HTML pages themselves can be

journal
extracted to the location required by
XML parser
your presentation system. The two
types of dynamically generated
resources also created within the
PAK must be extracted to the
Line & box DOC1 locations indicated by the relevant
HTML Chart data Static
Pages index vector Graphics EMFE INI keywords.
pages objects images
graphics Applet
File store or database File store only Static images and the DOC1
Pages reference CD objects using Pages reference these files using the Graphics Applet used to present
the location/method specified in ResourceURL EMFE INI keyword charts are assumed by the HTML to
JDataURL EMFE INI keyword be already present at the location
Web server repository indicated by the ResourceURL
keyword in the HTML section of the
EMFE INI.
The extraction routine will also need

Presentation to build an index to the HTML files so
system 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
Web to supply additional references.
browser
Groups and Identifiers

HTML 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.
80 HTML Deployment
Graphics handling
Unlike 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 path
Query – 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
Examples of how chart objects are referenced
Mode URI Description
JDataMode = URL and...
DataURL = http://doc1/resources/&jdUID.dat use fully qualified path and jdUID as file

Example resolution: http://doc1/resources/JD09AFG1.dat name.
DataURL = &jdUID.dat use current path/default location
DataURL = http://doc1/&docUID/&pageUID/&jdUID.dat use several unique IDs to provide full path

Example resolution: http://doc1/d781122/p87487287/JD09AFG1.dat
JDataMode = Query and...
JDataURL = http://doc1/scripts/getcd.cgi?&jdUID call to cgi script in the defined location using

Example resolution: the jdUID attribute as the sole parameter.
http://doc1/scripts/getcd.cgi?getcd.asp?/jdUID=JD09AFG1
DataURL = getcd.asp?/&pakUID&docUID&jdUID call to asp script in the current path/default

Example resolution: location using several unique IDs as
getcd.asp?/pakUID=p87487287&docUID=d781122&jdUID=JD09AFG1 parameters.
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 generated
date – System date
time – System time
platform – 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 image
url – 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 object
datalen – 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 name
pageid – which page within doc
lref – position on the page
cpage, fpage, docmap Future expansion only. No relevant content at this time.
84 HTML Deployment
W o rk sta tio n U tilitie s
A number of command line utility programs are provided to supplement the

features of the DOC1 design modules.
RTF2LDO – import RTF

RTF2LDO 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:
Effects of downgrading when using RTF2LDO
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.
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 follow
SEARCHPATH=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 follows
BEGIN;
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:
INCH
MM - millimeters
CM - 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:
INCH
MM - millimeters
CM - centimeters
LPI - lines per inch
POINTS - 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;
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;
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;
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 file
2 - continue if error encountered and delete document object file
3 - 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.LDO
where 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.LDO
where 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 file
2 - each member is written to a separate document object file
3 -all members from a particular section are written to the same document
object file
See 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.LOL
will produce a single output file named ALL.LDO
LOL2LDO -a -s -c2 LOLLIST.LIS

will produce multiple output files such as LOLL0001, LOLL0002, LOLL0101, etc.
LOL2LDO -c3 C:\DOC1\ALLDOJS.LOL

will 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.bmp
MAKEBMP image.pcx image.cmp
c:\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 FONT02
DOC1GFC -rS APPLIC1.LAR X0FONT01 C0FONT02:T1FONT01 English
DOC1GFC -rF C:\DOC1\RESOURCE\APPLIC1.LAR X0FONT01 FONT01P
Other Utilities 97
Font References in DOC1 Workstation Resource Files
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.
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 on
NO – 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:
Brazilian, Portuguese 27
Catalan 18
Danish 20
Dutch 1996-GB 3
Dutch 1996-VD 4
Dutch-VL 5
Finnish 25
French, New (etymological hyphenation) 6
French, New (phonetic hyphenation) 8
French, Old (etymological hyphenation) 7
French, Old (phonetic hyphenation) 9
German, New 10
German, New (old hyphenation) 12
German, Old 11
Icelandic 26
Italian 16
Norwegian 21
Norwegian (morphological hyphenation) 22
Portuguese 19
Spanish 17
Swedish (-CK hyphenation) 24
Swedish (C-K hyphenation) 23
Swiss German, New (old hyphenation) 14
Swiss German, Old (new hyphenation) 15
Swiss German, Old (old hyphenation) 13
UK English 1
US English 2
"No proofing" 0
Examples:
Set ‘UK English’ and ‘no hyphenation’ to the entire document object library
DOC1GLC -L oldfile.lol -C 1
Set ‘US English’ and ‘hyphenation on’ to the section ‘Second Section’ and ‘no proofing’ plus ‘no hyphenation’ to all
other sections
DOC1GLC -L oldfile.lol -C 2 -HY YES -S Second_Section
Lists all the attributes of the document object library
DOC1GLC -L c:\appl\cust\newfile.lol
Changes ‘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

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.
Environment
The 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 Preview

A 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
Initialization
A 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 Objects

Each 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 Files

Once 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 Output

Having 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 Pages

A 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 Window
The 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 Pages
To 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 Printing
The 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

Debugging
Use 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 Services
A 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 Codes

Error handling is assisted by published codes being returned from all
functions.
General Principles and Function Overview 109

Function Reference
The 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_NOERROR

CEVRET_NOT_INITIALIZED
CEVRET_INVALID_HANDLE
CEVRET_INVALID_PARAMETER
CEVRET_ERROR
CEVRET_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

CEVRET_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

CEVRET_MEM_ERROR
CEVRET_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’.

CEVRET_WIN_ERROR
CEVRET_ERROR
CEVRET_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.

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_UnitInch
CEVDEF_UnitCm
CEVDEF_UnitMm
CEVDEF_UnitPica
CEVDEF_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.

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.

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

CEVRET_ALREADY_INITIALIZED
CEVRET_MEM_ERROR
CEVRET_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_UnitInch
CEVDEF_UnitCm
CEVDEF_UnitMm
CEVDEF_UnitPica
CEVDEF_UnitPoint
pdValue Pointer to double to receive the converted value. Set to zero if there is an
error.

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.

CEVRET_ERROR
CEVRET_INVALID_PROOF_SPEC
CEVRET_NOPRINTERS
CEVRET_INVALID_PRINTER
CEVRET_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_INITIALIZED

CEVRET_ERROR
CEVRET_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

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

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

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

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

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

CEVRET_INVALID_WINDOW
CEVRET_ERROR
CEVRET_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.

CEVRET_ERROR
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 resolution
CEV_Resolution240 - 240 dpi
CEV_Resolution300 - 300 dpi
CEV_ResolutionFit - the resolution will be generated so that the image fits
the window.

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

CEVRET_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

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

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

CEVRET_ERROR
CevSetEnvironment
Synopsis Sets environment settings.
Prototype CEVRET_System CevSetEnvironment (PCEVENVINFO penvinfo)
Parameters penvinfo Pointer to environment information 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.

CEVRET_ERROR

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

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

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

CEVRET_ERROR
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

CEVRET_FILE_OPEN
CEVRET_FILE_WRITE
CevStopTrace
Synopsis Stops a trace previously started by CevStartTrace.
Prototype CEVRET_System CevStopTrace (VOID)

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

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

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

CEVRET_ERROR

Return Codes
Each 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 Codes
The 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_FINISHED
CevConvertRules has terminated
param1
USHORT Control ID
USHORT Notification code
param2 Object handle
LONG
CEVNOTIFY_CONVERT_FAILED
CevConvertRules has failed
param1
USHORT Control ID
param2
LONG Object handle
CEVNOTIFY_CONVERT_COMPLETE
CevConvertRules has completed at step ‘Conversion step’ out of ‘Maximum
steps’
param1
USHORT Control ID
param2
USHORT Conversion step
USHORT Maximum steps
CEVNOTIFY_EXECUTE_FINISHED
CevExecuteRules has terminated
param1
USHORT Control ID
param2
LONG Object handle
CEVNOTIFY_EXECUTE_FAILED
CevExecuteRules has failed
param1
USHORT Control ID
param2 LONG Object handle
Notification Codes 127

CEVNOTIFY_EXECUTE_COMPLETE
CevExecuteRules has completed after processing ‘Document number’ out of
‘Total document count’
param1
USHORT Control ID
param2
USHORT Document number
USHORT Total document count
128 Preview API

Types and Data Structures
The 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_UnitInch
CEV_UnitCm
CEV_UnitMm
CEV_UnitPica
CEV_UnitPoint
CEV_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_WorkPath
CEVENV_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;

CEVGRID_StepX
CEVGRID_StepY
CEVGRID_Show
CEVGRID_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;

CEVRULER_UOM
CEVRULER_Divisions
CEVRULER_ShowRuler
CEVRULER_ShowIndicator
CEVRULER_CrossHairs
CEVRULER_Thickness
CEVRULER_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.

CEVSCROLL_HShow
CEVSCROLL_VShow
CEVSCROLL_HPosition
CEVSCROLL_VPosition
CEVSCROLL_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_LINELEFT
SB_LINERIGHT
SB_PAGELEFT
SB_PAGERIGHT
SB_SLIDERPOS
sVCommand Vertical scroll reposition. Assign one of the following constants representing
standard WM_VSCROLL parameters:
SB_LINEUP
SB_LINEDOWN
SB_PAGEUP
SB_PAGEDOWN
SB_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 1
TITLE BITMAP FileName
TITLE 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 fonts
TITLE BITMAP D:\DOC1\PAGEFILE\PAGE1.BMP
TITLE TEXT "Useful chars"
CHARS 0x00a0-0x00a9
FORCE LINE BREAK
CHAR 0x0091
CHAR 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 Bridge
The 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.
Holding server Other server
DOC1 Port
Print to Other server
Monitor
EDINAT client Workstation

Job DOC1 Upload Other server
Output Service
Workstation
Workstation
DOC1 APPC client

EMFE batch PCE DOC1
outputs Journal
ReadyEDI
utility
Job
Job
Job
Output
Job
Output
PSF Prepared Merged Merged
Output
Output
AFPDS outputs outputs
Concatenate as required
DOC1 Host
EDINAT/DOC1 Production bridge environment
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.
138 Integrating with third party products

The DOC1 Upload Service
The 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 is
doc1uploadconfig.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 -install
This 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:
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
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:
LUADD ACBNAME(S43APP1)
SCHED(ASCH)
TPDATA(SYS1.APPCTP)
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:
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:
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
++
##
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_SERVICE
NET STOP DOC1UPLD_SERVICE
You can monitor the upload process via the Windows event viewer.
The DOC1 Port Monitor

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

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 NT

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

Example DOC1holding.inf file
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
; 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"
Port Monitor installation for Windows 2000 & XP

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

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
M e rg e d
host system
o utp u ts
Uploaded 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
R ea d yE D I and also splits out the journal information so that it can be used as an index
utility
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
P rep a re d DOC1 datasteam format with each document stored as a separate record in the
A FP D S Jo u rna l
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.
Structure of DOC1 Journal files as produced by READYEDI
Vector offset (10 characters) S Page count (5) S EDINAT journal string (variable length)
S = user defined separator character. This will only be included if specifically requested when starting READYEDI
You may need to be aware of this structure if you need to parse the various
fields when programming PCE.

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
//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
//* 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
<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
<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 data
The 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.
h 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 output
The 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.

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 default
Keycode=Keycode ;no default
<Files>
Messages=Filename ;mandatory - no default
Input=FileName ;mandatory - no default
DataFormat=FileName ;mandatory - no default
ReformatOutput=Filename ;mandatory - no default
<Reformat>
FormatType=XML
KeyField=FieldName
ShowEmptyRecords={YES|NO} ;default NO
ShowKeyDefField={YES|NO} ;default NO
DateFormat=DateCode ;default %Y/%m/%d
Symbols="Controls" ;default "{}[]" i.e. "x’47',x’48',x’49',x’50'"
CompactSpaces={YES|NO} ;default YES
<XML>
Schema=SchemaName ;default DOC1
DefinitionName=String ;no default
DocumentDate=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 sign
Examples:
DateFormat="%m/%d/%Y" e.g. 04/13/2000
DateFormat="%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.dat
Input=\production\input511.dat
DataFormat=\doc1\resources\app511.edf
ReformatOutput=\xmlout\app511.xml
<Reformat>
FormatType=XML
KeyField="Account number"
ShowEmptyRecords=YES
ShowKeyDefField=YES
DateFormat="%m/%d/%Y"
CompactSpaces=NO
<XML>
Schema=DOC1
DefinitionName="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 line
A 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.
h 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 Lines

The 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:
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 Pages
For 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 Block
The 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 CASSing
CASSing 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.
h THEPOSTNET 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.
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 Id
Run Date
Resource Set
Cycle #
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 Id
Run Date
Resource Set
Transmission Number
OTS CASS
Cycle #
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.
h 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.
h 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.

OTS Records
This 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.
File Header Record (FILEHEAD)
Field Name Length Description Values Set by1 Validation2
Record Length 05 Maximum length of record "512"– System (defaults to "8196")

32759 <AFPDS>MaxRecordSize
Cycle 02 Numeric cycle within "01"–"31" <>Cycle Aborts if

the month Info (Cycle) out of range
OTS Corp ID 05 The unique, OTS-assigned <>CorpId Aborts if

Corporate ID number Info (Corp Id) not numeric
Run Date 08 The customer’s billing run date in System (Run Date) Aborts if
the format mmddyyyy <>Run Date date is.
Info(Run Date) invalid
Summary 06 The OTS-assigned print <>ResourceSet

Resource Rev # profile ID Info (Resource Set)
CASS Flag 01 "C" and "N" means that no "Y", "C", "System (defaults to "Y") Uses default
CASS-related NOPs are or N <>OTSCASS value if invalid.
generated. Info (OTS CASS)
Transmission 03 Incremented Transmission System (defaults to "001") Uses default

Number Sequence Number <> Transmission Number value if out
Info (Transmission Number) of range.
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.

Address2 Information
This 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".
Address2 Information Record
Field Name Length Description Values Set By1 Validation2
Address Line 1 60 Customer name, business name, Address (Name)

an address line, or blanks if not used
Address Line 2 60 Customer name, business name, Address (Address 2)




Address Line 6 60 City/State/Zip line – comprised Address (City)

City name, a two-char State code Address (State)
and a 10-char ZIP code Address (Zip)
Address Type 1 Residential or "R" System (Defaults to "R") Uses default

Business address type "B" Info (Business/Residential Flag) value if out
of range.
1
2
Whenever a value is detected as invalid, a message will be output to the user explaining why the value is invalid.
h 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.

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

Statement Trailer
This record is always included once per document and contains details of that
document.
Statement Trailer Record
Account Number 50 Unique tracking number System (defaults If not unique, a

to Statement sequence) warning message
Info (Account Number) is produced
Statement Type 01 Bill Type Handling Group "0", "H" System (defaults to "0" Invalid values default
If Special Handling Code is "A", "G" Info (Statement Type) to "0" (zero) for Normal
set to other than "99", value bills and "H" for Normal
is set to "H" for Normal bills Held/Special Handled
or "G" for Forced Flat Bills. bills.
Number of 02 The number of copies of "01-99" System (defaults to "01") Uses default
Copies this statement including <>Copies value if invalid
the original Info (Copies)
ZIP Code 12 The ZIP+4 Code Address (Zip Code)
Special Handling 02 Special handling option3, 4 "01-79" System (defaults to "99") Invalid values
Code Info (Special Handling Code) default to "99".
No-Print Switch 01 Whether statement should "Y" System (defaults to "N") Uses default
be printed or not. "N" <>NoPrintFlag value if invalid.
Info (No Print Flag)
Country Code 03 See note 5. System (defaults to Blanks)

Info (Country Code)
Original Insert 11 Bill Inserts System (defaults to all "N"s) At most 5 of the flags
Combo Info (Insert Combo 1-11) 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 letters
otherwise Info (State Code)
Total Dollar 10 Total monies due on this System (defaults to Zeros) Uses default
Amount particular statement/document7 Info (Total Dollar Amount) value if invalid.

Statement Trailer Record
Dollar Sign 01 "" System (defaults to Blank) Uses default

Value "-" Info (Total Dollar Amount) value if invalid.
Carrier Route 04 The carrier route populated System (defaults to Blanks)

Note: This field is not tied Info (Carrier Route)
to CASSing
Product Code 03 " " or System (defaults to Blanks) Uses default

"E01" Info (Product Code) value if invalid
Info (E-Bill Flag) when set to Y
will set this to "E01".
1
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.

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 default
CorpId=Number ;no default
RunDate=Datecode ;no default
ResourceSet="String" ;no default
OTSCASS={Y|C|N} ;default Y
TransmissionNumber=Number ;default 1
Copies=Number ;default 1
NoPrintFlag={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=15
CorpId=5339
RunDate="01152001"
ResourceSet=3297
OTSCASS=Y
TransmissionNumber=1
Copies=1
NoPrintFlag=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 Requirements
To 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 exits
In 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 type
An 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 type
A 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 type
A 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 exits
This 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 applications
User 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 Identifier
Enter the Identifier that has been specified for the function in the User Exit
control file.
Parameter references
Use 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 value

This 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 applications
In 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 equivalent
MVS_COBOL – Cobol call from OS/390 or equivalent
NT_SYSTEM - any call from Windows NT or equivalent
OS2_SYSTEM – any call from OS/2
AS400_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 Main
CALL2 INSTRUCTION MVS_COBOL DOC1EXIT GoExit
CALL3 PRINTSTREAM UNIX_SYSTEM /DOC1EXIT/AFPSUPP AddGoca
CALL4 DATA_INPUT AS400_ILE DOC1PROG Doc1Call
Preparing DOC1 applications for user exits 179

Creating the user program
The 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 cells

DOC1 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.
h 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.
180 User Exits

Initiation
Each 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 exchange

The 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 modes
The 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 file
CbData – 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 record
cbMax – 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 Data
User 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.
h 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.

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
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.
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
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
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
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 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 & linking
If 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 -shared
HPUX -b
Sun: -G -K pic -lelf
Under AIX the module must be exported. For example:
AIX: -bE:name.exp -bM:SRE
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
//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.
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 requirements
The 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 API
The 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.
Data Exchange API functions to access memory cells
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
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.
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 9900

UxitGetString (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 put
cbString Count of bytes in string.
Return Codes None
Example // Return a string in memory cell 9999

UxitPutString (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 function
UxitGetArraySize (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 function
void 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'
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'

W-MEMCELL-ID
W-TEXT-BUFFER
W-TEXT-LENGTH.
Parameters 01 W-MEMCELL-ID PIC S9(9) COMP VALUE ZERO.

01 W-TEXT-LENGTH PIC S9(9) COMP VALUE ZERO
Return Codes None
Example * Return a string in memory cell 9999

CALL 'LEMPSTR'
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 queried
W-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 read
W-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.
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);
}
else if (strcmp (pszMode, "DIED") == 0) // Abnornal termination?
{ // Do the ‘died’ (abnormal termination) tasks and set return code to ok.
}
else if (strcmp (pszMode, "TERM") == 0) // Normal termination?
{ // Do (normal) terminate tasks and set return code to ok.
User program examples 197

}
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-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
* 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
TEST-FOR-DIED.
IF W-COMMAND-ID = 'DIED'
PERFORM DIED-PROCEDURE
TEST-FOR-TERM.
IF W-COMMAND-ID = 'TERM'
PERFORM TERM-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 'Some text string .... ' TO W-TEXT-BUFFER.
CALL 'LEMGSTR'
W-MEMCELL-ID
W-TEXT-BUFFER
W-MIN-BUFF-SIZE
W-MAX-BUFF-SIZE
W-TEXT-LENGTH.
* Do your stuff here!
CALL 'LEMPSTR'
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.
EXEC-EXIT.
200 User Exits

EXIT.
*
DIED-PROCEDURE SECTION.
DIED-START.
* Do the died processing here
MOVE 'DIED process completed' TO W-MESSAGE-TEXT.
DIED-EXIT.
EXIT.
*
TERM-PROCEDURE SECTION.
TERM-START.
* Do the termination processing here
MOVE 'TERM process completed' TO W-MESSAGE-TEXT.
TERM-EXIT.
EXIT.
*
INVALID-COMMAND-PROCEDURE SECTION.
INVALID-START.
* Do the invalid command processing here
STRING W-COMMAND-ID DELIMITED BY SIZE
' - ' DELIMITED BY SIZE
'command id not valid' DELIMITED BY SIZE
INTO W-MESSAGE-TEXT.
INVALID-EXIT.
EXIT.
*
*

202 User Exits
Index
Symbols Cell parameter 176
CevAddFirmDataLibrary
Reference 110
%@ in PCE composition edit commands 68 CevAddFirmDataLibrary API function
.BMP 134 Usage 106
.EAR 103 CEVAPI.H 104
.EDF 103 CevConvertRules API function
.EOL 103 Reference 111
.LAR 103 Usage 107
.LDF 103 CevCreateObject API function
.LIM 89 Reference 111
Usage 106
A CevCreateWindow API function
Reference 112
Account group 80 Usage 108
add DJDE, PCE command 27 CevDestroyObject API function
add document id, PCE command 27 Reference 112
add document name, PCE command 28 Usage 106
add document TLE, PCE command 28 CevDoubleToLu API function
add medium map, PCE command 29 Reference 113
add TLE, PCE command 29 Usage 108
Address block 161 CEVENVINFO structure 130
Address2 Information 166 CevExecuteRules API function
AFP Index 21 Reference 113
AFPDS Usage 107
Attribute Name triplet 28 CEVGRIDINFO structure 130
Attribute Qualifier triplet 28 CevInitApi API function
Attribute Value structured field 28 Reference 114
Begin Named Page Group structured field 59 Usage 106
End Named Page Group structured field 59 CevLuToDouble API function
Manipulating with PCE 13 Reference 115
Named group structured field 21 Usage 108
Opening with PCE 53 CevProof API function
PCE operand 55 Reference 115
TLE structured field 30, 42, 62 Usage 108
AIX 186 CevQueryActivePage API function
and not, PCE operator 39 Reference 116
and, PCE operator 39 Usage 107
ApiData Data structure 184 CevQueryDataDocCount API function
Application Layer Editor. See ALE Reference 116
Application Rules 103 Usage 107
Arrays of PCE variables 15, 34 CevQueryDataDocKey API function
atrim, PCE parameter 47 Reference 117
Attribute Name, TLE attribute 28, 30, 42, 62 Usage 107
Attribute Value, TLE attribute 28, 30, 42, 62 CevQueryDataDocKeyId API function
Reference 117
B Usage 107
CevQueryDataDocLabel API function
Reference 117
Barcodes 19
Usage 107
BCOCA 49
CevQueryDocCount API function
begin CE, PCE command 30
Reference 118
begin loop, PCE command 31
Usage 107
Begin Named Page Group structured field 59
CevQueryGridInfo API function
begin procedure, PCE command 31
Reference 118
BEGIN, RTF2LDO keyword 89
Usage 108
Bitmap used with Characters dialog 134
CevQueryPagesInDoc API function
Block headers In PCE 16
Reference 119
Boolean evaluation in PCE 14, 39
Usage 107
C CevQueryResolution API function
Reference 119
Usage 108
call procedure, PCE command 32 CevQueryRulerInfo API function
Call Type, User Exit Control file 178 Reference 119
203
Usage 108 Literals 23
CevQueryScrollInfo API function Procedure 14
Reference 120 Sample 77
Usage 108 Variables 14, 23
CEVRULERINFO structure 131 Declaring 34
CEVSCROLLINFO structure 132 Control Files for Preview API 106
CevSetActivePage API function Control script for RTF2FDO 87
Reference 120 Convert images to bitmaps 96
Usage 107 Copies, Initialization file keyword 170
CevSetBackColor API function CorpId, Initialization file keyword 170
Reference 121 Current print position 66
Usage 108 CustomerName
CevSetEnvironment API function Reformat Initialization file keyword 154
Reference 121 Cycle, Initialization file keyword 170
Usage 106
CevSetGridInfo API function D
Reference 121
Usage 108 Data Format Editor 105
CevSetResolution API function Data format file 103
Reference 122 Data structures within a user program
Usage 108 'C' definition 191
CevSetRulerInfo API function Data Type Definition 152
Reference 122 Data types in PCE 26
Usage 108 DATA_INPUT user exit 173
CevSetScrollInfo API function DataFormat
Reference 122 Reformat Initialization file keyword 154
Usage 108 Dataset names in PCE Control file 24
CevStartTrace API function date environment value 43
Reference 123 DBCS 19
Usage 109 DBCS-HEX, PCE operand 48
CevStopTrace API function DBX, CE command 69
Reference 123 DD label in PCE Control file 24
Usage 109 declare procedure, PCE command 33
CevTerminateApi API function declare, PCE command 34
Reference 123 Define Image List 70
Usage 109 Define Overlay List 70
CEVUOM enumerated type 129 DefinitionName
CevUseEngineRuleFiles API function Reformat Initialization file keyword 155
Reference 123 Delimited file types 16
Usage 106 Delimited, PCE operand 55
CevUseLogicalRuleFiles API function DFE 105
Reference 124 DHR, CE command 70
Usage 106 DIED user exit invocation mode 182
CevUseObject API function Digital UNIX 186
Reference 125 DIJ 18
Usage 108 opening in PCE 55
change DIJelement, PCE command 32 DIJelement 32, 40
CHAR(S) keywords in Character Layout file 134 DIL, CE command 70
Character Layout file 133 DJDE, adding to print datastream 19
Characters dialog 11, 133 DLL file
Chart data object 81 For Preview API 104
Charts, with DHTML 81 DLM 94
close, PCE command 33 DOC1 for Workgroups. See Workgroups
CLSE user exit invocation mode 183 DOC1 Interchange Journal. See DIJ
Cobol Functions with user exits 192, 196, 199 DOC1 PCE. See PCE
Coding a Character Layout File 133 DOC1 Port Monitor 142
COL, CE command 69 DOC1 Production Bridge 138
Color, setting in PCE 69 DOC1 Upload Service 139
Comments in PCE Control file 25 DOC1GFC 97
CompactSpaces DOC1GLC 99
Reformat Initialization file keyword 155 DOC1RFC. See RFC
Composition edit 66 DOC1RFL. See RFL
Conditions in PCE routines 14 DOC1RFMT 152
Consolidation level in LFL2FDO 95 DOC1RFP. See RFP
contains, PCE parameter 39 docoffset environment value 43
Control file document attributes object 80
Comments 25 Document layouts 162
Concepts 14 Document Library Editor 94
Filenames 24
204 Index - D
Document Object Editor. See DOE G
Document object library 103
Extracting objects 94, 95
Document objects ge, PCE operator 39
Creating from Firm Data Libraries 94 Group level TLE’s 21
Document Repository 18 Grouping documents in PCE 20
DocumentDate gt, PCE operator 39
Reformat Initialization file keyword 155
Documents, grouping in PCE 20 H
DOE
Creating customized pages for Characters dialog 11, 133 Header data in print datastreams 16
DOS Header file
Filename convention 12, 24 For Preview API 104
PCE read offsets 58 Host Resource Files 103
Running DOC1RFMT 156 HPUX 186
DPOL, CE command 70 HTML 79
Draw Box 69
Draw Horizontal Rule 70 I
Draw Vertical Rule 71
DTD 152
Identifier, User Exit Control file 178
DVR, CE command 71
if, PCE command 37
dXML 152
Image Metrics 67
E Image resources
Converting images to bitmaps 96
Image used with Characters dialog 134
EDINAT 138 IMAGE, RTF2LDO keyword 89
else, PCE command 37 in range, PCE operand 39
EMFE Identifier for user functions 176 Indexing for AFP 21
EmfeInputData data structure 185 INI. See Initialization file
end ce, PCE command 34 INIT invocation mode 184
end if, PCE command 37 INIT user exit invocation mode 182
end loop, PCE command 35 Initialization File
End Named Page Group structured field 59 For Reformat 153
end procedure, PCE command 35 Initialization invocation mode 182
Engine rules 103 Input
Environment values in PCE applications 42 Reformat Initialization file keyword 154
eq, PCE operator 39 insert object, PCE command 37
Errors during PCE applications 51 INSTRUCTION
Exception dictionary file 47 User exit 173
Execution invocation mode 182 User Exit Control file 178
exit loop, PCE command 35 Invocation modes
Exit type, User Exit Control file 178 Data structure 184
of user exits 182
F InvocationMode structure 175, 184
is Main, PCE parameter 33
False comparison using PCE 39
File Header, OTS 165 J
Files
Naming conventions 12 Java applet for DHTML deployment 81
PCE concepts 15 JDataMode 81
Pointers and offsets 17 JDataURL 81
Firm Data Journal Files, In PCE 17
BLOB support 138 JPThreshold 81
Firm Data Objects 138 JUST, RTF2LDO keyword 89
Font
Mapping names from RTF style 85 K
Reversed text 74
Font Equivalents File 92
Key Field 105
Font Metrics 67
Key ID 105
Font Reference by Index
Keycode
in CE commands 67
Font references - changing 97
KeyField
for...next, PCE command 36
FORCE LINE BREAK 134
ksdsafp, PCE parameter 54
format, PCE sub-command 54
ksdsmeta, PCE parameter 54
FormatType
Function, User Exit Control file 179
Index - K 205
L N
Labels of Document Layouts 105 Name parameter

LADCEV.DLL 104 User Function object 176
LADCEV.LIB 104 ne, PCE operator 39
le, PCE operator 39 next, PCE command 36
LEMGSIZ 193, 195 NoPrintFlag, Initialization file keyword 170
LEMGSTR 192 not, PCE operator 39
LEMPSTR 193 Notification Codes from Preview API 127
Length of strings with PCE 44 NT. See Windows
let (boolean), PCE command 39 Numeric computations in PCE 44
let (copy), PCE command 49
let (number functions), PCE command 44 O
let (string manipulation), PCE command 45
let … (environment values), PCE command 42 Object header 175
let … call userexit, PCE command 40 Objects for Preview API 106
let … DIJelement, PCE command 40 Offsets for IO operations in PCE 17
let … document id, PCE command 41 On error call, PCE command 51
let … document name, PCE command 41 OPEN user exit invocation mode 182
let … document TLE, PCE command 42 open, PCE command 53
let … page count, PCE command 44 OpenVMS
let...TLE..., PCE command 48 Filename convention 12, 25
Level, TLE attribute 28, 30, 42, 62 Running DOC1RFMT 156
Library file or not, PCE operator 39
For Preview API 104 or, PCE operator 39
line, PCE operand 53 OS/2
LINESP, RTF2LDO keyword 88 Filename convention 12
LINESPV, RTF2LDO keyword 88 Location of user exit programs 187
Linking with Data Exchange API 186 Running DOC1RFMT 156
Literals in PCE routines 23 OS/390
Log file Filename convention 12, 24
With PCE Control file 20 Linking with user programs 186
Logical page 66 Location of user exit programs 187
Logical rules 103 Opening files with PCE 53
LOL2LDO 94 PCE read offsets 57, 59
LOOKUPKEY, RTF2FDO keyword 89 Running DOC1RFMT 158
Looping in PCE routines 14 Running READYEDI 147
lt, PCE operator 39 OS/400
ltrim, PCE parameter 46 Filename convention 12, 24
LUNIT type 129 Linking with user programs 187
Location of user exit programs 187
M Opening files with PCE 54
PCE read offsets 57, 59
Main procedure in PCE Control file 33 Running DOC1RFMT 157
MAKEBMP utility 96 OTSCASS, Initialization file keyword 170
MAKEEDF utility 159 overwrite, PCE command 56
mapp, PCE parameter 46
MEASURE, RTF2LDO keyword 88 P
Medium map, adding reference to AFPDS 19
Memory cells 180 Page level TLE’s 21
For Return Data 183 pageoffset environment value 42
Memory requirements of PCE 15 Pages with PCE 15
Merge Application Rules Utility 101 Changing 19
merge, PCE command 49 Counting number in document 44
MERGELAR 101 Moving into a document 51
Messages PAK file 79
Reformat Initialization file keyword 154 Panels for DOC1RFMT under OS/400 157
Metacode Parameters
Identifying in PCE Control file 55 User Function object 176
Manipulating with PCE 13 PCE
mixc, PCE parameter 47 Adding AFP index fields 29, 61
Module, User Exit Control file 178 Adding AFP medium maps 29
move page, PCE command 51 Adding DJDEs to Metacode datastream 27
move, PCE command 50 Adding document names 27, 28
Adding print elements to existing pages 30
Boolean evaluation 39
Calling error routine 51
206 Index - L
Calling user exits 37, 40 READ user exit invocation mode 183
Closing files 33 read, PCE command 57
Concepts 14 READYEDI
Conditional statements in Control file 37 Running on OS/390 147
Copying variables 49 Running on OS/400 149
Counting pages in document groups 44 Running on UNIX and OpenVMS 150
Declaring variables in Control file 34 Running on Windows, OS/2 and DOS 151
Document groups 20 Record headers with PCE 16
for...next loops in Control file 36 record, PCE parameter 53
Getting environment information 42 Reformat utility 152
Memory requirements 15 ReformatOutput
Merging pages 49 Reformat Initialization file keyword 154
Moving pages into a document group 51 replace, PCE command 60
Moving printable elements 50 ResourcePath 81
Numeric computation 44 ResourceSet, Initialization file keyword 170
Opening Files 53 Return codes
Overwriting strings 56 From Preview API 126
Quitting a process 57 Return Data from user exits 183
Reading AFP indexes 48 return, PCE command 60
Reading from files 57 ReturnStatus data structure 185
Replacing a string 60 Reversed text fonts 74
Returning from procedures 60 Right brace 154
Set page name for postscript 61 Right square bracket 154
String functions 45 RRDS VSAM format 13
Text manipulation 45 RTF 85
Translating text strings 63 RTF2LDO 85
Writing to files 63 rtrim, PCE parameter 47
Writing trace information 63 Rules files for Preview API 103
Physical page 66 RunDate, Initialization file keyword 170
PI, CE command 72
Place Image 72 S
Place Page Overlay 72
plain, PCE parameter 55 Sample file
Pointers in files used by PCE 17 for Preview API 104
Port Monitor 142 SAMPLE.C 104
Windows 2000 & XP 144 SBT, CE command 73
Windows NT 143 SBTR, CE command 73
Postal Information 167 Schema 152
PostScript Reformat Initialization file keyword 154
Font names 67 SCPP, CE command 74
PCE operand 55 SEARCHPATH, RTF2FDO keyword 87
PPO, CE command 72 SEEK user exit invocation mode 183
Preview API 103 Sequence Number
Preview object 103 TLE attribute 28, 30, 42, 62
Preview Window 108 Set Boxed Text 73
Print datastream Set Boxed Text Right Justified 73
Formatting with PCE 16 Set Current Print Position 74
Header data 16 set page name, PCE command 61
Print Positioning for composition edit 66 Set Physical Page Size 75
Printer controls, adding with PCE 19 Set Text Line 75
Printer resource references in PCE 67 Set Text Presentation 76
PrintOutput, Initialization file keyword 170 ShowEmptyRecords
PRINTSTREAM Reformat Initialization file keyword 154
User exit 173 ShowKeyDefField
User Exit Control file 178 Reformat Initialization file keyword 154
Procedures in PCE Control file 14 SIZE, RTF2LDO keyword 88
Production Bridge 138 SPPS, CE command 75
doc1holding.inf 142 Statement Trailer 168, 170
Proof printing 108 STL, CE command 75
STP, CE command 76
Q String functions in PCE 45
String, PCE operand 47
quit, PCE command 57 substring, PCE parameter 47
Summary Pages 161
R Sun 186
Symbol PCE operand 48
read … DIJentry, PCE command 59 Symbols
read … document, PCE command 59 From Initialization file 48
Index - S 207
Reformat Initialization file keyword 155 W
Sys_last_error 51
T Windows
Filename convention 12, 24
Linking with user programs 186
TELL user exit invocation mode 182 Location of user exit programs 187
TERM user exit invocation mode 182 Opening files with PCE 53
Text PCE read offsets 59
Manipulating in PCE 45 Running DOC1RFMT 156
Translating 63 Workstation Resource Files 103
time environment value 43 Workstation resources 97
TITLE keyword in Character Layout file 134 write DIJentry, PCE command 64
TITLE TEXT keyword in Character Layout file 134 write document, PCE command 65
TLE, AFPDS structured field 21, 30, 42, 62 write, PCE command 63
Identifying with PCE 48 wsafp, PCE parameter 54
TLE, PCE command 61 wsmeta, PCE parameter 54
Trace file
With PCE Control file 20 X
trace, PCE command 63
translate, PCE command 63
Translation Tables XML 79
With PCE Control file 63 Produced by Reformat 152
TransmissionNumber, Initialization file keyword 170
True comparison using PCE 39 Z
TXTBLK, RTF2LDO keyword 89
Zip Code 167
U
Unit of measure 66
UNITS, RTF2LDO keyword 88
UNIX
Filename convention 12, 25
Opening files with PCE 53
PCE read offsets 58
Running DOC1RFMT 156
Upload Service 139
User 171
User defined pages 133
User Exits 171, 175
Control file 176
Control File reference 178
Data Exchange API 188
In PCE 22
Set-up 171
User Function object 176
User Value object 176
UxitGetArrayElement 190
UxitGetArraySize 190
UxitGetString 189
UxitPutString 189
value, PCE parameter 44

Variables
in PCE 26
in PCE Control file 14
Arrays 15, 34
Copying 15
VERSION keyword in Character Layout file 134
VPS
PCE operand 55
VSAM
As print datastream file 13
Opening with PCE 53
Using offsets with document groups 59
vsamafp, PCE parameter 53
vsammeta, PCE parameter 53
208 Index - T

Doc1 v4 5 0 Programmers Guide 7d

Hochgeladen von

Dokumentinformationen

Originaltitel

Copyright

Verfügbare Formate

Dieses Dokument teilen

Dokument teilen oder einbetten

Freigabeoptionen

Stufen Sie dieses Dokument als nützlich ein?

Sind diese Inhalte unangemessen?

Copyright:

Verfügbare Formate

Doc1 v4 5 0 Programmers Guide 7d

Hochgeladen von

Copyright:

Verfügbare Formate

®

Security algorithms Copyright ©

Base 14 fonts and derivations

Printed in the UK.

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

Command File Reference ..................................................................................... 23

HTML DEPLOYMENT ...............................................................................................79

LOL2LDO – deconstructs document object library ...................................................... 94

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

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

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

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

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

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

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

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

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

Generating an OTS Finishing line .........................................................................160

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

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

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

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

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

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

This Programmer’s Guide describes the requirements of features in the

Windows, OS/2 or DOS

Updates to this manual

The DOC1 Post Composition Engine (PCE) handles the requirements of

The primary input to a PCE process is normally one or more output

Procedures and Program control

The start of a procedure is identified by a begin procedure command. All

If required, the return command in a procedure can immediately pass control

Variables, Data Types and Arrays

Concepts and Command Overview 15

Defining File Types

There are predefined record construct types to support datastreams stored as

Block and Record Headers

A specific close command is available which closes the appropriate file

Reading and Writing

File Pointers and Offsets

Concepts and Command Overview 17

DIJ indexes and the Document Repository

Documents that are referenced by a DIJ always have a unique identifier

Changing Composed Pages

Adding New Elements

Concepts and Command Overview 19

Error Handling and Environment

Support for AFPDS Indexing

Page level TLEs

Group level TLEs

To read existing document level TLEs use the let...document TLE

Note: it is assumed that there is enough memory available to PCE to read in

Concepts and Command Overview 21

User exits of type INSTRUCTION call an external user-defined program

User exits of type PRINTSTREAM are intended to return a self-contained

User exits of type DATA_INPUT are not supported for PCE.

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.

Variables and Arrays

To specify that a variable is an array or to reference a specific array element,

Command File Reference 23

let <Var2> = ‘Text String’;