Processing PDF files on mainframe CONTROL-D

General Information

This procedure deals with the setup involved to process PDF files on the mainframe
CONTROL-D. The procedure is divided into several sections – reference only the sections you
need for your implementation.

Section 1: Transferring PDF files from Windows/Unix to CONTROL-D CDAM

In many cases, the PDF files will be created on a distributed systems server, and
they need to be sent to the mainframe as the first part of processing.

Method 1 describes the use of the CONTROL-D/Agent on Windows/Unix to

transfer the file, through the File Transfer Option (FTO), directly into CDAM
datasets on the mainframe. This method is generally the preferred means to
convey the data to the mainframe, and it affords a completely automated path for
processing these PDF files.

Method 2 describes the use of conventional FTP and a copy job to store the
PDF in a CDAM file. There is no inherent automation in this method, but it may
be suitable for use in some environments.

There are a number of important advantages inherent in Method 1. These

include:

● Space needs are automatically accommodated – no “out of space” errors

part way through the transfer
● Fully automated path from file detection to report viewing
● Duplicate datasets will not be created (each CDAM file has a unique
name)
● No external job is required

Section 2: Decollation of PDF reports with CONTROL-D

PDF reports are processed in the same way as AFP and Xerox reports in
CONTROL-D v 6.1.xx and higher. The procedure will go over the specific steps
to implement a decollation mission for a PDF file.

Product release level requirements

CONTROL-D with Page On Demand version 6.1.09

CONTROL-D/Agent components version 2.x or higher – version 3.5.00 preferred
Section 1: Transferring PDF files from Windows/Unix to CONTROL-D CDAM
Method 1: CONTROL-D/Agent and File Transfer Option

Initial setup on server

Prior to transferring PDF files, the CONTROL-D/Agent components need to be installed

on the Windows or Unix server. The CONTROL-D/Agent is made up of an Automate
Process (which detects specific files in “watched” directories) and a Session Agent
executable (which actually moves the data).

For CONTROL-D/DS versions 3.1.xx and higher, the Automate Process and Session
Manager should be installed. (The Session Agent executable is installed when the
Session Manager is installed.) Note that the Session Agent executable can also be run
from a script or as a scheduled command (in CONTROL-M), if it is not necessary to
automatically trigger off the appearance of a file.

Step 1: Create an automate directory rule if desired to detect a file created by the PC
application based on a specific name or pattern mask. The automate rule should issue the
session agent command (see below).

Step 2: Execute a session agent command to send the report to the mainframe FTO. This
command will work with any version of sesagent, just make sure that the name of the executable
is correct. For example, this command will send a PDF to the CMB3 mainframe:

bmc-ctd-sesagent -o=put -h=cmb3 -p=3132 -d=NLCU/NLCU1/// -u -f="D:\NLCU.pdf"

If you will use an automate rule to execute this command when a file appears in a
directory, the automate rule should issue the sesagent command with the variable
%%FilePath in place of the file name:

bmc-ctd-sesagent -o=put -h=cmb3 -p=3132 -d=NLCU/NLCU1/// -u -f="%%FilePath"

The parameters shown in this command are:

-o=put : "Put" the file onto the mainframe

-h=cmb3 : The name of the host computer
-p=3132 : The port for the FTO address space (see more below)
-d=NLCU/NLCU1/// : The data for FTO to understand what to do with the file (see more
below). There must be 4 slashes ( / ) in this parameter.
-u : Send data uncompressed (very important for proper processing)
-f="D:\NLCU.pdf" : The name of the PDF file

Initial setup on mainframe

Prior to running a sesagent command to send a file to the mainframe, the File Transfer
Option (FTO) needs to be installed and configured. FTO can be installed for any
customer who has CONTROL-D Page On Demand licensed.

During the IOAGATE installation (IOA installation step 20), various application servers
are configured to work with the gateway. The FTO application server is a server type of
“F” and is a “MC” (multi-channel) application server.

The FTO application server needs two TCP/IP ports. A good rule of thumb is to assign
the pair of ports that is two numbers higher than the ones specified for Page On Demand.
 For example, if the port for POD is 3130, then FTO should be port 3132. The FTO
