HP Exstream

Version 7.0MR5

Production Environment
© 2008-2009 Hewlett-Packard Development Company, L. P.

Confidential computer software. Valid license from HP required for possession, use or copying. Con-
sistent with FAR 12.211 and 12.212, Commercial Computer Software, Computer Software Docu-
mentation, and Technical Data for Commercial Items are licensed to the U.S. Government under
vendor's standard commercial license.

The information contained herein is subject to change without notice. The only warranties for HP
products and services are set forth in the express warranty statements accompanying such products
and services. Nothing herein should be construed as constituting an additional warranty. HP shall
not be liable for technical or editorial errors or omissions contained herein.
Contents

About the Production Environment ............................................................. 6

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6
Benefits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6
Guide Design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6
Viewing Settings for the Engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7
Determining the Package File Version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7

Running the Engine in the Windows Environment ........................................ 8

About the Engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8
Naming Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8
Transferring Package Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8

Running the Engine from the Command Prompt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9

Opening the Command Prompt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9
Running the Engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9

Running the Engine in Batch Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9

Running the Engine in the UNIX or Linux Environment ............................... 10

About the Engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Naming Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Transferring Package Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10

Running the Engine from the Shell Prompt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Running the Engine Using a Shell Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Special Considerations with AS/400 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Naming Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Transferring Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Running the Engine from AS/400 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Retrieving Output from AS/400 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Running the Engine on Mainframe Platforms ............................................ 15

About the Engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Naming Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Transferring Package Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15
Specifying File Names in Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Production Environment 3
 Using JCL Files to Run the Engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Common JCL Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Loading VSAM Package Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Running the Engine Using VSAM Package Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Using Dynamic Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Mainframe Engines and Connectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Control Files ........................................................................................... 23

Control Files and the Command Prompt . . ...... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Control File Types . . . . . . . . . . . . . . ...... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Formatting a Control File . . . . . . . . . ...... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Specifying Comments in a Control File ...... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Creating a Control File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Control Files and the System Key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

CONTROLFILE Switch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Inserting a Key in a Control File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
z/OS and the System Key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Control Files and z/OS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Specifying the z/OS Name in the Control File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Using a Fully-qualified Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Using Rules to Specify a File Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Specifying Multiple Package Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Normal Mode with Output Sorting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Specifying Package Files in PostSort Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Running the Engine with a Control File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Engine Reporting .................................................................................... 29

System Generated Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Message Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Report Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

System Performance ............................................................................... 34

Memory Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Release Memory with New Sections/Customers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Store Transaction Tables in Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Improving z/OS Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

MEMORYCACHE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Queues and z/OS File Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Pre-Load Reference Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Memory Use at Run Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Production Environment 4
 Running Multiple Instances of the Engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Troubleshooting ..................................................................................... 42
Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

Index .................................................................................................... 46

Production Environment 5
About the Production Environment

Introduction
There are two engines included with the HP Exstream content creation and design environment. You run the
design engine from the Design Manager interface for testing purposes. Each design station includes a copy of
this engine. The engine is required to run HP Exstream in a production environment. You run the engine from the
command prompt, through scripts or Job Control Language (JCL). You must use engine switches and specify
them either on the command line when you execute the program or in a control file to run the engine.

Benefits
There are many benefits to using the engine, including the following:
Š You can install the engine on several different platforms:
• Windows
• z/OS
• UNIX
• Linux
• AS/400
Š The engine eliminates the “Demonstration Powered by HP Exstream” tagline on the composed output.

NOTE: If you run the engine for the production environment from a design workstation, the engine
is limited to 120 pages per minute. If you run the design engine, it runs at full speed.

Guide Design
This guide assumes a strong understanding of your operating system and system administration concepts.
This guide provides the answers to the following questions:
Š How do I set options for the engine?
Š Which which operating systems can the engine work?
Š How do I use the command prompt to run the engine?
Š How do I run the engine on the Windows Server Environment?
Š How do I run the engine on the UNIX or Linux Environment?
Š How do I run the engine on AS/400?
Š How do I run the engine on z/OS?
Š What are control files, and how do I use them?
Š How can I improve system performance?
Š What are some frequently asked questions about the production environment?

Production Environment 6
 About the Production Environment

Viewing Settings for the Engine

The System Settings are located under the System heading under Environment. The settings you have
purchased are activated with your system key and are selected in the Production Environment area in
System Settings.

For more information about the System Settings, see the System Settings chapter in the System Adminis-
tration guide.

To determine whether you can run in production mode, look at the Key string box on the Key tab in the
System Settings. In this box you can view:
Š Whether you can run in single-byte or double-byte mode.
Š If the license is capable of production.
Š When the key expires (if it expires).
In addition, the Operating Systems area shows you on what operating systems the key lets you run the
engine. In the example below, this system can utilize Linux, UNIX, Windows, and z/OS operating systems.

For information on the platform you are using, see the chapter devoted to that platform: Running the Engine
in the Windows Environment; Running the Engine in the UNIX or Linux Environment; Running the Engine on
Mainframe Platforms.

Determining the Package File Version

Package file and engine versions are closely related. For the package file to work correctly, the engine and
package file versions must be compatible.
To determine the required engine version for the package file, you have two options. The first option is to use
the PubEngVersion.exe. You run this utility from the command line, as follows:
PubEngVersion -PACKAGEFILE=PackageFileName
If successful, PubEngVersion.exe issues a return code of 0 and the following message:
Required engine version is m.mm.rrr
It can also return error codes as shown below.

Return codes
Code Message

16 Buffer read error

12 Error with the PUB file
8 Can’t determine version
0 Success

The second option is to call the EnginVer function in the library PubEngVersion.dll. The Windows call
signature is:
__declspec(dllimport) int EnginVer(char * pPubFile, long * piPubFileLen, char *
pVersion, long * piVersionLen);
Pass the package (PUB) file name and PUB file name length in the first two arguments. The DLL writes the engine
version required as a string into the buffer pointed to by the third argument, and returns the length of this string
into the long integer pointed to by the fourth argument. It returns the same error codes as PubEngVersion.exe.

Production Environment 7
Running the Engine in the Windows Environ-
ment

About the Engine

The engine is supported in the Microsoft Windows environment. Supported operating systems include the
following:
Š Windows 2003 (Service Pack 2)
Š Windows Server 2008
Š Windows XP Professional
Š Windows Vista
To run the engine you must use engine switches and specify them either at the command prompt when you
execute the program or in a control file. The engine reads the commands on the command line before it reads
options in the control file. Thus, options you specify in the control file override the commands specified on the
command line.

For information on the available engine switches, see the Engine Switches and Return Codes guide.

Naming Conventions
When you work from the command prompt, it is important to adhere to the naming conventions of the platform
you are using.
On Windows, make the directory and file specifications of production file names or arguments as follows:
C:\dir1\...\dirn\filename
The drive specification, C:, is optional. If you omit the drive specification, the current working drive is assumed.
Each directory specification and file name can be up to 128 characters in length.
If you begin with a backslash (\), the file is relative to the root directory. If you do not begin the file specifi-
cation with a backslash, the file specification is relative to your current working directory.
When you are testing on any platform, you can use names like C:\Data Files\Customer.dat as the File
to use for data mapping on the Test Data Source tab. In a Windows environment, you can retain the
same naming convention for the File to use for data mapping on the Production Data Source tab as
well. Relative file names cannot be used in production, therefore you must provide the entire path.

Transferring Package Files

Depending on where the engine is located, you might need to transfer the package file to the production server.
You can transfer the package file using either of the following methods:
Š Use your FTP program in bin mode to transfer the file.
Š Copy the file using standard Windows functionality.

Production Environment 8
 Running the Engine in the Windows Environment

Running the Engine from the Command Prompt

You can run the engine from the command prompt using the following command:
prodengine -PACKAGEFILE=packagefilename
The mandatory PACKAGEFILE switch tells the engine which package file to use to compose the application. If
the package file name has spaces in it, you must remember to enclose the file name in double quotes (“ “). You
must specify the entire path if the package file is located in a different directory than HP Exstream.

For more information on the PACKAGEFILE and other engine switches, see the Engine Switches and Return
Codes guide.

Opening the Command Prompt

To access the command prompt in Windows 2000, and XP, click the Start > Program Files > Accessories
> Command Prompt. You may also access the command line by selecting Start > Run, and entering cmd
as the argument.
The MsgResource_<language>.dat file is required to run the engine. The engine uses the message resource file
to communicate messages to the user. The engine issues an error and stops processing if it cannot find the file.
Additional switches can be used to run the engine. You can also run the engine using a control file. When a
package file contains features the key doesn’t authorize, the engine issues a message indicating an unlicensed
feature and stops processing.

For more information on specifying a different message resource file using the DLGMSGLANGUAGE or the
DLGMSGRESOURCE switch in a control file, see the Engine Switches and Return Codes guide.

For information on creating and running the engine with a control file, see the Control Files chapter.

Running the Engine

To run the engine from the command prompt, change to the HP Exstream directory and enter the following:
prodengine -PACKAGEFILE
Add any additional switches necessary to run the engine. Remember to enter a space between each switch.
Press ENTER to run the engine. The customer numbers appear in the window as they are processed. When the
engine finishes processing, you return to the command prompt.

Running the Engine in Batch Mode

You can use a batch file to run the engine with only a single command on the command prompt. A batch file
can contain multiple commands as well as specific switches to execute the engine run.
To use a batch file, you must access the command prompt. If you have changed the directory to the batch file
location, then you can type the batch file name to start the run. If the batch file is located in a different directory,
then you must type the entire path of the batch file location.

