o

Debugging AFP Tricks of the AFP Masters

Xplor Document University Howard Turetzky Printing Systems Advanced Technical Support howardt@us.ibm.com
IBM OUTPUT ENVIRONMENT
XDU 2007 March 07 2007 IBM Corporation IBM Printing Systems

OUTPUT SOLUTIONS FOR AN ON DEMAND WORLD

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 and correcting print file problems that IBM uses !You will use the tools that we use to diagnose and fix errors !You will see the documentation we reference to understand AFP Architecture
2

IBM OUTPUT ENVIRONMENT

OUTPUT SOLUTIONS FOR AN ON DEMAND WORLD

Get the Evidence

! You cant solve printing problems without information ! Gathering 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 cant tell whats wrong if you dont know whats right)

Error messages and logs

IBM OUTPUT ENVIRONMENT

OUTPUT SOLUTIONS FOR AN ON DEMAND WORLD

Getting Your Hands Dirty

! If the problem and the solution are not obvious, then you will need to examine the data and test it yourself
1. Get the input file
You may also need to know the file characteristics (record format, record length, 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

IBM OUTPUT ENVIRONMENT

OUTPUT SOLUTIONS FOR AN ON DEMAND WORLD

What Really Happened?

!Users dont always know exactly how their jobs print, so Trust, but Verify !Now try to recreate the problem
" If you cant reproduce the error you will have a hard time fixing it " You may need to have the user rerun it in his own environment

IBM OUTPUT ENVIRONMENT

OUTPUT SOLUTIONS FOR AN ON DEMAND WORLD

Problem Analysis
! Now that you have verified that a problem exists, you need to 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

IBM OUTPUT ENVIRONMENT

OUTPUT SOLUTIONS FOR AN ON DEMAND WORLD

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.

IBM OUTPUT ENVIRONMENT

OUTPUT SOLUTIONS FOR AN ON DEMAND WORLD

Lab Exercise: Infoprint Manager Message Facility

IBM OUTPUT ENVIRONMENT

OUTPUT SOLUTIONS FOR AN ON DEMAND WORLD

Problem Analysis
! The message text gives the cause of the problem:
The font pattern resolution in bytes 24-27 of an Font Control (FNC) structured field must match the font pattern resolution of the actual destination. This font character set cannot be used on this actual destination.

! and the solution

Either change the font pattern resolution so that it matches the actual destination's resolution or send the print job to an actual destination that supports the character set specified in the structured field.

! The font was a 240-pel font trying to print to a 300-pel printer. Either change the printers resolution or use a 300-pel font.

IBM OUTPUT ENVIRONMENT

OUTPUT SOLUTIONS FOR AN ON DEMAND WORLD

Message Example
"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 BLANK PAGES.

! 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

10

IBM OUTPUT ENVIRONMENT

OUTPUT SOLUTIONS FOR AN ON DEMAND WORLD

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 cant 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 PAGEDEFs MCF and Field) to see what context the font is in, then try to substitute one about the same size and type

xed-pitch for billing lines, for example, or typographic for paragraphs

11

IBM OUTPUT ENVIRONMENT

OUTPUT SOLUTIONS FOR AN ON DEMAND WORLD

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}

12

IBM OUTPUT ENVIRONMENT

OUTPUT SOLUTIONS FOR AN ON DEMAND WORLD

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

! Its not worth the effort to fix complex errors

" eg., you can fix a bad dimension in an OBD or OBP, but you cant fix a bad image raster pattern

13

IBM OUTPUT ENVIRONMENT

OUTPUT SOLUTIONS FOR AN ON DEMAND WORLD

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

14

IBM OUTPUT ENVIRONMENT

OUTPUT SOLUTIONS FOR AN ON DEMAND WORLD

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 ...2 ...3 ...4 ...5 ...6 ...7 ...8 ...9 ..10 ..11 ..12 ..13

NOP (No Operation) BDT (Begin Document) NAME - BPG (Begin Page) NAME - - BAG (Begin Active Environ Group) NAME - - - MCF1 (Map Coded Font 1) - - - PGD (Page Descriptor) - - - CTC (Composed-Text Control) - - - PTD1 (Presentation Text Descrip) - - EAG (End Active Environ Group) NAME - - BCT (Begin Composed-Text Block) NAME - - - PTX (Presentation Text Data) - - ECT (End Composed-Text Block) NAME - EPG (End Page) NAME

SFI AFPANLYZ SFI i SFI i SFI SFI SFI SFI SFI i SFI (blanks) SFI SFI (blanks) SFI i SFI

0033 0018 0015 0010 0044 0016 0012 0014 0010 0010 0111 0010 0010

D3EEEE D3A8A8 D3A8AF D3A8C9 D3B18A D3A6AF D3A79B D3A69B D3A9C9 D3A89B D3EE9B D3A99B D3A9AF

000001 000002 000001 000001 000001 000002 000003 000004 000001 000002 000001 000002 000001

15

IBM OUTPUT ENVIRONMENT

OUTPUT SOLUTIONS FOR AN ON DEMAND WORLD