application server STC will use the two ports 3132 and 3133.

To verify that you have successfully added the FTO server, check in the IOA PARM
library member ECAPARMx, after you exit from IOAICE. You should see two sections in
this parm member related to this change – they will look similar this these examples:

Communication Channels declarations

CHANNEL ID=F1,
MODEL=MC,
PROTOCOL=TCP,
PORT=3132,
CHANNEL=ENABLE

Applications Server declarations

APSERVER APPL=(F),
CHANID=F1,
PROCNAME=L$CTDFTO,
SERVER=ENABLE

Step 3: Create FTOPARM member. This PDS member in the CTD FTOPARM library lets the
session agent command tell CONTROL-D how to handle the PDF file. In the "-d" parameter of
sesagent, there are four values - each one must end with a slash "/", even if the value is null or
blank.

The order of the values is:

FTOPARM member name / FTOPARM member section / jobname / job number /

For example, the FTOPARM member on the mainframe may look like this:

EDIT IOACMB3.CTD.V6100O.FTOPARM(NLCU) - 01.08 Columns 00001 00072

Command ===> Scroll ===> CSR
****** ***************************** Top of Data ******************************
000100 +++NLCU1
000200 TYPE=B
000300 OUT=CDAM
000400 LINESEP=NONE
000500 PAGESEP=NONE
000600 FIRSTLINE=NONE
000700 PREFIX=MWCD.V1
000800 ASSOC=PDF
000900 JOBNAME=NLCU1
001000 RECFM=VB
001100 LRECL=300
001200 BLKSIZE=304
001300 DECMIS='* IOACMB3.CTD.V6100O.REPORTS NLCU1 PROD FORCE'
****** **************************** Bottom of Data ****************************
Sample FTOPARM member for PDF file

