Customer Engagement EngageOne® Compose ® EngageOne Generate Production Guide Version 6.6 Service Pack 9 Table of Contents 1 - Preface 5 - Programming PCE Conventions used in this guide 5 The PCE environment 64 Function overview and script command summary 64 2 - Working with Generate Script syntax 74 PCE command reference 78 About Generate 7 Composition Edit Commands 173 Using segmented resources 7 Script file sample 197 Code page support 8 Return codes 8 Messages 8 6 - Running PCE Legacy support 9 Debugging publications 9 PCE resources 200 OPS file 10 Creating an initialization file 202 Using symbols 28 INI section summary 204 Running Generate under z/OS 30 Start the job 218 Running Generate under UNIX and Windows 32 7 - Defining external keyed 3 - Running Generate in Server images Mode Embedding external keyed images 222 Server Mode Environment 35 External key map file 222 Running Server Mode 41 DOC1MAKE 224 XML structure of external key map 227 Example Keyed image XML 236 4 - Running Generate as a Started Task 8 - Working with resources in a Requirements 47 HIP file Defining the environment 48 Running Started Task 59 Extracting and manipulating resources 239 Extended configuration file examples 61 RPU 239 DOC1ACU 248 9 - Processing PDF output 13 - Output datastream formats DIME 252 Working with Designer output formats 336 DIME INI Reference 253 Predefined output formats 337 Running DOC1DIME 257 Customizing output formats 339 10 - Working with HTML 14 - Appendix A SCP code page reference Deployment considerations 260 EDU 267 Generate SCP (Set Code Page) Override values 351 11 - User exits Compatibility 273 Types of user exits 273 Preparing Generate for User Exits 274 Creating the user program 275 Programming guidelines & function overview 277 Code samples 281 User exit API function library 290 12 - Structured XML journals <ProductionJournal> 316 <CompositionDate> 317 <OutputDevices> 318 <StartOfJob> 319 <JE> 320 <Publications> 321 <Pub> 322 <PBO> 323 <PBC> 324 <Doc> 325 <DO> 326 <PG> 327 <PGO> 328 <PGC> 329 <JE> 330 <EndOfJob> 331 <JE> 332 Example 333 EngageOne® Compose EngageOne® Generate Production Guide 3 1 - Preface This section describes typographic and naming conventions used throughout this guide. In this section Conventions used in this guide 5 Preface Conventions used in this guide Typographic conventions [...] text 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). File naming conventions The following conventions are expected whenever you need to specify file names in the Generate environment. z/OS All files are referenced by Data Definition (DD) labels with actual datasets being assigned to these labels in start-up JCL. Example: Output=DD:AFPOUT Windows Files are referenced by path (optional) and filename. If a path name is not specified Generate will search the current directory (from which Generate was started) for the filename. Example: Output=C:\DOC1HOST\AFPOUT\APPLIC1.AFP UNIX Files are referenced by path (optional) and filename. If a path name is not specified Generate will search the current directory (from which Generate was started) for the filename. Example: Output=/doc1host/afpout/applic1.afp Updates to this Guide This guide is issued in electronic format (PDF) only. It may be reissued from time to time to include corrections or additions that have been made since the original issue. These changes will be indicated with a change bar in the margins. The latest version of all product user guides can be downloaded from the DOC1 Support Net website. EngageOne® Compose EngageOne® Generate Production Guide 5 2 - Working with Generate Generate is the batch program that processes production jobs on your chosen host system. Generate reads information about the job requirements from a HIP file, merges the input data file it receives with your publication designs and produces output datastreams ready for printing or presenting on your intended output devices. In this section About Generate 7 Using segmented resources 7 Code page support 8 Return codes 8 Messages 8 Legacy support 9 Debugging publications 9 OPS file 10 Using symbols 28 Running Generate under z/OS 30 Running Generate under UNIX and Windows 32 Working with Generate About Generate The program typically has the name DOC1GEN on all platforms. You will need to run the program from the batch environment appropriate to your host system and production process: command line, script, JCL, etc. The name and location of the HIP file that is to control a job is specified as a parameter to the DOC1GEN program when it is started. Normally, all other file references will have been specified in the production job settings that were used when the job was published in the Designer. If required however, you can create an Override Production Settings file (OPS) in which you can specify additional/alternative file references and other settings. Where used an OPS file is specified as a second parameter to the DOC1GEN start-up command. Note: On some supported platforms memory resident versions of DOC1GEN are available (Server Mode and Started Task). These allow a Generate production environment to remain loaded and for batches of input data passed to the defined channel to be processed dynamically. You will need to configure the environment before running in these modes and the launch method will differ from that described in this section. For more details see “Running Generate in Server Mode” and “Running Generate as a Started Task” in the Production Guide. You will need to ensure that all input files referenced in the productions settings and the OPS file are available at the locations specified when DOC1GEN is started. For jobs running under z/OS indirect file references using DD names are typically used in which case the start up JCL will need to include DD cards with these labels that indicate the actual datasets. Output files will be created with the file location/names specified in the production settings and the OPS file. You will need to ensure that suitable disk space is available to receive the output at the defined location. Under z/OS you will need to allocate suitable datasets either in advance or as part of start-up JCL if DD references are used. Using segmented resources Where you are using independently published (segmented) resources or Active Content you should be aware of the following: • Generate needs to know where to find the segmented resources as they are not present in the design HIP file specified on the command line. The resource HIP or HIP's necessary for a job must be specified in the OPS file using the <Input> section ResourceHIP and ActiveContentLocation keywords. One or more ResourceHIP keywords can be used, allowing device specific resources to be kept separate if desired. Segmented resources must be in the same repository as the publication design. EngageOne® Compose EngageOne® Generate Production Guide 7 Working with Generate • Generate has no control over resource versions when working in this way. It is the user’s responsibility to ensure that all HIPs are compatible and contain the appropriate resources. • Care must be taken if resource HIPs specified by the ResourceHIP keyword contain conflicting device settings for the same device type. In this case the settings used by the last loaded HIP will be used, possibly resulting in unexpected output. • The <Output> Name keyword is specified differently when resources are published independently. See Output in the OPS section. Code page support In order to read input data and configuration settings specified on your production system DOC1GEN needs to be able to convert the data it receives into the Unicode format it expects internally. To do this it uses a range of code page tables that define the required translations. For most Western applications these tables are contained within DOC1GEN itself and you need to take no specific action in the production environment. Due to their potentially large size, code page tables for non-Western applications are stored in a separate Extended Code Page (ECP) file and you will need to ensure this is made available to DOC1GEN by referencing it when starting the program. Return codes DOC1GEN always returns 0 (zero) for successful completion or where warning messages (only) have been issued. Return code 16 is issued where a failure has occurred – i.e. where an abort message has been issued. Messages Messages issued by Generate are always written to the standard output medium for the system on which the program is running. A list of possible messages and their explanations can be found on the EngageOne® Compose Technical Support web site at https://www.pitneybowes.com/us/support/products/software/engageone-compose-support.html. EngageOne® Compose EngageOne® Generate Production Guide 8 Working with Generate Legacy support The DOC1 Series 5 production engine cannot process jobs created in a pre-Series 5 environment without modification. However, you can use Generate to automatically launch the Series 4 production engine (known as EMFE). To do this you need to call the DOC1GEN program with an OPS file (see below for details) that indicates the location of the EMFE program and the relevant EMFE initialization file. You should refer to your Suite 4 user documentation for details of the parameters and files that are required when using this method. Debugging publications When an error occurs in the logic of your publication design, you can use the debugging option in Generate or Preview to trace the problem. Processing stops on the first publication that causes the error and a tree structure is generated that represents the path the program took when the error occurred.