For more information on creating and running the engine with a control file, see the Control Files chapter.

Production Environment 9
Running the Engine in the UNIX or Linux Envi-
ronment

About the Engine

The engine is supported in the UNIX and Linux environments. Supported operating systems include:
Š IBM AIX/RS-6000 5.1 and later
Š HP-UX 10.20 and above (32 bit or 64 bit)
Š Sun Solaris 2.5.1
Š OS/400 4.3.3
Š SUSE Linux: version 8.0 (Intel); kernel version 2.4.18 for build and 2.6 for exact regression
Š RedHat Linux: version 4.0 (Intel); kernel version 2.6

Naming Conventions
When you are working from the command prompt, it is important to remember to retain the naming conventions
for the platform you are using. Make the directory and file specifications of production file names or arguments
as follows:
/dir1/... /dirn/filename

TIP: When you are testing on any platform, you can use names like C:\Data
Files\Customer.dat as a Test Data Source.

If you do not begin the file specification with a slash (/), the file is relative to your home directory. If you begin
with a slash, the file is relative to the root directory. UNIX directory and file names are case sensitive. Be sure to
verify all directories and file names for spelling and case before using them. If the names do not match, an error
is issued.

Data file properies, Production Data Source tab, UNIX environment

Transferring Package Files

To run the engine in this environment, you must transfer the package file to the UNIX system. Transfer the
package file to the target system using your FTP program in bin mode.

Production Environment 10
 Running the Engine in the UNIX or Linux Environment

Running the Engine from the Shell Prompt

The mandatory PACKAGEFILE engine switch is used in the example below, in addition to some of the switches
which can be used in production mode. You can also run the engine using a control file. The directory and file
names used in the example might differ from those used in your environment. The following steps begin after you
have accessed the UNIX server using a telnet connection.

For more information on creating and running the engine with a control file, see the Control Files chapter
later in this book.

WARNING: When a package file contains features the key doesn’t authorize, the engine issues a
message indicating an unlicensed feature and stops processing.

To run the engine from a shell:

1. At the prompt, type cd followed by a space.
2. After the space, specify the directory where the engine is located.
3. Press ENTER to change the directory.
The change is successful when you are returned to the command prompt.
4. Type Engine after the prompt, followed by a space.
5. After the space, add the mandatory PACKAGEFILE switch.
In the example the entire path is added to the specified file name:
-PACKAGEFILE=/Exstream/INPUT/package.pub
6. Enter a space after the -PACKAGEFILE switch.
7. Add any additional switches necessary to run the engine.
Remember to enter a space between each switch.
8. Press ENTER to execute the engine.
The customer numbers appear in the window as they are processed. When the engine finishes processing, the
prompt returns.

Running the Engine Using a Shell Script

You can also run the engine on a UNIX server using a shell script. You use a shell script to run the engine with
only a single command at the shell prompt. A shell script can contain multiple commands as well as specific
switches used to execute the engine run.

For more information on creating and running the engine with a control file, see the Control Files chapter.

For more information on the CONTROLFILE switch, see the Engine Switches and Return Codes guide.

A sample shell script is shown below.

#!/bin/sh
# This script links the file input.dat to the pseudo-file DD:INPUT1
# then links optional.rule.file to the pseudo-file DD:INPUT8
# then executes Exstream (called ENGINE in this example)
# with the command options –controlfile=control.file and –
messagefile=message.summary
# A file DD:OUTPUT1 is created and then renamed to output.file
#
# This example assumes that all files are in the current directory

Production Environment 11
 Running the Engine in the UNIX or Linux Environment

# of execution and that ENGINE is in the execution path of the

# current user.
# Remember of course these values are case sensitive.
ln input.data DD:INPUT1
ln optional.rule.file DD:INPUT8
ENGINE –controlfile=control.file –messagefile=message.summary
mv DD:OUTPUT1 output.file

WARNING: When a package file contains features that the key doesn’t authorize, the engine
issues a message indicating an unlicensed feature and stops processing.

NOTE: The MsgResource_<language>.dat file is required to run the engine.

The engine uses the message resource file to communicate messages to the user. The engine
issues an error and stops processing if it cannot find the file.

For more information on specifying a different message resource file using the DLGMSGLANGUAGE or the
DLGMSGRESOURCE switch in a control file, see the Engine Switches and Return Codes guide.

Special Considerations with AS/400

The engine is supported on AS/400 for the OS/400 4.3.3.

Naming Conventions
When you work on AS/400, all files used by the application must exist in the same directory. Therefore, local
names are sufficient when defining file names in the Production Data Source tab. Directory and file names
are case sensitive.

TIP: When you are testing on any platform, you can use names like C:\Data
Files\Customer.dat as a file name on the Test Data Source tab.

Data file properies, Production Data Source tab, AS/400 environment

NOTE: To access native OS\400 files from the Portable Application Solutions Environment (PASE),
you must use the fully-qualified path to the data file. For example:
/QSYS.LIB/mydata.LIB/mytable.FILE/mytable.MBR

Production Environment 12
 Running the Engine in the UNIX or Linux Environment

Transferring Files
To run the engine from the AS/400 environment, you must use FTP to upload files to the directory where the AIX
engine is installed. These files include:
Š The package file.
Š Data files used in the application.
Š Any control files or script files to be used by the application.

For more information on creating and running the engine with a control file, see the Control Files chapter.

To upload files to the AS/400, use the FTP command quote site namefmt 1.

NOTE: Before uploading to the AIX engine directory, you must remove all carriage returns (line
feeds) from text files. To do this, replace all X’0D0A’ commands with X’0A’ commands.

To transfer files to the AS/400 system:

TIP: You can use the FTP command ascii to upload files that can be read with a text editor
program.

TIP: Use your FTP program in bin mode to upload all files that cannot be read by a text editor
program.

1. Use FTP to access the AS/400 PASE environment.

2. Change the directory to the one where the AIX engine is located.
For example: cd /Exstream/Tar
3. Upload the package file (PUB file) to the directory where the AIX engine is located.
4. Upload any necessary TXT or DAT files to the same directory.
Make sure the carriage returns have been removed from these files.
5. Upload the engine control file to the same directory.
To run the engine using a script file, upload the script file at this time.

Running the Engine from AS/400

The following steps utilize a control file.

DBCS: For more information on creating and running the engine with a control file, see the Control
Files chapter.

To run the engine:

1. Call the interactive shell environment from the AS/400 from a Telnet session.
For example: call qp2term
2. Change the directory to the AIX engine location.
3. Call the engine and specify the control file on the command prompt.
For example: ./Engine -CONTROLFILE=controlprod.opt
4. Press ENTER to execute the engine run.

Production Environment 13
 Running the Engine in the UNIX or Linux Environment

Retrieving Output from AS/400

To retrieve your output files:
1. Verify the output file has been created by the engine.
For example: ls
2. Using FTP, change to the local directory where you want to place the output file(s).
For example: lcd C:\FTP_Files\
3. Access the directory on the AS/400 where the AIX engine is located.
In the example, this directory is /exstream/tar.
4. Using the get command, copy the output file from the directory on the AS/400 to your local workstation.
For example: get AS400.pdf

Production Environment 14
Running the Engine on Mainframe Platforms

About the Engine

The engine is supported on a mainframe platform. Supported operating systems on mainframe platforms
include:
Š OS/390 version 2.6
Š z/OS 1.1 and later

Naming Conventions
It is important to remember to retain the naming conventions of the platform you are using. Directory and file
names on z/OS must be in all capital letters. For example, you use names like DD:DATAOUT or
‘HLQ.XXXX.XXX’ on z/OS.
When you test you can use local file names like C:\Data Files\Customer.dat as the File to use in test
on the Test Data Source tab. However, the production file must be located on the production platform.
Use the following naming conventions when working with z/OS files:
Š z/OS datasets or files must be comprised of up to eight segments of up to eight characters separated by a period.
The first segment is called the High Level Qualifier (HLQ). The HLQ defaults to your login name and is automati-
cally prepended to any data set name (DSN) not enclosed in single quotes. For example if you are logged in as
P390A, then TESTING.CONTROL is the same as 'P390A.TESTING.CONTROL’.

NOTE: Segments do not represent a directory structure.

Š Characters must be A-Z, 0-9, and $.

Š The directory structure must be flat and entered into the system catalog.

Transferring Package Files

To transfer a package file to a z/OS system, upload the package file using your FTP program in bin mode.

WARNING: The destination PDS for the package file must have the following DCB information:
RECFM=VB, LRECL=1024, Block Size=27560
Failure to comply causes the engine to read package files incorrectly. If the LRECL
setting is larger than 1024, the files are not read correctly.

Production Environment 15
 Running the Engine on Mainframe Platforms

Specifying File Names in Commands

You can use several formats to specify z/OS file names in commands. For example:
-COMMAND=DD:ddname
-COMMAND=dd:ddname(member)
-COMMAND=qualifier.qualifier.qualifier
-COMMAND=qualifier.qualifier.qualifier(member)
File names include:
Š ddname—The data definition of the file in your JCL
Š member—The member name of a PDS
Š qualifier—A z/OS data set

NOTE: The slash (/) character is supported as an argument specifier on the z/OS platform. It is
used to define parameters or switches on the command line interface.

Using JCL Files to Run the Engine