In the session agent command, the “-d” parameter values from the example
(-d=NLCU/NLCU1///) have this meaning:

● NLCU/ : Use the member of FTOPARM(NLCU) to determine how to process the

incoming file
● NLCU1/ : Use the section of FTOPARM(NLCU) that matches +++NLCU1 to
determine how to process the incoming file. There may be several sections in this
 single member – each one begins with +++. The first section that matches exactly or
by a wildcard (for example, +++NL*) will determine how the output is processed.
● / : No jobname is being specified by the session agent command
● / : No job number is being specified by the session agent command

Note: If a jobname or job number was specified in the command, these will appear in the
CDAM file and $SYSDATA records. They are not required, and they can optionally be
supplied in the FTOPARM member as well.

For PDF reports, you should use the values listed in the FTOPARM member above for
TYPE, OUT, LINESEP, PAGESEP, FIRSTLINE, ASSOC, RECFM, LRECL, and
BLKSIZE. They work.

There are three parameters that you should adjust as needed:

● PREFIX : This is the CDAM dataset prefix for the file that will be created, containing
the PDF. Each site should follow their normal conventions for this value; as with all
CDAM prefixes, this must be seven characters or less.
● JOBNAME : This will often be useful to differentiate reports for future access, and
also helps to guarantee that your report mission will read the correct CDAM.
● DECMIS : This line is in the format of the REPLIST member of CTD PARM, and tells
FTO to force a specific category of a specific mission from a specific decollation
mission library when this report is stored in CDAM.

Note: The DECMIS string does not guarantee that this decollation mission will process
this specific file transfer. It will force a specific decollation mission into the AMF; the
decollation mission must be coded correctly to pick up the specific CDAM file created by
this FTOPARM member.

End of Method 1

Method 2: FTP and Copy to CDAM

Step 1: Execute FTP to mainframe.

There are a variety of FTP methods and tools. To do a native FTP of a PDF file to the
mainframe, go to a DOS prompt or Unix shell prompt and issue the commands in
black (with modification for your local files and environment). Do not enter the
comments in green.

>ftp cmb3
cmb3 should be replaced by your mainframe hostname or IP address.
Supply your mainframe user ID and password when prompted.

>binary
This ensures that your files are sent as data or “image” instead of being
translated to the mainframe EBCDIC character set.

>quote SITE LRECL=300 BLKSIZE=304 RECFM=VB

 The “quote SITE” commands set the mainframe dataset characteristics for all file
transfers that follow during this FTP session, unless you issue another SITE
command.

If you do not indicate the space allocation on the SITE command, you will
generally get the default TSO allocation set up for your mainframe. If you
anticipate the files are large, you should add the space allocation amounts to the
SITE command.

An example of this command with space parameters is:

quote SITE LRECL=300 BLKSIZE=304 RECFM=VB CY PRI=20 SEC=10

The PRImary and SECondary allocation amounts are in the unit type CYlinders,
TRacks, or BLocks.

>put “D:\NLCU.pdf” ‘RDWEXE.NLCU.PDF’

The first value generally specified in double quotes ( “” ) is the PC file name.
The second value, generally specified in single quotes ( ‘’ ) is the mainframe
dataset name.

>quit
After one or more put statements, type quit to exit FTP

Step 2: Run IEBGENER job to copy the uploaded file to CDAM.

You will need the CDAM subsystem name for this installation of CONTROL-D. This is
found in the IOA PARM library member CTDPARM as the value of AMNAME. If this
value is blank, the subsystem name will be the value of SSNAME in the IOAPARM
member of the same library.

Run IEBGENER in a batch job to create the CDAM dataset. In the example below, the
subsystem name for CDAM is I610.

//RDWEXEX1 JOB (FS,BMC),'ERIK E',NOTIFY=RDWEXE,

// CLASS=A,MSGCLASS=X,MSGLEVEL=(1,1),REGION=0M
//STEP1 EXEC PGM=IEBGENER
//SYSUT1 DD DISP=SHR,DSN=RDWEXE.NLCU.PDF
//SYSPRINT DD SYSOUT=*
//SYSUT2 DD SUBSYS=(I610,'PREFIX=MWCD.V1')
//SYSIN DD DUMMY

After running this job, you will have the PDF file in CDAM dataset that is the same as
from Method 1.

End of Method 2
Section 2: Decollation of PDF reports with CONTROL-D
The following steps outline the procedure to decollate a PDF report. Not all steps may be needed
for each report. Steps marked as initial setup can be done for each report, but usually they are
done one time for many different reports. You will need to evaluate your own usage to determine
how these steps are implemented.

These are the steps to set up a new PDF report for decollation.

1. Create OS/390 Resource Library List section in CTD PARM member $$TRNRES
2. Create a report clique for PDF reports using this Resource Library List
3. Create a decollation mission for your CDAM dataset with GROUP COLUMNIZED and
test
4. Create the final decollation mission for production use and test

Step 1: [Initial setup] Create OS/390 Resource Library List section in CTD PARM member
$$TRNRES

The $$TRNRES member of CTDPARM contains Resource Library Lists. A Resource

Library List consists of a name of the list, target resource library to store report
resources in (can share between AFP, Xerox, and PDF), and one or more source
resource libraries.

The most specifically named Resource Library Lists should go near the top of the
$$TRNRES member. The least specific and generic Resource Library Lists should go
toward the bottom. All list names begin with +++.

+++NLCU1
RESLIB=RDWEXE.CTD.RESLIB
XRX,RESLIB=RDWEXE.XEROX.RESOURCE
XRX,CTDLIB=IOACMB3.IOA.V6100I.SAMPREPS

In this example, the Resource Library List is named NLCU1. The target resource library
is RDWEXE.CTD.RESLIB. There are two source libraries – RDWEXE.XEROX.RESOURCE
and IOACMB3.IOA.V6100I.SAMPREPS.

PDF files contain all of their resources internally, but it is recommended to supply at least
one source resource library – the SAMPREPS library. This is used for various
transformation defaults members.

If you need to create a new target resource PDS library, allocate it with a larger than
typical number of directory blocks. It should be a RECFM=FB dataset; LRECL=80 works
very well, but any reasonable LRECL value that is at least 80 should be fine.

Step 2: [Initial setup] Create a report clique

The report clique is a set of attributes that tell CONTROL-D how to evaluate and
ultimately transform or reassemble the pieces of a decollated report.

● Go into option DO, select option 1, and press <enter> twice (until you get to the
full list of cliques on your system).
● Type NEW on the command line and press <enter>. Select clique type of PDF
when prompted.
 ● On the clique, enter the Resource Library List name you created above – for
example, NLCU1.

--------------- CONTROL-D REPORT CLIQUE FORMAT PDF

COMMAND ===>
----- Property ----------------- ----- Value ---------- (Edit)
1. General Parameters
Owner of Report Clique = RDWEXE
Page Width In Inches = 0
Page Height In Inches = 0
OS390 Resource Library List Name = NLCU1
3. Row Col Parameters
Number of Rows = 150
Number of Columns = 150
Text 0 Degrees = Y (Y/N)
Text 90 Degrees = Y (Y/N)
Text 180 Degrees = Y (Y/N)
Text 270 Degrees = Y (Y/N)
Fonts To Ignore =
Include External Overlays = Y (Y/N)
Include Internal Overlays = Y (Y/N)

● The “Row Col Parameters” are important to how CONTROL-D interprets the
location of text on the report pages. If your PDF has very “dense” text – that is, a
small font with more than 150 characters on a line, raise the number of ROWS
and COLUMNS. These values should be slightly more than the estimated “most
characters” on a line with the smallest “useful” font in the report. The default 150
by 150 frequently works for all reports being processed – it is always a good
place to start.

Note: Never change the Rows / Columns in an existing clique, unless you also
plan to change all report decollation missions that use this clique. Otherwise, the
definitions that use this clique will not find report value in the correct locations on
the page.

● Exit the clique definition by PF03. When prompted for a name, name your clique
something useful – maybe the same as the Resource Library List – NCLU1.

Step 3: Create a decollation definition with group COLUMNIZE

PDF files, like AFP and Xerox reports, can contain multiple fonts of varying sizes. The
text may all be written in the same orientation, but might instead by in several orientations
within the same report. (For example, a customer invoice might additionally have the
customer’s address printed upside-down, so that it appears in a mailing envelope the
proper way, when the invoice is folded.)

Internally, CONTROL-D extracts this text and determines its location on a “virtual page”
that is 150 rows by 150 columns (or another size, depending on the Row/Column value in
your clique). Any report splitting by the contents of the page, and any DO INDEX, DO
NAME *, or other statements that extract data from the report page as based on this
virtual page of text.

In order to write a decollation mission for a PDF report, you need to see this virtual page.
Normally, this exists internally in memory during decollation. However, you can process
the report to “columnized data” for testing, which shows you each of the virtual pages.
To do this, you create a definition with a GROUP of COLUMNIZED. Create a new report
definition and type SCHED on the command line to be able to access the GROUP field
(see example below).

----- CONTROL-D/V CATEGORY TEST-FTO JOB NLCU1 ----------- (R.S)

COMMAND ===> SCROLL===> CRSR
+-----------------------------------------------------------------------------+
| CATEGORY TEST-FTO JOBNAME NLCU1 GENERIC MONITOR |
| OWNER RDWEXE TASKTYPE REP GROUP COLUMNIZED JOBID |
| DESC DEC OF PDF SENT BY FTO |
| DESC |
| =========================================================================== |
| DAYS DCAL |
| AND/OR |
| WDAYS WCAL |
| MONTHS 1- Y 2- Y 3- Y 4- Y 5- Y 6- Y 7- Y 8- Y 9- Y 10- Y 11- Y 12- Y |
| DATES |
| CONFCAL SHIFT RETRO N MAXWAIT 00 |
| MINIMUM PDS |
| =========================================================================== |
| IN |
| WHEN IN QUEUE N CLS TIME FROM UNTIL INTERVAL PRIORITY |
| DSN |
| =========================================================================== |
| OUT |
| SHOUT WHEN TO URG |
| MSG |
| =========================================================================== |
| DEF COPIES 00 LVL USER LIVPOOL1 DEST MAX COPIES 01 |
| =========================================================================== |
| ON TRNDSN = PREFIX=MWCD.V1 ASSOC=PDF JOBNAME=NLCU1, |
| LAST=YES |
| CLIQUE = NLCU1 |
| PRT COPIES LVL USER DEST MAX COPIES |
| PRINT/CDAM PARMS = |
| DO |
| WHEN LINE - COL - PRINT REF NXT CT AND/OR |
| STRING = |
| DO USER = LIVPOOL2 LVL LINE COL - |
| S A T SYNONYM = CONCAT = |
| DO NAME = COLUMIZED NLCU PDF LINE COL - |
| DO |

The “columnized” decollation definition should be very basic. In addition to the GROUP
COLUMINZED, make sure that:

● WHEN IN QUEUE is “N”, meaning that the report is already in a CDAM file and
not on spool.

● Use ON TRNDSN, a special variation of the ON DSN that invokes the internal
transformation logic. There is only one extra field – the clique name that you
created in Step 2. The CDAM parms, such as PREFIX, ASSOC, and JOBNAME
should match the values in your FTO PARM or IEBGENER JCL. LAST=YES
makes sure that you only attempt to decollate the last CDAM that was uploaded.

Force this definition, and look for it to finish successfully. Then go to U.2 and locate the
report delivered to the recipient in the DO USER statement. View this text report – the
columnized data.
Step 4: Create a production decollation definition

User the data in the columnized view to determine where index values are or where other
report text strings are to be found. Below is a comparison of the native PDF version and
columnized version of a report.

PDF version of report

--------- CONTROL-D/V REPORT VIEWING NOTES 0 PAGE 1 OF

COMMAND ===> SCROLL ==
UR LIVPOOL2 RP COLUMIZED NLCU PDF JB NLCU1 0000582 DT 120803 RUL
----+----1----+----2----+----3----+----4----+----5----+----6----+----7---
---- Orientation=000 ---- ---- Orientation=000 ---- ---- Orientation=000
00026: Northern Lights Credit Union
00031: Northern Lights Credit Union
00033: 2209 North Junction Rd. E.
00036: Yellowknife, NWT X1A 2L9
00038: (867) 555-0222
00044:
00046:
00048:
00058: This month, Northern Lights is featuring a 3.2
00060: Start your savings by 28 February 2002, and we
00068: Statement date 15/01/2002
00070: Account 002-9388
00072: Beginning balance $101.09
00075: Ending balance $160.06
Columnized version of report

You will write the decollation mission from the text report, just as if it were any other text
report, with one exception. Although the column numbers should be based on the top
ruler on the screen (columns 1-80 and beyond), the row numbers should be the five digit
number at the beginning of each line of text.
For example, to index by account number in the report above, the index will be in
columns 48-55 (based on the ruler line shown in blue). The row will be 00070, as
highlighted in green. Make sure that you see all five digits of the row number on each
line; if you see only four, type SHOWCC on the command line.

For the final definition, remove the group COLUMNIZED. The definition, including the
index section, (after SCHED is turned off again) will look like this:

----- CONTROL-D/V CATEGORY PROD JOB NLCU1 ----------- (R.S)

COMMAND ===> SCROLL===> CRSR
+-----------------------------------------------------------------------------+
| CATEGORY PROD JOBNAME NLCU1 GENERIC MONITOR |
| =========================================================================== |
| DEF COPIES 00 LVL USER LIVPOOL1 DEST MAX COPIES 01 |
| =========================================================================== |
| ON TRNDSN = PREFIX=MWCD.V1 ASSOC=PDF JOBNAME=NLCU1, |
| LAST=YES |
| CLIQUE = NLCU1 |
| PRT COPIES LVL USER DEST MAX COPIES |
| PRINT/CDAM PARMS = |
| DO |
| WHEN LINE - COL - PRINT REF NXT CT AND/OR |
| STRING = |
| DO USER = LIVPOOL2 LVL LINE COL - |
| S A T SYNONYM = CONCAT = |
| DO NAME = PDF NLCU STATEMENTS LINE COL - |
| DO INDEX = ACCOUNT R G LINE 00070 COL 00048 - 00055 |
| MASK = RC N LINE - COL - |
| SUBINDX = LVL LINE COL - |
| MASK = RC LINE - COL - |
| =========================================================================== |
| INDEX LEVEL DISPLAY |
| ACCOUNT |
| =========================================================================== |

When you run this decollation mission, the result should be a decollated PDF report. It
can be split to multiple recipients or indexed for quick access to a specific section.