! AFP Analyzer

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 1:NOP:SCRIPT/VS 4.0.0: DEVICE PG1A CHARS X0N2200E TRN:( 14)>April 18, 2002< 2: BEGIN DOCUMENT :AFPANLYZ Coded Graphic Character Set AMB: 936 Global Id: GCSGID 65535 CPGID 37 AMI: 240 3: BEGIN PAGE :i Fully Qualified Name: Replace RMI: 1009 First GID Name: i (Hex) 89 TRN:( 37)>Howard Turetzky, IBM Printing Systems< 4: BEGIN ACTIVE ENVIRONMENT GROUP :i AMB: 1041 5:MCF:FONT_ID CODED_FONT CODE_PAGE CHAR_SET ROT AMI: 240 3 T1000395 C1H20000 RMI: 1163 2 T1000395 C1H400F0 TRN:( 26)>Boulder Programming Center< 6:PGD: X Units 2400 Y Units 2400 X Size 2040 Y Size AMB: 1076 2640 Page Size: 8.50 11.00 AMI: 240 7:CTC:(CONSTANT):00000000000000002D00 1274 8:PTD: X,Y Unit Base 10 in X,Y Units/Base: 2400 2400 RMI: TRN:( 18)>howardt@us.ibm.com< X,Y Text Block Size: 2,040 2,640 (unchained) NOP:( 0)>< 9: END ACTIVE ENVIRONMENT GROUP :i (Bytes: 166) 12: END PRESENTATION TEXT BLOCK : (Bytes: 308) 10: BEGIN PRESENTATION TEXT BLOCK : 13: END PAGE :i (Bytes: 513) 11:PTX: (escape) STO: 000/090

Analyzing AFP

" (MVS,VM, Windows, AIX)

Decodes everything Large output

AMB: AMI: SVI:

473 240 15

16

IBM OUTPUT ENVIRONMENT

OUTPUT SOLUTIONS FOR AN ON DEMAND WORLD

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 x00 " This can be fixed by a code page that maps x00 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 Error Mark)
" 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

17

IBM OUTPUT ENVIRONMENT

OUTPUT SOLUTIONS FOR AN ON DEMAND WORLD

Lab Exercise: Invalid Characters

! On the Start Menu, select Programs->AFP Workbench for Windows->IBM AFP Workbench Viewer ! In the Open File Name box, type or navigate to C: \AFP_Debug_lab \ansicc.afp ! Click on the zoom icon in the toolbar or 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) Options->Preferences->More Add path C: \AFP_Debug_lab; to Resources

! Dont see the palm tree?

" " "

18

IBM OUTPUT ENVIRONMENT

OUTPUT SOLUTIONS FOR AN ON DEMAND WORLD

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:

20

IBM OUTPUT ENVIRONMENT

OUTPUT SOLUTIONS FOR AN ON DEMAND WORLD

Optional Lab Exercise: Using ACIF to Find Errors

! Open a command window ! cd C:\AFP_Debug_lab ! Run ACIF:
acif0425-415 parmdd=acif.parm cpgid=500
0425-415 cc=yes 0425-415 cctype=a 0425-415 chars=GT10,GB10,GI12,LR12 0425-415 fileformat=record 0425-415 formdef=F1A10110 0425-415 indexobj=none 0425-415 inputdd=ansicc.host 0425-415 mcf2ref=cf 0425-415 outputdd=ansicc.afp 0425-415 pagedef=P1STD1 0425-415 trc=yes 0425-415 restype=none 0425-415 userlib=. 0425-346 DATA IN AN INPUT RECORD OR PAGEDEF RESOURCE IS INVALID: A SKIP TO A NON EXISTENT CHANNEL = 'F3'X ON RECORD NUMBER = 51 WAS DETECTED WITHIN THE LND STRUC TURED 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 NON EXISTENT CHANNEL = 'F2'X ON RECORD NUMBER = 79 WAS DETECTED WITHIN THE LND STRUC TURED 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 SE QUENCE NUMBER IS NOT AVAILABLE, AND RESOURCE NAME IS UNKNOWN. 0425-441 ACIF AT PQ71172 HAS COMPLETED ABNORMALLY WITH RETURN CODE 4. 21

IBM OUTPUT ENVIRONMENT

OUTPUT SOLUTIONS FOR AN ON DEMAND WORLD

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

22

IBM OUTPUT ENVIRONMENT

OUTPUT SOLUTIONS FOR AN ON DEMAND WORLD

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=*

23

IBM OUTPUT ENVIRONMENT

OUTPUT SOLUTIONS FOR AN ON DEMAND WORLD

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 help solve 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

24

IBM OUTPUT ENVIRONMENT

OUTPUT SOLUTIONS FOR AN ON DEMAND WORLD

What the Server Doesnt 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 " " " "

25

IBM OUTPUT ENVIRONMENT

OUTPUT SOLUTIONS FOR AN ON DEMAND WORLD

What the Printer Knows

! As the printer builds an image of the page in memory, it detects 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

26

IBM OUTPUT ENVIRONMENT

OUTPUT SOLUTIONS FOR AN ON DEMAND WORLD

How to Make Sense of Sense Data

IPDS error-code registry for printers ! (310) Hardware sense data (link level)
" " " " " 24 bytes of error or situation information Device specific Action codes:
X00, X02-X04, X07, X0B, X0F-X14, X18, X1C, X24, X25, X4D

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)
28

IBM OUTPUT ENVIRONMENT

OUTPUT SOLUTIONS FOR AN ON DEMAND WORLD

Layout of an IPDS NACK

29

IBM OUTPUT ENVIRONMENT

OUTPUT SOLUTIONS FOR AN ON DEMAND WORLD

Places to Look (a peek into Daves 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

30

IBM OUTPUT ENVIRONMENT

OUTPUT SOLUTIONS FOR AN ON DEMAND WORLD

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

31

IBM OUTPUT ENVIRONMENT

OUTPUT SOLUTIONS FOR AN ON DEMAND WORLD

The Real Debugging Secrets

! Analysis and experience are the main tools we use
" " " " With much reading of manuals Using the tools weve seen Changing and fixing what we can Then testing until it works

" and when all else fails, call m

32

IBM OUTPUT ENVIRONMENT

OUTPUT SOLUTIONS FOR AN ON DEMAND WORLD

Questions?

33

IBM OUTPUT ENVIRONMENT