To run the engine on a z/OS system, you must create and use a JCL file. The sample JCL file provided with the
engine is valid when you substitute your file names for the ones provided.

For more information on specifying a different key by using the KEY, KEYFILE, or KEYPART switches in a
control file, see the Engine Switches and Return Codes guide.

WARNING: When a package file contains features that the key doesn’t authorize, you receive a
message indicating an unlicensed feature and the process stops.

Sample JCL file used to run the engine

//VERAFP JOB (999,POK), ",
// TIME=1440,
// NOTIFY=&SYSUID,
// REGION=0M,
// CLASS=A,
// MSGCLASS=H,
// MSGLEVEL=(1,1)
//*
//EBCEXE EXEC PGM=ENGEXE,
// PARM='-USECONTROL=YES'
//STEPLIB DD DSN=P390A.EXSTREAM.LOAD ,DISP=SHR
//DLMSGRES DD DSN=P390A.DMSGENUS,DISP=SHR
//EXMSGS DD DSN=P390A.EXSTREAM.VERMSG(MSGAFP2) ,DISP=SHR
//BANKDATA DD DSN=P390A.EXSTREAM.VERDATA(BANKDATA) ,DISP=SHR
//EXPACKAG DD DSN=P390A.EXSTREAM.VERPACK(PACKAFP) ,DISP=SHR
//EXREPORT DD DSN=P390A.EXSTREAM.VERRPT(RPTAFP2) ,DISP=SHR
//EXCONTRL DD DSN=P390A.EXSTREAM.VMSCTRL,DISP=SHR
//EXTRACK DD DSN=P390A.EXSTREAM.VERTRK(TRKAFP2) ,DISP=SHR
//EXOUTPUT DD DSN=P390A.EXSTREAM.VERAFP(EXAFP2) ,DISP=SHR

Production Environment 16
 Running the Engine on Mainframe Platforms

Common JCL Commands

The following is an explanation of the previous JCL example follows, beginning with line 9:
Š //EBCEXE EXEC PGM=ENGEXE
This command loads the engine. The load module is the PDS, P390A.EXSTREAM.LOAD, identified by the //
STEPLIB argument that follows.

Š //PARM='-USECONTROL=YES
This command defines the parameters for the load module. In this case, the JCL tells the ENGEXE load module to
use a control file. Since we did not set the name of the control file, the engine will use the default control value of
DD:EXCONTRL.
In this example the DD:EXCONTROL references P390A.EXSTREAM.VMSCTRL.

Š //STEPLIB DD DSN=P390A.EXSTREAM.LOAD,DISP=SHR
This command identifies the location of the load module.

Š //DLMSGRES DD DSN=P390A.DMSGENUS,DISP=SHR
This JCL is required to provide access to the message resource file which generates English language error
messages. DLMSGRES is the default DD value in z/OS for the English version of the message resource file. In this
example, the physical name of the message resource file is P390A.DMSGENUS.

Š //EXMSGS DD DSN=P390A.EXSTREAM.VERMSG(MSGAFP2),DISP=SHR
This control value identifies the MESSAGEFILE as DD:EXMSGS. This statement equates it to the physical file
MSGAFP2 in the PDS P390A.EXSTREAM.VERMSG. All engine messages are written to this file.

Š //BANKDATA DD DSN=P390A.EXSTREAM.VERDATA(BANKDATA),DISP=SHR
This command identifies the data file for the application. A value of DD:BANKDATA was entered as the name of
the production file used by this application. The statement equates the logical name BANKDATA to the physical file
BANKDATA in the PDS P390A.EXSTREAM.VERDATA.

Š //PACKAGE DD DSN=P390A.EXSTREAM.VERPACK(PACKAFP),DISP=SHR
This control value identifies the PACKAGEFILE as the DD:PACKAGE. This statement equates it to the physical file
PACKAFP in the PDS P390A.EXSTREAM.VERPACK. The package file is the file that the engine uses to create
output.

Š //EXREPORT DD DSN=P390A.EXSTREAM.VERRPT(RPTAFP2),DISP=SHR
This control value identifies the REPORTFILE as the DD:EXREPORT. This statement equates it to the physical file
RPTAFP2 in the PDS P390A.EXSTREAM.VERRPT. All engine report information is written to this file.

Š //EXCONTROL DD DSN= P390A.EXSTREAM.VMSCTRL,DISP=SHR

This statement equates the logical name DD:EXCONTROL to the physical file P390A.EXSTREAM.VMSCTRL.
The engine options are read from this file when the switch
-USECONTROL=YES is implemented.

Š //EXTRACK DD DSN=P390A.EXSTREAM.VERTRK(TRKAFP2),DISP=SHRIn z/OS, the default value for

the tracking file is DD:EXTRACK.
This statement equates it to the physical file TRKAFP2 in the PDS P390A.EXSTREAM.VERTRK.

Production Environment 17
 Running the Engine on Mainframe Platforms

Š //EXOUTPUT DD DSN=P390A.EXSTREAM.VERAFP(EXAFP2),DISP=SHR
This control value identifies the OUTPUTFILE as the DD:EXOUTPUT. This statement equates it to the physical file
EXAFP2 in the PDS P390A.EXSTREAM.VERAFP. The engine writes all the data destined for the output device
to this file. In this example, the output is an AFP print stream.

NOTE: When you select the output property Used resources only in any print stream that
supports it, the engine uses temporary files to generate the output. On z/OS systems, you
must allocate a temporary file (DD:TEMP) in your engine JCL. The space allocated for your
temporary file must be at least as large as your main file.

For more information on specifying a different message resource file using the DLGMSGLANGUAGE or the
DLGMSGRESOURCE switch in a control file, see the Engine Switches and Return Codes guide.

Using HFS for File Output

HFS is supported for file output with the z/OS version used to run the engine. With HFS, the output file size and
attributes resolve themselves. The DD statement takes the following format:
//OUT1 DD PATH='/u/joeuser/BANK.pdf',
// PATHOPTS=(OWRONLY,OCREAT,OTRUNC),
// PATHMODE=(SIRWXU),PATHDISP=(KEEP,DELETE)
The following table explains the DD statements.

DD statement explanation
Statement Explanation

PATHOPTS Use PATHOPTS to specify the access and status of the data file.
OWRONLY Use OWRONLY to specify that the program can open file for writing.
OCREAT Use OCREAT to specify that the system can create the file if it does not already exist.
OTRUNC Use OTRUNC to specify that the system is to truncate the file length to zero when all
the following conditions are true:
• When the file specified on the PATH parameter exists
• When the file is a regular file
• When the file successfully opened with ORDWR or OWRONLY
PATHMODE Use the PATHMODE parameter to specify the file access attributes when the system is
creating the HFS file named on the PATH parameter. Creating the file is specified by
a PATHOPTS=OCREAT parameter. Use the SIRWXU permission to allow the file
owner to do the following:
• Read, write, and search, if the file is a directory.
• Read, write, and execute, for a file other than a directory.
PATHDISP Use the PATHDISP parameter to specify what happens to the file if the job ends
normally or abnormally.

KEEP
Use the KEEP parameter to specify that the file should be kept:
Š When the step ends normally, KEEP is the first subparameter.
Š When the step ends abnormally, KEEP is the second subparameter.

Production Environment 18
 Running the Engine on Mainframe Platforms

DELETE
Use the DELETE parameter to specify that the file should be deleted:
Š When the step ends normally, DELETE is the first subparameter.
Š When the step ends abnormally, DELETE is the second subparameter.

Loading VSAM Package Files

A package file can be loaded into either an ESDS or KSDS VSAM file. The following JCLs illustrate how to
create and load both file types.
The engine tests package files to verify if they are Virtual Storage Access Method (VSAM) package files when
multiple package files are loaded. When VSAM package files are loaded, the engine loads objects as
necessary to enhance performance. In this case the index of available objects in memory contains only the
objects required for the current run. However, if any of the package files are not VSAM, the engine reads
objects from all the package files into memory and the index is populated for the engine run.

JCL to create the package file in an ESDS VSAM file

