© 2007 IBM CorporationIBM Printing Systems
IBM OUTPUT ENVIRONMENTXDU 2007 March 07
o
Debugging AFP Tricks of the AFP Masters
Xplor Document UniversityHoward TuretzkyPrinting Systems Advanced Technical [email protected]
OUTPUT SOLUTIONS FOR AN ON DEMAND WORLD
2 IBM OUTPUT ENVIRONMENT
o
Debugging is a Process, Not a Tool
Printing errors are expensive! Quick diagnosis and correction of errors reduces cost
You will learn the process of identifying andcorrecting print file problems that IBM uses
You will use the tools that we use to diagnose andfix errors
You will see the documentation we reference tounderstand AFP Architecture
OUTPUT SOLUTIONS FOR AN ON DEMAND WORLD
3 IBM OUTPUT ENVIRONMENT
o
Get the Evidence
You can’t solve printing problems without informationGathering Problem Information
What are the symptoms?• Not printing• Printing incorrectly
– wrong font, missing images, wrong orientation, missing text…• Printing too slowly: printer clutches
Prove It!! Collect the evidence• Incorrect output
– Also sample of correct output (you can’t tell what’s wrong if you don’t knowwhat’s right)
• Error messages and logs
OUTPUT SOLUTIONS FOR AN ON DEMAND WORLD
4 IBM OUTPUT ENVIRONMENT
o
Getting Your Hands Dirty
If the problem and the solution are not obvious, then you willneed to examine the data and test it yourself1. Get the input file
– You may also need to know the file characteristics (record format, recordlength, carriage control type…)
2. Get the resources– You will need all the resources the job actually used– You may need to know the resource directory hierarchy to locate the
resources actually used– Eg., did it use the 240- or 300-pel resources or which copy of FORMDEF F1XXX
was really used
3. Get any job submission commands– Print JCL, pdpr command, ACIF parameters…
OUTPUT SOLUTIONS FOR AN ON DEMAND WORLD
5 IBM OUTPUT ENVIRONMENT
o
What Really Happened?
Users don’t always know exactly how their jobsprint, so Trust, but Verify
Now try to recreate the problem If you can’t reproduce the error you will have a hard time fixing
it You may need to have the user rerun it in his own
environment
OUTPUT SOLUTIONS FOR AN ON DEMAND WORLD
6 IBM OUTPUT ENVIRONMENT
o
Problem Analysis
Now that you have verified that a problem exists, you needto narrow down the possibilities Were there error messages?
• Messages usually print at the end of the job– If not, check any message logs– /var/pd/servername/error.log for Infoprint Manager– PSF SYSOUT and console for z/OS
• Look up the message. It may contain the explanation!• pdmsg msgnum• PSF or ACIF messages books•
OUTPUT SOLUTIONS FOR AN ON DEMAND WORLD
7 IBM OUTPUT ENVIRONMENT
o
Lab Exercise: Infoprint Manager Message Facility Click on the Management Console icon on the task bar, or from the
Start menu select IBM Infoprint Manager->Management Console On the Management Console menu, select Help->Message Help… On the Message Number pulldown, select 0420, then type 684 in
the box after the dash, and press OK.
OUTPUT SOLUTIONS FOR AN ON DEMAND WORLD
8 IBM OUTPUT ENVIRONMENT
o
Lab Exercise: Infoprint Manager Message Facility
OUTPUT SOLUTIONS FOR AN ON DEMAND WORLD
9 IBM OUTPUT ENVIRONMENT
o
The message text gives the cause of the problem:
and the solution
The font was a 240-pel font trying to print to a 300-pelprinter. Either change the printer’s resolution or use a300-pel font.
Problem Analysis
The font pattern resolution in bytes 24-27 of an FontControl (FNC) structured field must match the font patternresolution of the actual destination. This font characterset cannot be used on this actual destination.
Either change the font pattern resolution so that itmatches the actual destination's resolution or send theprint job to an actual destination that supports thecharacter set specified in the structured field.
OUTPUT SOLUTIONS FOR AN ON DEMAND WORLD
10 IBM OUTPUT ENVIRONMENT
o
Message Example
We have either the wrong data or the wrong PAGEDEF Look at the data for line 35, which will begin with ‘4’ The PAGEDEF or the DATA Map has no channel 4 Ask the user to verify that the correct PAGEDEF was used to print the job
PSF tells you:
APS346I DATA IN AN INPUT RECORD OR PAGEDEF RESOURCE IS NOT VALID:A SKIP TO A NONEXISTENT CHANNEL = 4 ON RECORD NUMBER =35 WAS DETECTED WITHIN THE LND STRUCTURED FIELDS.OUTPUT WAS FORCED TO SINGLE SPACING, WHICH MAY CAUSE BLANKPAGES.
OUTPUT SOLUTIONS FOR AN ON DEMAND WORLD
11 IBM OUTPUT ENVIRONMENT
o
Fixing Broken Print Jobs What kinds of errors can you fix?
If you need to print the job, right or wrong, you can repair many kinds of errors Missing resources
Identify all the missing resource If you can’t get them from the customer, substitute: Page Segments and Overlays
– Copy an existing resource and rename it with the name of the missing file» Make test segments/overlays» a square empty box to show position» blank to see what prints
• Fonts– Copy and rename an existing font– Look in the MCF and PTX (or the PAGEDEF’s MCF and Field) to see what context the font is
in, then try to substitute one about the same size and type» fixed-pitch for billing lines, for example, or typographic for paragraphs
OUTPUT SOLUTIONS FOR AN ON DEMAND WORLD
12 IBM OUTPUT ENVIRONMENT
o
Lab Exercise: Creating Substitute Resources On the Start menu, select Programs->Accessories->Paint Open the file {C:\AFP_Debug_lab\palm tree.gif}
Select Print from the File menu, then IBM AFP 300 Select the Advanced tab Select Output Type: Page Segment Select Image Options: Properties, check Color Options Black/White Push Print use the file name
{C:\AFP_Debug_lab\S1PALM.psg}
OUTPUT SOLUTIONS FOR AN ON DEMAND WORLD
13 IBM OUTPUT ENVIRONMENT
o
Handling AFP Errors
Datastream errors In resources, substitute the resource In the print file:
• Some errors can be fixed by hand-editing or writing a small program• Use a tool like the AFP Analyzer to identify the error• Use a hex editor to change the bytes
It’s not worth the effort to fix complex errors eg., you can fix a bad dimension in an OBD or OBP, but you can’t fix a bad
image raster pattern
OUTPUT SOLUTIONS FOR AN ON DEMAND WORLD
14 IBM OUTPUT ENVIRONMENT
o
Lab Exercise: AFP Analyzer and AFPDMP
In C:\AFP_Debug_lab, enter the command:afpdmp ansicc.afp
You can use the –d parameter to get more detail:afpdmp –d ansicc.afp
In C: \AFP_Debug_lab, enter the command:runafpan ansicc.afp ansicc.lst /LOG
then enter:notepad ansicc.lst
OUTPUT SOLUTIONS FOR AN ON DEMAND WORLD
15 IBM OUTPUT ENVIRONMENT
o
Analyzing AFP Two programs to make it easier to read AFP:
AFP dump (AIX, DOS/old Windows, new Windows version)• Structured field names,• Some values decoded• Schematic view of file
...1 NOP (No Operation) SFI 0033 D3EEEE 000001
...2 BDT (Begin Document) NAME AFPANLYZ SFI 0018 D3A8A8 000002
...3 - BPG (Begin Page) NAME i SFI 0015 D3A8AF 000001
...4 - - BAG (Begin Active Environ Group) NAME i SFI 0010 D3A8C9 000001
...5 - - - MCF1 (Map Coded Font 1) SFI 0044 D3B18A 000001
...6 - - - PGD (Page Descriptor) SFI 0016 D3A6AF 000002
...7 - - - CTC (Composed-Text Control) SFI 0012 D3A79B 000003
...8 - - - PTD1 (Presentation Text Descrip) SFI 0014 D3A69B 000004
...9 - - EAG (End Active Environ Group) NAME i SFI 0010 D3A9C9 000001
..10 - - BCT (Begin Composed-Text Block) NAME (blanks) SFI 0010 D3A89B 000002
..11 - - - PTX (Presentation Text Data) SFI 0111 D3EE9B 000001
..12 - - ECT (End Composed-Text Block) NAME (blanks) SFI 0010 D3A99B 000002
..13 - EPG (End Page) NAME i SFI 0010 D3A9AF 000001
OUTPUT SOLUTIONS FOR AN ON DEMAND WORLD
16 IBM OUTPUT ENVIRONMENT
o
Analyzing AFPAFP Analyzer
(MVS,VM, Windows, AIX)• Decodes everything• Large output
1:NOP:SCRIPT/VS 4.0.0: DEVICE PG1A CHARS X0N2200E2: BEGIN DOCUMENT :AFPANLYZ Coded Graphic Character SetGlobal Id: GCSGID 65535 CPGID 37 3: BEGIN PAGE :i Fully Qualified Name: ReplaceFirst GID Name: i (Hex) 89 4: BEGIN ACTIVE ENVIRONMENT GROUP :i 5:MCF:FONT_ID CODED_FONT CODE_PAGE CHAR_SET ROT 3 T1000395 C1H20000 2 T1000395 C1H400F0 6:PGD: X Units 2400 Y Units 2400 X Size 2040 Y Size2640 Page Size: 8.50 11.00 7:CTC:(CONSTANT):00000000000000002D00 8:PTD: X,Y Unit Base 10 in X,Y Units/Base: 2400 2400X,Y Text Block Size: 2,040 2,640 9: END ACTIVE ENVIRONMENT GROUP :i (Bytes: 166) 10: BEGIN PRESENTATION TEXT BLOCK : 11:PTX: (escape) STO: 000/090 AMB: 473 AMI: 240 SVI: 15
RMI: 622 SCFL: 2(T1000395 C1H400F0) TRN:( 35)>AFPANLYZ: Structured Field Analyser< AMB: 700 AMI: 240 SVI: 9 RMI: 1138 SCFL: 3(T1000395 C1H20000) TRN:( 27)>Document Number Version 9.0< AMB: 805 AMI: 240 RMI: 1393 TRN:( 14)>April 18, 2002< AMB: 936 AMI: 240 RMI: 1009 TRN:( 37)>Howard Turetzky, IBM Printing Systems< AMB: 1041 AMI: 240 RMI: 1163 TRN:( 26)>Boulder Programming Center< AMB: 1076 AMI: 240 RMI: 1274 TRN:( 18)>[email protected]< (unchained) NOP:( 0)>< 12: END PRESENTATION TEXT BLOCK : (Bytes: 308) 13: END PAGE :i (Bytes: 513)
OUTPUT SOLUTIONS FOR AN ON DEMAND WORLD
17 IBM OUTPUT ENVIRONMENT
o
Off-page and Invalid Character Errors Off-page condition is when anything is printed outside of the
printable area (as defined by the PGD XpgSize/YpgSize) Invalid characters are code points not defined in the current code
page for the font Most common is x’00’ This can be fixed by a code page that maps x’00’ to space
These errors can be masked (blocked) by the print server DATACK=BLOCK or DATACK=BLKPOS or DATACK=BLKCHAR Printer still does automatic recovery, which takes time if there are many errors
Many printers will indicate off-page errors with a PEM (Printer ErrorMark) Usually a black mark near the point that ran off the page Some use lines from the error point to the boundary (“star wars vectors”) A few will substitute a character such as ‘?’ for invalid characters
OUTPUT SOLUTIONS FOR AN ON DEMAND WORLD
18 IBM OUTPUT ENVIRONMENT
o
Lab Exercise: Invalid Characters
On the Start Menu, select Programs->AFPWorkbench for Windows->IBM AFPWorkbench Viewer
In the Open File Name box, type or navigatetoC: \AFP_Debug_lab \ansicc.afp
Click on the zoom icon in the toolbaror View->Zoom or Ctrl+Z, select 150%
On the Options menu, select Preferences,then set the Default Character to ‘?’ (Viewer 2.02 displays the Unicode invalid
character--narrow box)
Don’t see the palm tree? Options->Preferences->More Add path C: \AFP_Debug_lab; to Resources
OUTPUT SOLUTIONS FOR AN ON DEMAND WORLD
20 IBM OUTPUT ENVIRONMENT
o
How Errors are Detected Different components of the print system detect different types of errors
AFP errors are found by PSF, Infoprint Manager or ACIF Syntax errors:
• Badly-formed structured fields• Missing records: Begin/End
Missing resources Some parameter errors
• Missing or invalid triplets in Map repeating groups• Length errors, invalid or out-of-range logical units• Most FORMDEF problems
Line data and PAGEDEF errors are only detected by PSF or ACIF Missing or invalid carriage controls Wrong-length record
“0425-nnn DATA IN AN INPUT RECORD OR RESOURCE IS NOT VALID:…”
OUTPUT SOLUTIONS FOR AN ON DEMAND WORLD
21 IBM OUTPUT ENVIRONMENT
o
0425-415 cpgid=5000425-415 cc=yes0425-415 cctype=a0425-415 chars=GT10,GB10,GI12,LR120425-415 fileformat=record0425-415 formdef=F1A101100425-415 indexobj=none0425-415 inputdd=ansicc.host0425-415 mcf2ref=cf0425-415 outputdd=ansicc.afp0425-415 pagedef=P1STD10425-415 trc=yes0425-415 restype=none0425-415 userlib=.0425-346 DATA IN AN INPUT RECORD OR PAGEDEF RESOURCE IS INVALID: A SKIP TO A NONEXISTENT CHANNEL = 'F3'X ON RECORD NUMBER = 51 WAS DETECTED WITHIN THE LND STRUCTURED FIELDS. OUTPUT WAS FORCED TO SINGLE SPACING, WHICH MAY CAUSE BLANK PAGES.
0425-346 DATA IN AN INPUT RECORD OR PAGEDEF RESOURCE IS INVALID: A SKIP TO A NONEXISTENT CHANNEL = 'F2'X ON RECORD NUMBER = 79 WAS DETECTED WITHIN THE LND STRUCTURED FIELDS. OUTPUT WAS FORCED TO SINGLE SPACING, WHICH MAY CAUSE BLANK PAGES.
0425-105 THE ERROR REPORTED ABOVE OCCURRED IN LOGICAL RECORD NUMBER 51, WHOSE SEQUENCE NUMBER IS NOT AVAILABLE, AND RESOURCE NAME IS UNKNOWN.0425-441 ACIF AT PQ71172 HAS COMPLETED ABNORMALLY WITH RETURN CODE 4.
Optional Lab Exercise: Using ACIF to Find Errors Open a command window cd C:\AFP_Debug_lab Run ACIF:
acif parmdd=acif.parm
OUTPUT SOLUTIONS FOR AN ON DEMAND WORLD
22 IBM OUTPUT ENVIRONMENT
o
ACIF on z/OS//APKSMAIN EXEC PGM=APKACIF,REGION=0M//INPUT DD DSN=HOWARDT.SPF.DATA(ANSICC),DISP=SHR//SYSIN DD * CC = YES /* carriage control used */ CCTYPE = A /* CARRIAGE CONTROL TYPE */ CPGID = 500 /* code page identifier */ chars=GT10,GB10,GI12,LR12 FDEFLIB= SYS1.FDEFLIB FONTLIB= FONTS.FONTLIBB,FONTS.FONTLIBB.EXTRA FORMDEF = F1a10110 /* FORMDEF NAME */ INPUTDD= INPUT /* input file ddname */ INDEXOBJ = NONE mcf2ref=cf OUTPUTDD = OUTPUT /* output file ddname */ OVLYLIB= SYS1.OVERLIB PAGEDEF = P1STD1 /* PAGEDEF NAME */ RESFILE = seq /* resource file PDS or SEQuential */ RESOBJDD = RESLIB /* resource file ddname */ RESTYPE = all /* RESOURCE SELECTION */ USERLIB = HOWARDT.APK.PPFALIB
/*
OUTPUT SOLUTIONS FOR AN ON DEMAND WORLD
23 IBM OUTPUT ENVIRONMENT
o
ACIF on z/OS
//OUTPUT DD DSN=HOWARDT.REVTST.OUTPUT,// DISP=(NEW,CATLG),// SPACE=(32760,(5200,1500),RLSE),UNIT=SYSDA,// DCB=(LRECL=32756,BLKSIZE=32760,RECFM=VBM,DSORG=PS)//INDEX DD DSN=HOWARDT.REVTST.INDEX,DISP=(NEW,CATLG),// SPACE=(32760,(150,150),RLSE),UNIT=SYSDA,// DCB=(LRECL=32756,BLKSIZE=32760,RECFM=VB,DSORG=PS)//RESLIB DD DSN=HOWARDT.REVTST.RESLIB,DISP=(NEW,CATLG),// SPACE=(32760,(15,15),RLSE),UNIT=SYSDA,// DCB=(LRECL=32756,BLKSIZE=32760,RECFM=VBM,DSORG=PS)//SYSPRINT DD SYSOUT=*
OUTPUT SOLUTIONS FOR AN ON DEMAND WORLD
24 IBM OUTPUT ENVIRONMENT
o
Debugging With ACIF ACIF: AFP Conversion and Indexing Facility
Used to convert line data for Infoprint Manager Collects resources used in a job so print file and resources can be sent or
stored together ACIF uses the same code as PSF/zOS to validate AFP and to convert to line
data Can detect the same errors as PSF
For debugging, ACIF is useful to convert line data to AFP to helpsolve problems Find why data prints on the wrong page Explain objects not positioned correctly See where fields were mapped by the PAGEDEF Show how barcodes were created and positioned Identify missing resources Count pages
OUTPUT SOLUTIONS FOR AN ON DEMAND WORLD
25 IBM OUTPUT ENVIRONMENT
o
What the Server Doesn’t Know
Print servers cannot detect most content errors Off-page conditions Invalid text, graphics or image commands Most font details Print servers do not examine print data because of performance and
complexity Contents of PTX, IPD, IRD, GAD, BDA mostly sent to the printer
unchanged
OUTPUT SOLUTIONS FOR AN ON DEMAND WORLD
26 IBM OUTPUT ENVIRONMENT
o
What the Printer Knows
As the printer builds an image of the page in memory, itdetects any problems with data content Off-page, invalid character, all font metric problems Invalid text controls, GOCA drawing orders, IOCA SDFs
Each error (exception) is reported back to the print server Exceptions are sent from the printer to the server in a NACK (negative
acknowledgement) Can be synchronous (in response to a command) or asynchronous The print server uses this information to control recovery
OUTPUT SOLUTIONS FOR AN ON DEMAND WORLD
28 IBM OUTPUT ENVIRONMENT
o
How to Make Sense of Sense DataIPDS error-code registry for printers(310) Hardware sense data (link level)
24 bytes of error or situation information Device specific Action codes: X’00’, X’02’-X’04’, X’07’, X’0B’, X’0F’-X’14’, X’18’, X’1C’, X’24’, X’25’, X’4D’ Look in IPDS Technical Reference for a specific printer
(553) IPDS Negative Acknowledgements Look in IPDS Reference Some hardware sense data is converted into a NACK by host software
(176) Special object-error codes (PostScript, PDF,TrueType)
OUTPUT SOLUTIONS FOR AN ON DEMAND WORLD
29 IBM OUTPUT ENVIRONMENT
o
Layout of an IPDS NACK
OUTPUT SOLUTIONS FOR AN ON DEMAND WORLD
30 IBM OUTPUT ENVIRONMENT
o
Places to Look (a peek into Dave’s office)www.printers.ibm.com/manuals IPDS Reference
Error code registry How the printer/host connection is supposed to work Sense Type & Model, Obtain Printer Characteristics
IPDS Technical References (AFCCU, non-AFCCU, hardware publications)
Printer Information Manual Software books
MO:DCA Architecture books Programming and Line Data Reference Product and messages manuals
OUTPUT SOLUTIONS FOR AN ON DEMAND WORLD
31 IBM OUTPUT ENVIRONMENT
o
Other Tools Debugging Tools
Traces: PSF and Infoprint Manager can trace data and actions
• Useful for Service to diagnose problems with the software• Not so useful for print datastream errors
Printer traces• Only useful for printer problems or severe performance problems• Will be directed by Service and CE• Not helpful for print datastream errors
OUTPUT SOLUTIONS FOR AN ON DEMAND WORLD
32 IBM OUTPUT ENVIRONMENT
o
The Real Debugging Secrets
Analysis and experience are the main tools we use With much reading of manuals Using the tools we’ve seen Changing and fixing what we can Then testing until it works
…and when all else fails, call m
OUTPUT SOLUTIONS FOR AN ON DEMAND WORLD
33 IBM OUTPUT ENVIRONMENT
o
Questions?