//DELETE EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
DELETE SVCS.TEST.TC36984.OUTPUT
DELETE SVCS.TEST.TC36984.PUB1ESDS
DELETE SVCS.TEST.TC36984.PUB2ESDS
//DEFINE EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//* DEFINE VSAM ESDS DATASET
DEFINE CLUSTER -
(NAME(SVCS.TEST.TC36984.PUB1ESDS) -
RECORDSIZE(80 32000) -
NONINDEXED -
VOLUMES(XBIG01)) -
DATA -
(CYLINDERS (2 1))
/*

JCL to create the package file in a KSDS VSAM file

//DELETE EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//* DELETE OLD DATASET
DELETE -
EXSTREAM.KSDS
/*
//DEFINE EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//* DEFINE VSAM KSDS DATASET
DEFINE CLUSTER -
(NAME(EXSTREAM.KSDS) -
RECORDSIZE(80 32000) -
VOLUMES(XBIG01)) -
DATA -
(KEYS(12 7) -
CYLINDERS (200 200)) -
INDEX -
(TRACKS (5 5))
/*

Production Environment 19
 Running the Engine on Mainframe Platforms

JCL used to load the package file into either VSAM file
VSAMRPRO
//REPRO EXEC PGM=IDCAMS
//INPUT DD DSN=QA.TC13811.PACKAGE(PKG4),DISP=SHR
//OUTPUT DD DSN=EXSTREAM.ESDS.PKG1,DISP=SHR
//SYSPRINT DD SYSOUT=*
//* REPRO
REPRO -
INFILE(INPUT) -
OUTFILE(OUTPUT)
/*

Running the Engine Using VSAM Package Files

The following example JCL illustrates how to run the engine using a VSAM package file.

JCL for Engine run using a VSAM package file

//EBCEXE EXEC PGM=ENGEXE,
// PARM='-USECONTROL=YES'
//STEPLIB DD DSN=EXSTREAM.VNN.LOAD,DISP=SHR
//DLMSGRES DD DSN=EXSTREAM.DMSGENUS,DISP=SHR
//EXMSGS DD DSN=EXSTREAM.MESSAGES.OUT(MSG1),DISP=SHR
//EXCONTRL DD DSN=EXSTREAM.INPUT(CONTROL1),DISP=SHR
//EXTRACK DD DSN=EXSTREAM.OUTPUT(TRACK),DISP=SHR
//EXREPORT DD DSN=EXSTREAM.OUTPUT(REPORT),DISP=SHR
//EXPKG1 DD DSN=EXSTREAM.VSAM.PKG1,DISP=SHR
//IN30832 DD DSN=EXSTREAM.INPUT(IN30832),DISP=SHR
//IN30932 DD DSN=EXSTREAM.INPUT(IN30932),DISP=SHR
//PDF DD DSN=EXSTREAM.PDF(PDF),DISP=SHR

Tuning Options
Various tuning options can be used to improve the performance of z/OS batch jobs when using VSAM clusters
to store the package file. The best tuning method to use depends on the system software available to you. In
order of preference, the tuning methods recommended are discussed in the following sections.

Option One: IAM

The best results have been obtained by using Innovation Access Method (IAM) which is a competitor product to
VSAM. There are no changes to the JCL required except to define IAM as the OWNER in the DEFINE CLUSTER
statement. For example:
DEFINE CLUSTER ( NAME(EXSTREAM.VSAMTEST.ESDS) -
OWNER($IAM) - this makes it an IAM dataset
STORCLAS(TEMP) -
NONINDEXED -
RECORDSIZE(80 32000) ) -
DATA ( TRACKS(600 50) )

NOTE: Not all z/OS environments have access to IAM.

Production Environment 20
 Running the Engine on Mainframe Platforms

Option Two: SMB

z/OS offers a technique called System Managed Buffering (SMB), a feature of DFSSMS, to improve VSAM I/O.
To use SMB; you must allocate the VSAM dataset in a SMS dataclass that supports Extended Format and you
must add the ACCBIAS parameter to the EXPACKAG DD statement. For example:
DEFINE CLUSTER (NAME(EXSTREAM.VSAMTEST.ESDS) -
VOLUMES(TESTDA) -
DATACLASS(XBIG) - this dataclass supports Extended Format
NONINDEXED –
RECORDSIZE(80 32000) ) -
DATA ( TRACKS(600 50) )
//PASS1 EXEC PGM=ENGEXE,
…
//* this is the DD for randomly reading the package during customer processing
//* DO: SMB optimizes buffers management to direct access.
//EXPACKAG DD DSN= EXSTREAM.VSAMTEST.ESDS,DISP=SHR, -
// AMP=('ACCBIAS=DO')

NOTE: You might need to ask a z/OS system programmer to find out which dataclasses support
Extended Format. You can see if the dataset is in extended format by using LISTCAT ALL
on the VSAM cluster and looking for Extended in the attribute section.

Option Three: BLSR

You can also improve performance using Batch Local Shared Resources (BLSR) in the DD statement that refers to
the VSAM package file. This is done in the engine step. For example:
//PASS1 EXEC PGM=ENGEXE,
...
//ESDSEXT DD DSN= EXSTREAM.VSAMTEST.ESDS,
// DISP=(OLD,DELETE)
//EXPACKAG DD SUBSYS=(BLSR,'DDNAME=ESDSEXT','BUFND=181')
In the example above, EXPACKAG is the default DDNAME for the package file and
ESDSEXT is a temporary DDNAME that references the actual VSAM package file.

Using Dynamic Images

The functionality described below is available only if you have licensed the Dynamic content import module.
Dynamic images are image files that are referenced in messages and other objects. They are placed according
to rules and customer information. You must specify additional engine switches when you are using dynamic
images.

For more information on the available engine switches, see the Engine Switches and Return Codes guide.

NOTE: When uploading images to a mainframe, upload the files using the FTP command bin.
Uploading using ASCII mode alters the image data.

Production Environment 21
 Running the Engine on Mainframe Platforms

The following is an example of a JCL used with dynamic images.

//VERTIFF1 JOB (999,POK), ",
// TIME=1440,
// NOTIFY=&SYSUID,
// REGION=0M,
// CLASS=A,
// MSGCLASS=H,
// MSGLEVEL=(1,1
//
//EBCEXE EXEC PGM=ENGEXE,
// PARM='-USECONTROL=YES'
//STEPLIB DD DSN=P390A.EXSTREAM.LOAD,DISP=SHR
//DLMSGRES DD DSN=P390A.MSGRESEN,DISP=SHR
//EXMSGS DD DSN=P390A.EXSTREAM.OUTMSG(MSGTIFF1),DISP=SHR
//TIFFIMPO DD DSN=P390A.EXSTREAM.TIFF(TIFFIMP),DISP=SHR
//PACKAGE DD DSN=P390A.EXSTREAM.PACKTEST(PACKTIFF),DISP=SHR
//EXREPORT DD DSN=P390A.EXSTREAM.OUTRPT(TIFF1),DISP=SHR
//EXCONTRL DD DSN=P390A.EXSTREAM.TIFFCTRL,DISP=SHR
//EXTRACK DD DSN=P390A.EXSTREAM.OUTTRK(TIFF1),DISP=SHR
//EXOUTPUT DD DSN=P390A.EXSTREAM.OUTAFP(TIFF1),DISP=SHR
//*

Mainframe Engines and Connectors

When using connectors, the engine does not wait for all customers in an application to be processed; instead,
it processes customers as they become available. When a mainframe engine is started, it produces an output
containing all of the customers already in the queue before getting the next group of customers. On all other
platforms, the engine retrieves the first customer in the queue and produces output for that one customer before
getting the next customer from the queue.

Production Environment 22
Control Files

Control Files and the Command Prompt

You use the control file to send options to the engine at run time. The control file is a text file containing engine
switches. When you use a control file, you do not have to type commands each time you run the engine.

For more information on the available engine switches, see the Engine Switches and Return Codes guide.

Any engine switch can be placed in a control file. When you use a control file, the only command necessary at
the prompt is the CONTROLFILE=command.

NOTE: Options in the control file override options placed directly on the command prompt.

Control File Types

You can use a control file for packaging or for a production run. Type the commands necessary for the
production or packaging run into the control file.

For more information on packaging with a control file, see the Packaging and the Design Engine guide.

NOTE: A package control file is created the same way as a control file for the engine. The only
difference is that packaging switches are used instead of engine switches.

Formatting a Control File

You type switches into a command file using the same format that you use on the command line. All switches
must be:
Š Preceded by a dash (-) or slash (/), depending on the platform
Š In capital letters

WARNING: If you include double quotes around a file name in a control file, errors are issued in
the message file, stating the specified file could not be found or created.

Production Environment 23
 Control Files

Specifying Comments in a Control File

Comments are non-processing information in control files. The engine ignores text or symbols from the comment
begin characters to the end of the line. You can use an asterisk or percent sign at the start of a line to comment
out the lines of text in a control file.
For example:
*comment text
%comment text

TIP: You can use comments to create a general control file, containing all the possible switches
necessary for a production run. Comment out any unnecessary switches before running the
engine. This makes the control file reusable.

Creating a Control File

When you create a control file you must select the engine switches necessary for the production run and add
them to the file. The engine switches used in the sample control file shown below are commonly used engine
switches. You must change the switches used in your control file to reflect the needs of your particular engine
run.

For more information on the available engine switches, see the Engine Switches and Return Codes guide.

To create an engine control file:

1. Open a text editor program. In the example, Windows Notepad is used.
2. Create a file for the control file. In the example, the name CTRL1.txt was used; however, any extension can be
used.
3. On the first line, type the mandatory PACKAGEFILE switch with the argument specifying the package file to be
composed.
4. Specify any additional switches you want to include in the control file, listing each on its own line.

WARNING: If you include double quotes ("") around a file name in a control file, the engine
issues errors in the message file, stating the specified file could not be found or
created.

5. Save the file.

Control Files and the System Key

The following sections describe several methods for specifying the system key.

CONTROLFILE Switch
You can call other control files from within a control file. This option is available to make key management
easier. For example, you can have a control file using only the KEY switch. When you need to change the key,
change it in this control file and then you can link all your control files to the KEY control file.

Production Environment 24
 Control Files

Inserting a Key in a Control File

If you are using a package file with an expired key, you must insert a valid key into the control file or the engine
does not compose the package file.
Insert the following switch in your control file:
-KEY=value
The value is the text string of your key. This value overrides the key in the package file. You can copy the key
characters from your Exstream key file (EKF) by double-clicking on the key which, in the Windows environment,
opens the key in a program of your choice. In other environments, you can open the file using your text editor.
When you run the engine with the control file the new key is used with the old package file.

Ensuring the Key Is a Match

When you copy this key into your control file it must be an exact match. To minimize visual copying errors on
Windows systems:
1. Open the key import file in Notepad.
2. Highlight the key information.
3. Copy the key.
4. Paste it into the control file.

z/OS and the System Key

In z/OS, you must use upper case characters. However, the system key must consist of the original mixed case
characters. For example:
Your key: XxxxXxXXXxxxxXXxXxXxXxxXXxxXXxxxXXxxxxXxXxxxXXXxxx
It must be specified exactly like this in the control file.
If you edit your z/OS control file on z/OS, the characters you enter for the key are converted to upper case. For
example:
-KEY=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
This is not a valid key, as the key must be mixed case.

TIP: On z/OS systems you can use the KEYPART switch to split a key string into multiple parts. It is
used for keys that are too large to fit on a single line of JCL. When the engine processes
multiple KEYPART switches, it combines the parts in the order supplied to form a single key
string.

NOTE: You can set the z/OS command CAPS OFF, to use a mixed case file. If you do not use this
command, all text is converted to upper case.

Production Environment 25
 Control Files

Control Files and z/OS

The following is an example of a z/OS control file used with dynamic images.
-OUTPUTFILE=DD:EXOUTPUT.
-PACKAGEFILE=DD:PACKAGE
-MESSAGEFILE=DD:EXMSGS
-REPORTFILE=DD:EXREPORT
-RUNMODE=PRODUCTION
-TRACKIN=DISABLE
-TRACKOUT=FILE
-REPORT=CUSTOMER
-ENGINEDSN=P390LOC
-IMPORTDIRECTORY= EXSTREAM.TIFF
-TESTMODE
This control file sets the import directory using the IMPORTDIRECTORY switch to EXSTREAM.TIFF.

NOTE: You must license the Dynamic content import module to use the IMPORTDIRECTORY engine
switch.

For more information on the engine switches used in this example, see the Engine Switches and Return
Codes guide.

Specifying the z/OS Name in the Control File

You can use a combination of a DD name and member name.
For example:
1. Set the DD to a PDS without specifying the member name. For example:
//TIFFIMPO DD DSN=P390A.EXSTREAM.TIFF,DISP=SHR
2. Set the DD as the IMPORTDIRECTORY name and use the original data file.
For example:
-IMPORTDIRECTORY= DD:TIFFIMPO

NOTE: The z/OS engine is distributed with a control file. It has a built-in DD name:
DD:TIFFIMPO(SOUTHERN)
This is a valid z/OS file name and can help you get started.

Production Environment 26
 Control Files

Using a Fully-qualified Name

To use a fully-qualified name, you must put single quotes around the entire name. If the full name is
MYHLQ.EXSTREAM.TIFF (member), you must put the first quote in the control file. For example:
-IMPORTDIRECTORY= 'MYHLQ.EXSTREAM.TIFF
The trailing quote must be in the data file:
C Robert Stevens 123456 9/25/2000 (ASCII1)
T ABC (SOUTHERN)' (ASCII1)'
T DEF (SOUTH)' (ASCII2)'

NOTE: z/OS automatically appends the user’s High Level Qualifier (HLQ) to the front of the data
set. You do not need to use fully-qualified name, because z/OS will automatically add the
current HLQ.

Using Rules to Specify a File Name

You can also build the entire name using a rule (including the leading and trailing quote), where needed. In this
case, you would not use the -IMPORTDIRECTORY switch at all. The following are options you can use to build
the file name. You can:
Š Get the name of the fully-qualified PDS from an Initialization file.
Š Get the member name only from the data file, no parentheses or quotes.
Š Build the fully-qualified name using a rule by adding the:
• Leading quote.
• Open parenthesis.
• Trailing parenthesis and quote.

Specifying Multiple Package Files

You can use multiple package files for an engine run.

Normal Mode with Output Sorting

In normal engine processing, or in step one for output sorting, all the packages for an application can be
specified in a list in the control file.
The application package file must be specified first. For example:
-packagefile=App_master.pub
-packagefile=4_4_2002__Doc.pub
-packagefile=New_Phase_4_Camp_and_docs.pub
-packagefile=One_changed_doc_and_one_new_doc.pub
You can also specify a text file containing the preceding list. For example:
-APP_PACKAGEFILES=MyPackageList.txt

Production Environment 27
 Control Files

Specifying Package Files in PostSort Mode

In PostSort mode, available with the High-volume delivery module only, package files can be specified in the
same manner, but if you are using the Application consolidator module to consolidate more than one appli-
cation, you must use one APP_PACKAGEFILES switch per application.

For more information on the APP_PACKAGEFILES engine switch used in this example, see the Engine
Switches and Return Codes guide.

NOTE: You can use the same sub-packages (campaign or document updates) in more than one
application when they are listed in each -APP_PACKAGEFILES file.

For example:
-APP_PACKAGEFILES=App_1_PackageFiles.txt
-APP_PACKAGEFILES= Second_App_PackageFiles.txt

Running the Engine with a Control File

The following instructions utilize the CONTROLFILE switch. The following steps assume you are working from the
HP Exstream executable’s directory. Both Windows and UNIX commands are explained below.
To run the engine using a control file:
1. At the command prompt, type one of the following commands to start the engine run:
• In Windows; the command is prodengine.
• In UNIX; the command is Engine.
2. Enter a space after the Engine or prodengine command.
3. After the space, type the CONTROLFILE command, to specify the location of the control file.
4. Press ENTER to start the engine run.

WARNING: If a package file contains features the key doesn’t authorize, you receive a message
indicating an unlicensed feature and the process stops.

Production Environment 28
Engine Reporting

System Generated Files

In addition to the output, you can also generate special files when the engine runs. You can generate message
files and report files. Both types of system generated files can be used to troubleshoot problems encountered
while running the engine.

Message Files
Message files show you all the messages the engine generates while processing the application.
There are four options available when you create a message file, located in the Message level drop-down list
on the Run the Engine dialog box. Each option controls how much detail is provided, relating to the severity
of the messages reported.

NOTE: These options can also be controlled by using the MESSAGEFILE and MESSAGELEVEL
engine switches.

The options available on the drop-down list are:

Š All (info, warning, and error)—All messages generated by the engine are reported. (This corresponds
with choosing I for MESSAGELEVEL.)
Š Warning and error—Only warning and error messages are reported in the message file. (This corresponds
with choosing W for MESSAGELEVEL.)
Š Error only—Only error messages are reported in the message file. (This corresponds with choosing E for
MESSAGELEVEL.)
Š None—No message file is generated.

Message File Customization (DBCS)

If you are using the DBCS version of HP Exstream, you may need to change the encoding of your engine
messages. To change the encoding, use the -MSGENCODE=encodeType engine switch.
Some common choices for encodeType are:

Š ASCII Š ISO88592 Š LATIN1

Š BIG5 Š JIPS Š LATIN2
Š EBCDIC Š JIS Š UTF16

NOTE: UTF16 is the default if no encoding is specified.

Production Environment 29
 Engine Reporting

Report Files
Report files show details about each object in the application.
There are four options available when you create a Report file, located in the Reporting level drop-down list
on the Run the Engine dialog box. Each option controls how much detail is provided, regarding the qualifi-
cation and inclusion of objects for each customer.

NOTE: This option can also be controlled by using the REPORTFILE and REPORT engine switches.

The reporting level options available are:

Š None—No report is generated. (This corresponds to choosing NONE for the REPORT engine switch.)
Š Selection summary—A basic summary selection for the entire application is generated. (This corresponds to
choosing SUMMARY for the REPORT engine switch.)
Š Customer selections—A basic summary of the selections made for each customer is generated. (This corre-
sponds to choosing CUSTOMER for the REPORT engine switch.)
Š Customer details—A detailed report about all objects for each customer is generated. (This corresponds to
choosing DETAIL for the REPORT engine switch.)

Selection Summary
The Selection summary engine report provides the least amount of data. It provides details at the appli-
cation level of objects selected for the run. The following example shows an engine report file with Selection
summary selected. In the following example the Customer driver file contains only one customer.
*******************************************************************
HP Exstream Version 4.5.301m
* Execution Begins: 3/24/2004 12:22:23
* Report File (15)
******************************************************************
Customers Processed: 1
Campaigns Selected: 0
Campaign Messages: 0
Other Messages: 0
Pages Processed: 1 (0 blank)
Sheets Produced: 1

Production Environment 30
 Engine Reporting

Customer Selections
The Customer selections option provides a minimal amount of detail, similar to the Selection summary,
only the selections are shown at a customer level, rather than an application level. The following example was
generated using the same application.
*******************************************************************
HP Exstream Version 5.5.21m
* Execution Begins: 9/13/2005 11:00:41
* Report File (15)
******************************************************************
******************************************************************
* Run Selections: 1:
******************************************************************
************** COMPOSED PAGE LIST ************************
**** COMPOSE INFO: Total pages: 1, Mktg: 0, Bus: 1, Inserts: 0, weight 0.150oz,
Language: English
Basic Automated 1, 1, 1 Front Page=Basic Table Papertype (8.5 x 11)
Weight ( 0.150 oz)
************** QUALIFICATION REPORT ************************
Qualified Document List (1):
1q, 1s Basic Automated (1 pages/messages)
1q, 1s Page (ordered): Basic Table

Customer Details
The Customer details option provides the most detail in the report files. This option generates information
about each object used for each customer. The following example report was generated using the same appli-
cation previously used. Note that there is only one customer for this run.
Each value of the variables used for the customer is reported, as well as the values at specific times throughout
the run. This is in addition to the qualification information already provided with lower levels of detail. This type
of detail is useful for troubleshooting variables to ensure they reset properly.
******************************************************************
* HP Exstream Version 5.5.21m
* Execution Begins: 9/13/2005 11:00:41
* Report File (15)
******************************************************************
******************************************************************
* Overview of File: Transactions
******************************************************************
* FORMAT: Record types
* The record types which have been mapped are:
* 0: (new customer)
* C: (new customer)
* T: (data record)
******************************************************************
******************************************************************
* Variable Information
******************************************************************
SYS_CustomerEffectiveDate Date System As-needed
SYS_LanguageCustomer String System Cus-
tomer(Don't Compute)
SYS_LocaleCustomer String System Cus-
tomer(Don't Compute)
SYS_CustInvalidDataLevel Integer System Post-cus-
tomer(Don't Compute)
CustomerName String File As-needed
CustomerAddress1 String File As-needed
CustomerAddress2 String File As-needed
CustomerAddress3 String File As-needed
ApprovedCard String File As-needed
ChargeTransactionDate Date () File As-needed
ChargeTransactionCity String () File As-needed

Production Environment 31
 Engine Reporting

ChargeTransactionDescription String () File As-needed

ChargeAmount__ Currency () File As-needed
StatementBeginBal Currency File As-needed
CreditCardNumber String () File As-needed
StatementTotal Currency Formula As-needed
****************************** Program Initialization
CustomerName ;
CustomerAddress1 ;
CustomerAddress2 ;
CustomerAddress3 ;
ApprovedCard ;
ChargeTransactionDate
ChargeTransactionCity
ChargeTransactionDescription
ChargeAmount__
StatementBeginBal $0.00;
CreditCardNumber
StatementTotal $0.00;
****************************** Customer: 1 : Customer Data Read
CustomerName Robert Stevens;
CustomerAddress1 100 Main Street;
CustomerAddress2 Apartment 104;
CustomerAddress3 Lexington, KY 40505;
ApprovedCard ITSA Card Platinum;
ChargeTransactionDate December 14, 2002; December
18, 2002; December 19, 2002; December 22, 2002; December 27, 2002;
ChargeTransactionCity Louisville, KY; Louisville,
KY; Louisville, KY; Louisville, KY; Louisville, KY;
ChargeTransactionDescription Outback Steakhouse; Yankee
Candle; Nordstrom's 33; Jiffy Lube; Kroger;
ChargeAmount__ $29.45; $84.76; $245.67;
$31.26; $52.25;
StatementBeginBal $0.00;
CreditCardNumber 7512 2145 4517 9813
StatementTotal $443.39;
******************************************************************
* Run Selections: 1:
******************************************************************
************** COMPOSED PAGE LIST ************************
**** COMPOSE INFO: Total pages: 1, Mktg: 0, Bus: 1, Inserts: 0, weight 0.150oz,
Language: English
Basic Automated 1, 1, 1 Front Page=Basic Table Papertype (8.5 x 11)
Weight ( 0.150 oz)
************** QUALIFICATION REPORT ************************
Qualified Document List (1):
1q, 1s Basic Automated (1 pages/messages)
1q, 1s Page (ordered): Basic Table
****************************** Customer: 1 : Customer Processed
CustomerName Robert Stevens;
CustomerAddress1 100 Main Street;
CustomerAddress2 Apartment 104;
CustomerAddress3 Lexington, KY 40505;
ApprovedCard ITSA Card Platinum;
ChargeTransactionDate December 14, 2002; December
18, 2002; December 19, 2002; December 22, 2002; December 27, 2002;
ChargeTransactionCity Louisville, KY; Louisville,
KY; Louisville, KY; Louisville, KY; Louisville, KY;
ChargeTransactionDescription Outback Steakhouse; Yankee
Candle; Nordstrom's 33; Jiffy Lube; Kroger;
ChargeAmount__ $29.45; $84.76; $245.67;
$31.26; $52.25;
StatementBeginBal $0.00;
CreditCardNumber 7512 2145 4517 9813
StatementTotal $443.39;
****************************** Program Completion
CustomerName Robert Stevens;

Production Environment 32
 Engine Reporting

CustomerAddress1 100 Main Street;

CustomerAddress2 Apartment 104;
CustomerAddress3 Lexington, KY 40505;
ApprovedCard ITSA Card Platinum;
ChargeTransactionDate December 14, 2002; December
18, 2002; December 19, 2002; December 22, 2002; December 27, 2002;
ChargeTransactionCity Louisville, KY; Louisville,
KY; Louisville, KY; Louisville, KY; Louisville, KY;
ChargeTransactionDescription Outback Steakhouse; Yankee
Candle; Nordstrom's 33; Jiffy Lube; Kroger;
ChargeAmount__ $29.45; $84.76; $245.67;
$31.26; $52.25;
StatementBeginBal $0.00;
CreditCardNumber 7512 2145 4517 9813
StatementTotal $443.39;

Production Environment 33
System Performance

Memory Management
The amount of memory available for processing varies based on your production platform and server set up.
Use the examples in the following table as a guideline to determine the maximum memory usage your
production platform can support.

Server maximum memory support

Server type example Memory available

Windows (64-bit) 4 GB
Windows (32-bit) 2 GB
Sun 3 GB
Linux (64-bit) 4 GB

WARNING: The table is a reference tool for troubleshooting memory management issues only. It is
not a guarantee of performance on all platforms and all configurations.

Memory usage may become an issue if you process large applications, such as those with long transaction
tables. The following sections describe how to better manage how much memory is used with three engine
switches: MEMORYSAVE, MEMORYCACHE, and CACHETABLE.

Release Memory with New Sections/Customers

You can use the MEMORYSAVE engine switch to reset memory at the start of each new section or customer.
Without this switch, the engine uses memory to store variables and composed pages at the largest variable. For
example, if one customer contains 600 pages in a document, the engine keeps the allocation for page memory
at this level, even if the next customer only requires a fraction of that amount.
With MEMORYSAVE, the engine releases the memory allocated to variables with each new section. This
dynamic approach to memory management may reduce the processing speed for the customer with the large
memory requirement but, overall, it eases memory requirements in most large runs, especially those with a large
number of transactions.
When you use MEMORYSAVE on the command line or in a control file, the engine waits to begin the reallo-
cation of memory until the run hits the threshold you set as a numeric value. This number represents a trans-
action count (an element count in a single array variable). Typically, the value is set to 20,000. This value refers
to the number of records read before writing to the file. This value can be changed, depending on the appli-
cation.

For more information on the MEMORYSAVE switch, see the Engine Switches and Return Codes guide.

Production Environment 34
 System Performance

Store Transaction Tables in Memory

If you have large transaction-based tables, use the MEMORYCACHE switch to save memory by writing table row
data to a temporary file you specify.

TIP: If you use both MEMORYCACHE and MEMORYSAVE, you may see a bigger improvement in
memory usage.

The engine writes all subsequent row data to a file instead of memory when the row count for any one table
exceeds one of the following conditions:
Š 250,000 (the CACHETABLE default and the value used if you do not use the CACHETABLE switch)
Š The number you specify with the CACHETABLE switch
When the engine reaches the end of the table, it sends the stored row data into the print stream along with
pagination, header/footer, and other page design information. The engine then resets the file so it is ready for
the next large table in the run. The engine uses additional files if it reaches the memory limit or if it encounters
read/write errors.

For more information on the MEMORYCACHE and CACHETABLE switches, see the Engine Switches and
Return Codes guide.

Improving z/OS Performance

The following are suggestions you can use to improve performance when running the engine in a z/OS
environment.

Production Environment 35
 System Performance

MEMORYCACHE
In a z/OS production run, the file you specify with the MEMORYCACHE switch must be an ESDS VSAM file. The
size of the file must accommodate row data for your largest customer. The VSAM cluster must be defined as
reusable prior to use (default is non-reusable).

NOTE: With extremely large tables, you can use multiple MEMORYCACHE entries with different file
names. The engine writes table row data to the next file in the list when the first file fills up.

Below are sections of sample code necessary to run an application using MEMORYCACHE. These are presented
in the order they must appear in the code.

MEMORYCACHE code samples

Description Location Sample

Define cluster Before the run engine //Define EXEC PGM=IDCAMS

command //SYSPRINT DD SYSOUTPUT=*
//*Define VSAM KSDS Dataset
DEFINE CLUSTER
(NAME(SVCS.TEST.KSDS) –
RECORDSIZE(32 32000) –
CYLINDERS(100 100) –
REUSE –
VOLUMES (XBIG01) –
NONINDEXED)
/*
Reference the JCL In the run engine //CACHING DD DSN=SVCS.TEST.KSDS,DISP=SHR
command
Control file Referenced by the -PACKAGEFILE=DD:EXPACKAG
sample JCL above -MESSAGEFILE=DD:EXMSGS
-REPORTFILE=DD:EXREPORT
-RUNMODE=PRODUCTION
-TRACKIN=DISABLE
-TRACKOUT=FILE
-REPORT=CUSTOMER
-MEMORYCACHE=’SVCS.TEST.KSDS’
*MEMORYCACHE=DD:CACHING
-CACHETABLE=3000
-MEMORYSAVE=5000

Queues and z/OS File Size

One consideration when you define queues that are dynamically created on z/OS is that you must specify the
estimated size for each dynamically created file.

Production Environment 36
 System Performance

Z/OS file size on queue properties

Algorithm Used to Set the z/OS File Size

The production environment uses the following method to convert the specified value to TRKS and CYLS.
Š If the z/OS file size is less than 1,200KB, use TRACKS and the primary amount is equal to the amount / 50.
Š Otherwise, use CYLINDERS and the primary amount is equal to the amount / 800.
Š Secondary storage is set to the primary / 3.
Š Disposition is (CATLG, CATLG).
Š Excess space is released (RLSE).
Š A model dataset is opened and closed to get the LRECL, BLKSIZE, RECFM, and VOLSER.

NOTE: The model dataset is specified by the production file. It is only used to get LRECL,
BLKSIZE, RECFM, and VOLSER to be used when allocating data sets dynamically.

Pre-Load Reference Files

Use the LOADREFFILE engine switch to pre-load reference files into VSAM in z/OS production. Using the
LOADREFFILE switch can reduce the CPU time needed to run applications on the mainframe. The
LOADREFFILE=filename switch on the z/OS engine places the engine in a run mode that only loads the
lookup files and then ends. The customer data files are not read and no output is created. The file name
specified is the name of the reference file to load. Use LOADREFFILE=ALL to pre-load all of the files.

NOTE: You can load VSAM files once and run multiple times.

Memory Use at Run Time

This is a technical discussion of z/OS-specific memory management.

Production Environment 37
 System Performance

C/C++ Memory Calls

The production environment uses following C/C++ standard memory calls:
Š new()
Š delete()
Š malloc()
Š realloc()
Š free()
The production environment uses most of the memory unless you tell it to free memory used for large runs. You
can control when to free memory using the MEMORYSAVE switch in the control file.

For more information on the MEMORYSAVE switch see the Engine Switches and Return Codes guide.

IBM Language Environment and Memory Usage

Since the production environment uses standard memory calls, the IBM Language Environment (LE) is used to
manage its stack and heaps. LE provides run-time options to control certain aspects of processing.
HP Exstream has no "memory looping;" it requests memory from LE. If you overload memory, problems can
occur in how LE uses extra CPU cycles to acquire it.

LE Reports
You can set LE to report on how it uses memory and to configure your JCL for better performance. Different
package files use memory differently, so before you move an application to production, you can run the LE
reports to configure memory usage optimally.
To generate a storage report and run-time options report for program ENGEXE, specify:
//GO1 EXEC PGM=ENGEXE,PARM='RPTSTG(ON),RPTOPTS(ON)/'
You can apply LE run-time options in the PARM argument step in your JCL. Anything before a forward slash (/)
is sent to LE as an option; anything after the slash is sent as an argument.
//[stepname] EXEC PGM=ENGEXE,
//PARM='[run-time options/][program parameters]'
For LE report memory configuration and usage reports (including tuning recommendations) use:
//[stepname] EXEC PGM=ENGEXE,
//PARM='RPTSTG(ON),RPTOPTS(ON)/-USECONTROL=YES'
RPTSTG(ON) shows the storage the application uses at run time. Use this report to help decide what values and
suboptions to indicate at run time.

NOTE: Because it increases run time, you generally only use RPTSTG(ON) to assist with
application development.

RPTOPTS(ON) shows the run-time options in effect during application run time.

LE Tuning Parameters
The main LE tuning parameters are ANYHEAP, HEAP, HEAPPOOLS, and STACK. HEAP and HEAPPOOLS are key
when tuning an application to improve memory usage and performance.

Production Environment 38
 System Performance

Anyheap
The ANYHEAP option controls the allocation of library heap storage not restricted to below the 16M line. This
option is always in effect. The IBM default is:
ANYHEAP(16K,8K,ANYWHERE,FREE)
Another example is:
ANYHEAP(640K,32K,ANY,FREE)

Heap
The HEAP option controls the allocation of initial and additional heaps and details how that storage is
managed. This option is always in effect. The default is:
HEAP(32K,32K,ANYWHERE,KEEP,8K,4K)
For smaller applications, the LE reports require setting the heap to:
//PARM='HEAP(5M,256K,ANY,FREE,8K,4K)/-USECONTROL=YES'
For larger applications, set the heap to:
//PARM='HEAP(15M,512K,ANY,FREE,8K,4K)/-USECONTROL=YES'
The following table shows the heap suboptions.

Heap suboptions
Value Function

init_size Establishes the minimum initial allocation of heap storage. Designate as n, nK, or nM
bytes of storage. The actual amount of allocated storage rounds up to the nearest
multiple of 8-bytes.
incr_size Establishes the minimum size of any subsequent increment to the heap storage.
Designate as n, nK, or nM bytes of storage. The actual amount of allocated storage
rounds up to the nearest multiple of 8-bytes.
ANYWHERE/ANY Allocates heap storage anywhere in storage. On systems that support bimodal
addressing, you can allocate storage above or below the 16M line. If no storage is
available above the line, storage is obtained below the line. On systems that do not
support bimodal addressing, LE ignores this option and allocates the heap storage
below 16M. The abbreviation for ANYWHERE is ANY.
BELOW Allocates heap storage below the 16M line in storage that is accessible to 24-bit
addressing. The BELOW suboption causes the HEAPPOOLS option to be ignored
because HEAPPOOLS can only run above the line.
KEEP Stipulates that storage allocated to HEAP increments is not released when the last of
the storage is freed.
FREE Stipulates that storage allocated to HEAP increments is released when the last of the
storage is freed. The FREE suboption has no impact on heap increments containing a
HEAPPOOLS cell pool.

Production Environment 39
 System Performance

Heap suboptions
Value Function

initsz24 Establishes the minimum initial size of the heap storage obtained below the 16M line
for applications running with ALL31(OFF) when these applications specify
ANYWHERE in the HEAP run-time option. Designate as n, nK, or nM number of bytes.
The amount of storage rounds up to the nearest multiple of 8-bytes. initsz24 applies to
the initial heap and other heaps created with the CEECRHP call not allocated strictly
below the 16M line.
incrsz24 Establishes the minimum size for any subsequent increment to the heap area obtained
below the 16M line for applications running with ALL31(OFF) when these
applications specify ANYWHERE in the HEAP run-time option. Designate as n, nK, or
nM number of bytes. The amount of storage rounds up to the nearest multiple of 8-
bytes. incrsz24 applies to the initial heap and other heaps created with the CEECRHP
call not allocated strictly below the 16M line.

Heappools
For C languages, LE has a faster heap manager called HEAPPOOLS. This causes faster runs but use slightly
more memory.
HEAPPOOLS(ON,8,10,32,10,128,10,256,10,1024,10,2048,10)
The HEAPPOOLS option controls an optional heap storage management algorithm (heap pools) and is used to
improve performance of multi-threaded C/C++ applications with high use of standard memory calls.
The following table describes the suboptions available for heap pools.

Heappools suboptions
Value Function

OFF Establishes that LE does not use the heap pool manager.
ON Establishes that LE uses the heap pool manager to manage heap storage requests
against the initial heap.
[cell size] The size of cells in a heap pool. The cell size must be a multiple of 8, up to 2048. Cell
sizes 1K and 2K are also allowed.
[percentage] Percentage of HEAP run-time option’s init_size value to be used as the size for the heap
pool and any extents. The percentage must be between 1 and 90.

Stack
Stack controls the allocation of the thread’s stack storage. The default is:
STACK(128K,128K,BELOW,KEEP)

NOTE: For more information on tuning LE, see Language Environment for OS/390 & VM -
Programming Guide SC28-1939 and Programming Reference SC28-1940, available from
IBM.

Production Environment 40
 System Performance

Running Multiple Instances of the Engine

To run multiple instances of the engine at the same time, whether in batch mode or real time, there are some
considerations:
Š Each instance must read from its own package file. In some cases, two engines using the same .pub file can cause
instability.
Š Make sure an instance does not write to the same report or output file as another. You can usually do this by using
the FILEMAP and VARSET switches.
Š If you are running in batch mode or if you are running the engine using the Real-time module without the
DDAMESSAGE=APPEND switch, make sure each instance will not try to write the message file to the same place.

Production Environment 41
Troubleshooting

Troubleshooting
This chapter contains recommended solutions to some common issues you may experience. If these recommen-
dations do not solve your problem, try running a debug file for your application. If the issue persists, you can
create a case in Software Support Online (SSO) at http://support.overview.hp.com.

I want to use an old .pub file, but I get a message stating the key is invalid.
If you don’t want to recreate an old .pub file, but your key has expired, you must update the key to run the
engine for the specified file. To run the engine for a package file with an expired key:
1. Add the KEY command to the engine control file.
2. Open the EKF file in a text editor and copy the key directly into the control file.
The engine should run without problems.

I receive this error when trying to run the engine:

-*-*- EXSTREAM ENGINE Version <Version> -*-*- Production Engine
The CPU ID found, <CPU ID>, is invalid. Engine Terminated.
Exstream execution completed.
return status = 12
This error occurs because the license key and the CPU ID do not match. You need to contact your Account
Manager or Customer Service to resolve the error.

I have created a package file, but the engine issues an error when I try to run.
Make sure you are using the same key for the design and production environments. The engine enforces the key.
If you create an application using a demonstration key, for example, but the engine key does not have all the
same features enabled, you receive a message indicating an unlicensed feature and stops processing. To fix the
problem, update the application and remove the unlicensed features or upgrade your engine key.

Why isn’t MEMORYCACHE working on z/OS?

The MEMORYCACHE switch does not cache z/OS drawlists containing embedded images. If embedded
images are encountered, memory caching is performed but caching of the drawlists is skipped and they are just
processed.

For more information on the MEMORYCACHE and MEMORYSAVE switches, see the Engine Switches and
Return Codes guide.

All other embedded objects can be cached as expected on z/OS. All embedded objects can be cached as
expected on all other platforms.

Production Environment 42
 Troubleshooting

How can you limit the resources (CPU/RAM) to a single process?

You cannot limit the resources the engine consumes. However, the engine switch, MEMORYSAVE, causes it to
use less virtual memory when the number of transactions for a single customer is greater than the number
specified.

What is the best configuration for CPUs in UNIX?

Run the engine and obtain the CPU time used for processing the application. For example, use the time
command. Divide the wall clock time by the CPU time, rounding down. That gives the number of engine
processes that can run without CPU contention.
For example, wall clock time 60 seconds, CPU time 40 seconds, 1 engine/CPU. So, to run 4 engines simulta-
neously in this situation, use 4 CPUs.

Why do I receive the error message, "./Engine: cannot execute binary file",
when I try to run the engine in UNIX?
This error occurs if you download the wrong engine for your production environment. For example, if you
download the Solaris engine to run on your AIX system, you can fix this problem by downloading the correct
engine.

Why do I receive a "No such file or directory" message when I try to run the
engine on a UNIX-based platform?
When running the engine on the UNIX-based platform, set the following environment variables before you run
the engine:

UNIX-based Operating Systems and Environment Variables

Operating System Environment Variable
Linux LD_LIBRARY_PATH
AIX LIBPATH
Solaris LD_LIBRARY_PATH
HP-UX SHLIB_PATH

For Solaris only, environment variables must contain the directory of libodbc.so and libodbcinst.so files.

TIP: If you have not set the environmental variables, you can add them to the profile file in the user’s
directory for anyone who runs the engine or Uptrack. Use the code <dir> for directory. For
example:
LD_LIBRARY_PATH=<dir>
export LD_LIBRARY_PATH

What is the best memory configuration?

In UNIX you can monitor an engine process with 'ps -eal' or ps -l -p PID of the engine' and note the maximum
memory used in the SZ column. Then:
1. Subtract the amount of memory used by the operating system from the total memory on the system.
2. Divide the engine memory into this number to get the maximum number of engines that can run in the current
system memory without contention.

Production Environment 43
 Troubleshooting

If we send a package file to our host (mainframe) that contains 40 fonts and
we run a data file through that only has one record and generates output that
only calls two fonts, are all 40 fonts sent to the output device or just the two
we need for the specific statement we are trying to create? The same question
applies to images.
It depends on the output driver you are creating and whether you are using the Dynamic Content Import
module. You can place all resources (all fonts, in this example) inline at the top of the print stream or place no
resources in the file. If the resources are not in the file, separate resource files are created and sent to the output
device or place them in resource libraries.
You can do the same for static images: all inline or previously created. For dynamic images, only the specific
images used for the pages produced are included.

Using AFP with VSE

VSE is an older IBM mainframe operating system. If you are sending an AFP file from a z/OS to a VSE system
to print, do not include overlays and fonts as inline resources in the print stream. This functionality is not
supported in VSE. To alleviate this potential problem:
1. Package for resources only. This creates the overlays and fonts as separate files.
2. Move these resources into the appropriate PSF libraries on VSE.
3. Package without resources for the production run.
4. Run the engine. This creates AFP without resources at the top.

Will a VSAM package file run slower than a regular package file?
Using a VSAM package file can reduce run time because it enables HP Exstream on z/OS to read application
objects such as documents, pages, and variables as they are required instead of reading the entire package file
into memory at the beginning of the run. You will see significant improvement if your application contains a very
large number of application objects, such as documents, and not all of them are accessed in every run.
Whether this approach will run slower or faster depends on:
Š Time spent reading the package file into memory—For small .pub files, there really isn't much to gain
from using this feature, since the loading of the package file is insignificant. You can get an indication of how
long HP Exstream is taking to read the package file into memory by comparing the SETUP time to the TOTAL
time in the Elapsed CPU time: section of the message file. If this ratio is really high, as in the example below,
consider using a VSAM package file. For example:
Elapsed CPU time: 248.05 sec SETUP 250.12 sec TOTAL
Š Percentage of documents accessed—If you run an application containing hundreds of documents in a
small run that produces only a few documents, you can see a large performance gain. The same .pub file in a
larger run that uses all objects decreases performance.
Š Contents of the package file—You gain performance benefits only if there is a higher ratio of application
objects (such as pages and messages) over Environment objects (such as fonts and outputs).
Š Tuning of VSAM datasets—Since z/OS defaults are based on obsolete disk technology (such as sectors,
cylinders, and tracks), you must tune the VSAM dataset to gain performance benefits on currently available
hardware.

Production Environment 44
 Troubleshooting

When I run my application through the engine, it stalls on a particular cus-

tomer.
The most likely cause is a problem with a rule or formula in the application. To resolve this problem, first create
an application report for all rules and formulas, and investigate the code for all loop and while statements.

For information on creating application reports, see the Creating Application Reports section of the Using
Applications chapter in the Applications, Documents, and Pages guide.

If the error is not obvious in the code:

1. Turn on the code trace for each formula and all variables in the application.
2. On the Run the Engine dialog box, select Debug and specify a name for the debug file.
3. In the Trace Logic section, select Rules and Formulas.
4. Run the engine to create the debug file.
If the cause of the problem is an infinite loop, your debug file quickly grows large.
5. When the engine stalls, terminate the engine run and view the debug file for the infinite loop.

For information on using code trace and debug, see the Built-In Troubleshooting Tools chapter in the
Troubleshooting guide.

Production Environment 45
Index

A L
Algorithm used to set the MVS file size ............37 License key and CPU ID ................................ 42
Anyheap .....................................................39 Limit the resources used by the engine ............ 43
AS/400
Portable Application Solutions Environment .12
Retrieving output .....................................14
M
Running the engine .................................13
Memory management ................................... 34
Special considerations .............................12
Best configuration .................................. 43
Transferring files .....................................13
MEMORYCACHE switch ......................... 36 , 42
Message File ............................................... 29
Message file customization ........................... 29
C Message file options .................................... 29
C/C++ Memory Calls ...................................38 MVS
Control File > see also z/OS
And the System Key ................................24 Dynamic images .................................... 21
Comments .............................................24 Dynamic Images, Example JCL ................. 22
Creation ................................................24 File size algorithm .................................. 37
Formatting .............................................23 LE tuning parameters ........................ 38–40
Multiple package files .............................27 Loading VSAM Package Files ................... 19
Normal Mode (Step One) ........................27 Using LE reports ..................................... 38
Specifying package files in PostSort mode ..28
Specifying the z/OS name .......................26
Types ....................................................23
N
z/OS, Using a fully-qualified name ...........27
Naming conventions
z/OS, Using rules to specify file ...............27
AS/400 ................................................ 12
Control file
UNIX .................................................... 10
And the command prompt ........................23
Windows ................................................ 8
CONTROLFILE switch ....................................24
z/OS ................................................... 15
CPU, best configuration ................................43

P
D
Package file transfer UNIX ............................ 10
DBCS
Package report ............................................ 29
Message file customization ......................29
Pre-load Reference files, VSAM ...................... 37
Dynamic content import ................................44

Q
H
qp2term ..................................................... 13
Heap .........................................................39
Queues and MVS File Size ............................ 36
Heappools ..................................................40

R
I
Reference files pre-load VSAM ....................... 37
IBM LE and memory usage ............................38
Release with new sections/customers .............. 34
Innovation Access Method .............................20
Invalid key error ..........................................42

Production Environment 46
 Index

Report Files .................................................30 V

Customer details .....................................31 VSAM Package speed .................................. 44
Customer selections .................................31
Selection summary ..................................30
Report files options .......................................30
Run the engine from a shell script, UNIX ..........11 W
Running the engine from AS/400 ...................13 Windows
Running the engine in batch mode ....................9 Batch mode ............................................. 9
Naming conventions ................................. 8
Package file transfer ................................. 8

S
Stack ..........................................................40
System generated files ..................................29 Z
System Settings ..............................................7 z/OS ......................................................... 15
> see also MVS
Batch Local Shared Resources .................. 21
BLSR ..................................................... 21
T Control files ........................................... 26
Transferring Package files Explain JCL commands ............................ 17
Windows ................................................8 IAM ..................................................... 20
Troubleshooting the Production Environment 42–44 Improving performance ........................... 35
Memory use in ....................................... 37
Naming conventions ............................... 15
U Package file transfer ............................... 15
UNIX Queues and file size ............................... 36
Naming conventions ...............................10 Sample JCL file used to run the engine ....... 16
Package file transfer ...............................10 SMB ..................................................... 21
Run the engine from Shell script ................11 Specifying file names in commands ........... 16
Run the engine from the shell prompt .........11 Specifying names in the control file ........... 26
Sample shell script ..................................11 System Managed Buffering ...................... 21
Using AFP images with VSE ...........................44 Using JCL files to run the engine ............... 16
Using HFS for file output ......................... 18–19 Using VSAM Package Files ...................... 20
VSAM tuning options ........................ 20–21

Production Environment 47