Transcription

TXT2PDF User ReferenceGuideConvert Text Files to Portable Document Format (PDF)Version 09.107Revised April 17, 2009Leland [email protected] B. [email protected] User Reference GuidePage 1 of 544/18/2009

Table of ContentsTable of Contents 2Notices 4Acknowledgements 5Individuals 5Routines 5Contact Information 6Introduction 7TXT2PDF: The Command 8IN 9OUT 9ANNOT 9BG 10BM 11BROWSE 11CC 11COLOR 12COMPRESS 12CONFIG 12CONFIRM 13DEFCFG 13DELIM 13DINFO 13DRAW 14ENCODING 18ENCRYPT 18FONT 19HLQ 20IFEMPTY 20IMAGE 21LM 23LPI 23MAG 23MAXOSIZE 23MSGID 24MSGLVL 24OLOPT 24OLSORT 25OLTOK 25ORIENT 25OUTLINE 26OUTREC 27PAGE 28PAPER 29RM 29TEXT 30TM 31TRANS 31UNITS 32VIEWER 32VONLY 33TXT2PDF User Reference GuidePage 2 of 544/18/2009

XFONT 33XLATE 34TXT2PDF: The ISPF Dialog 35Primary ISPF PanelAnnotation PanelBackground PanelColor PanelEncryption PanelFont PanelMiscellaneous PanelOutline PanelOutline OptionsPage and Paper PanelProcessing SelectionBatch FTP OptionBatch Mail OptionForeground Processing optionsDownload PanelFTP PanelMail Panel3536363637373737383839404041414142TXT2PDF: Examples 43Appendix A: Installation 46Setting TXT2PDF Defaults: All PlatformsNational Language Translation: All PlatformsLinux and CygwinWindowsOS/390 and z/OSVM and z/VM464647474748Appendix B: GreenBar Stream Example 49TXT2PDF User Reference GuidePage 3 of 544/18/2009

NoticesThis software contains encryption source and object code that is regulated by the United States Bureauof Industry and Security. Since this is an “open-source” project, the required notice was submitted forLicense Exception TSU. This allows the software to be exported from the United States.However, the software may not be exported to certain countries and their nationals as they arerestricted by Section 734.2 of the EAR (Export Administration Regulations). These countries include,but are not limited to, Cuba, Iran, Iraq, Libya, North Korea, Syria, and Sudan. Please refer to theExport Administration Regulations website for more information.TXT2PDF User Reference GuidePage 4 of 544/18/2009

AcknowledgementsIndividualsWe would like to acknowledge the following individuals. Through their suggestions, testing, and codecontributions, TXT2PDF has become a much better product overall.Leland Lucius: For the TXT2PDF REXX code and the T2PINIT, T2PARC4, T2PMD5, andT2PTERM assembler code.Lionel B. Dyck: For creating XMITIP without which the original TXT2PDF code would haveremained hidden in some other homegrown applications and never seen the light of day. (Not tomention his already established distribution channels. Lionel has also contributed the TXT2PDFI ISPFdialog and this document, for which you should be extremely thankful. I hate doing documentationAndy W. Robertson: For fixing and enhancing the original escaping code and translation tables.A. Harry Williams: For adding the original CMS and Regina support without which TXT2PDFwould still be running on OS/390 only.Neal E. K. Gooch: For fixing some environment handling issues, adding Object REXX compatibility,and contributing the initial multi-level indexing code.Felipe Cvitanich: For contributing the PDFXLIB EXEC making it much easier to create the externaltranslation table.Len Steele: For major testing, feature suggestions, and making me think about other things “the rightway.”Frank M. Ramaekers Jr.: For giving all you VMers compression and encryption by doing a prettydarn good job of converting and generalizing the assembler routines.And many more: See the EXEC for a list of all contributors and the list of changes for theircontribution. (Gettin‟ to be too many to list here. ;-))RoutinesSeveral routines used by TXT2PDF were located on the Internet and we‟d like to thank their authorsfor publishing them. Any and all rights to these routines remain with the original authors.The Cos(), Pi(), Sin(), Sqrt() and QSort() routines were culled from the "Album of Algorithms andTechniques" by Vladimir Zabrodsky. If you use REXX, you HAVE to check this out:www.geocities.com/zabrodskyvlada/aatPeter Butler ([email protected]) posted the Atan() function to sci.math.num-analysis in 1995.TXT2PDF User Reference GuidePage 5 of 544/18/2009

Contact InformationFeel free to contact either of us if you have suggestions or encounter problems with this documentationor the application.Lionel B. eland PDF User Reference GuidePage 6 of 544/18/2009

IntroductionThe TXT2PDF utility is used to convert a text file into a Portable Document Format (PDF) file. It hasmany options to control the conversion, output appearance, and final presentation. Some of thefeatures include: AnnotationsOutline GenerationColor ControlSeveral Background OptionsViewer ControlThe following features are only available on OS/390, z/OS, and z/VM platforms: Encryption (will come to other platforms in the future)CompressionThe following feature is only available on OS/390 and z/OS: ISPF DialogThe ISPF Dialog features of interest are: Prompted creation of the TXT2PDF optionsForeground and Batch processing optionsEasy modeling for production batch JCLSupport for FTP and E-Mail of the generated reportCreation of Configuration fileWhile the original design was simply to convert OS/390 reports to PDF prior to emailing, TXT2PDFhas been generalized and adapted to other platforms including Linux, VM, and Windows. All that isrequired is a REXX interpreter or compiler on the target platform.Not sure about the load modules within the z/VM environment – awaiting word from someone whoknows z/VM.TXT2PDF User Reference GuidePage 7 of 544/18/2009

TXT2PDF: The CommandTXT2PDF is a standard command line utility and must be executed from a standard command lineinterface on the appropriate platform. For OS/390 and z/OS it is a standard TSO command and musttherefore be executed while logged in or in batch using the batch terminal monitor program (TMP).See the Examples section for examples of the JCL which can be used.The complete syntax is:TXT2PDF IN input filespec OUT output filespec ANNOT type / type spec BG type / type spec BM bottom margin BROWSE browse messages CC carriage control COLOR fore / back COMPRESS level CONFIG config filespec CONFIRM level DELIM character DINFO document info filespec DRAW type / specs ENCODING func / specs ENCRYPT type / opts FONT size / name / zoom HLQ hlq IFEMPTY option IMAGE func / name / specs LM left margin LPI line per inch MAG level MAXOSIZE max output size 0 MSGID prefix messages MSGLVL msgnum / msglvl OLOPT option/. OLSORT direction OLTOK token ORIENT orientation OUTLINE type / args OUTREC len PAGE mode / layout PAPER size / type / style RM right margin TM top margin TRANS style / dur / opts/. UNITS unit of measure VIEWER flags/. VONLY opt XFONT type / opts The command syntax is keyword followed by an option with no intervening equal sign. If the optioncontains embedded blanks then the entire option must be enclosed in quotes.Under TSO, and ISPF, all data set names are processed using the standard TSO and ISPF conventions.This means that if a TSO PREFIX is different from the Userid then that PREFIX will be used whenaccessing data set names that are not fully qualified and enclosed within quotes.TXT2PDF User Reference GuidePage 8 of 544/18/2009

INThe IN keyword defines the input file that will be converted to PDF format. Any valid filespecification for the platform is allowed.On platforms that have “standard” input and output files, you may omit this parameter and the inputtext will be read from “standard” input. This includes the CMS environment when TXT2PDF is run asa PIPELINE stage.Syntax:IN file-specificationExamples:z/OS:IN „userid.report.text‟IN DD:ddnameIN report.textz/VM:IN report.text.aOthers:IN report.txtOUTThe OUT keyword defines the file that will be created from the conversion of the input file. The filespecification is any valid file specification for the platform.On platforms that have “standard” input and output files, you may omit this parameter and the outputPDF file will be written to “standard” output. This includes the CMS environment when TXT2PDF isrun as a PIPELINE stage.Syntax:OUT file-specificationExamples:z/OS:OUT „userid.report.text‟OUT DD:ddnameOUT report.textz/VM:OUT report.text.aOthers:OUT report.txtANNOTAnnotations are similar to yellow post-it notes that are placed within a document.Syntax:ANNOT TEXT/page/row/col/state/textpageOn what page should the note be placed:FirstFLastLAllADefault: ALLOn first page onlyOn the last page onlyOn all pagesrowthe row, or line, on the page where the note will be placedDefault: 1colthe column where the note will be placed. This is onlyapproximate as TXT2PDF does not have the font metrics foran exact placement.Default: 1TXT2PDF User Reference GuidePage 9 of 544/18/2009

statethe initial display state of the note specified as:OpenClosedOCcauses the note to be opencauses the note to be closedDefault: 1textExamples:the text for the sticky noteANNOT Text/1/1/1/O/sample-textANNOT “T/1/1/1/C/Sample Text”Quotes are needed to include the blanksBGThe background will be drawn before the text of the document and this allows you to specify as manybackgrounds as you like. They will be placed in the order you specify.The STREAM background allows you to include valid PDF stream content from an external file, whilethe TEXTMARK and TMARK types produce an effect similar to a watermark.Syntax:BG STREAM/file-specificationBG G e/textBG e/font-size/textSupported types are:StreamTextmarkTmarkPDF stream contentSimulated watermarkEnhanced watermarkSTREAM:file-specificationContains the PDF control statements that define streamcontent. See Appendix B for an example.TEXTMARK and TMARK:styleThe direction in which to draw the text:TopDownTDBottomUpBUDefault: BottomUpupper left to bottom rightbottom left to upper righttext-colorColor of the textDefault: nonefill-colorIf not specified the text will appear hollow, otherwise the colorused to fill the letters.Default: GrayopacityPercent of solidness of the text.Default: 100font-name(TMARK) Name of the font.Default: Courierfont-size(TMARK) Size of the font in points.Default: 100TXT2PDF User Reference GuidePage 10 of 544/18/2009

textText to drawDefault: noneExamples:BG Stream/‟userid.stream.data set‟BG Textmark/bottomup//gray/100/TXT2PDFBG Textmark/td/yellow/black/80/TXT2PDFBG Tmark/td/yellow/black/80/12/TXT2PDFBG Tmark/td/yellow/black/80/Vera/12/TXT2PDFBMThe bottom margin is the offset in inches from the bottom of the page.Syntax:BM offsetDefault: 0.5 inchesExample:BM 0.8Note:See UNITSBROWSEDefines whether messages generated by TXT2PDF will be displayed. If under ISPF the messages willbe displayed in an ISPF Browse display otherwise the message will appear on the active window.Syntax:Browse optionoptionSpecify one of the following:YesNoYNDefault: NoExample:BROWSE NoCCSpecifies if the input data set contains carriage control characters in column 1 of the data. Both ASAand Machine carriage control characters are supported.Syntax:CC optionoptionExample:Specify one of the following:YesYFirst column contains machine or ASACC charactersNo (or ignore) CC charactersFile contains ASCII CC charactersNoAsciiNADefault:No (or based upon the DCB of data set)CC YesTXT2PDF User Reference GuidePage 11 of 544/18/2009

COLORDefines the color of the Text as well as the Background color of the page.Syntax:COLOR foreground/backgroundWhere foreground defines the color of the text on the page and background is thecolor of the page.All colors can be specified using either the following names or by specifying theexact RGB values by using 6 hexadecimal digits formatted as ellowFMRYThough intended for use with the barred paper style, the following colors may alsobe used:BlueBarOrangeBarExamples:GrayBarWhiteBarCOLOR Black/WhiteCOLOR Y/NCOLOR 00FF00GreenBarYellowBarthe defaultfor Yellow text and Navy backgroundgreenCOMPRESSDefines a level of compression from level 0 (none) to level 9 (maximum).Syntax:COMPRESS levelDefault: 0Example:COMPRESS 2CONFIGThe CONFIG keyword defines a file containing additional parameters. Everything in this file will beprocessed as if it had been included as arguments to the TXT2PDF command. Any arguments on theTXT2PDF command will override parameters in the Config file. Nested Config files are alsosupported. Comments are statements with an * in column 1. Continuation is by either a blank dash “ –“combination or a plus “ ” at the end of a record.Syntax:CONFIG file-specificationDefault: noneExamples:CONFIG „userid.txt2pdf.config‟CONFIG DD:ddnameCONFIG txt2pdf.config.aCONFIG c:\winnt\pdfconfig.txtCONFIG /.txt2pdfSample CONFIG File:* sample configuration fileRm .2 lm .2 tm .3 bm .3TXT2PDF User Reference GuidePage 12 of 544/18/2009

Msgid yes color yellow/blackConfig „userid.nested.config‟CONFIRMDefines the level of messages displayed during the TXT2PDF conversion process.Syntax:CONFIRM levelLevelSpecify one of the following:YesYNoNVerbose Vfor standard messagesfor quiet mode (no messages)for extensive messagesDefault: YesExamples:CONFIRM YesCONFIRM VDEFCFGDefines the name of the default config file as used by the CONFIG parameter. This does not actuallycause inclusion. The specified file will be included only if there are no command line parameters.You would normally use this in your TXT2PDFD EXEC.Syntax:DEFCFG file-specificationDefault: noneExamples:DEFCFG „userid.txt2pdf.config‟DEFCFG DD:ddnameDEFCFG txt2pdf.config.aDEFCFG c:\winnt\pdfconfig.txtDEFCFG /.txt2pdfDELIMThe DELIM parameter allows you to change the character used to delimiter between arguments. Anyparameter following this one must use the new specification.Syntax:DEFLIM characterDefault: /Examples:DELIM ,DINFODocument Information, or DINFO, references a file which contains a name followed by a descriptionthat will be added to the Document Information dictionary within the PDF file.Syntax:DINFO file-specificationDefault: noneExamples:DINFO „userid.pdfdinfo.text‟DINFO dinfo.txt.aDINFO c:\pdf\dinfo.txtTXT2PDF User Reference GuidePage 13 of 544/18/2009

Syntax for the DINFO file:Title The title of this documentSubject A subject line for the documentAuthor Name of the author(s)Keywords any associated keywords (you create the keyword)Sample DINFO File:Title TXT2PDF User‟s GuideSubject Getting Started with TXT2PDFAuthor Prefers to remain unknownBogus – you created this keyword so you must know what it meansDRAWThe DRAW parameter allows you to draw different objects on the page. At this time, you may drawlines, unfilled rectangles, filled rectangles, static text, and dynamic strings.To provide the most flexibility, coordinates and sizes are specified in PDF user space units. Each unitis 1/72 of an inch and the origin is the bottom left of the page. In addition, margins are ignored.Syntax:DRAW ton/dotoffDRAW style/doton/dotoffDRAW le/rotation/zoom/textDRAW tyle/rotation/zoom/textSupported types are:LineRectTextStringDraws a lineDraws a rectangleDraws textDraws dynamic textLINE and RECT:xThe lower left x-axis coordinate.Default: noneyThe lower left y-axis coordinate.Default: noneendx(LINE only) The upper right x-axis coordinate.Default: noneendy(LINE only) The upper right y-axis coordinate.Default: nonewidth(RECT only) The width of the rectangle.Default: noneheight(RECT only) The height of the rectangle.Default: noneopacityA value specifying the percentage of opacity the image willhave. A value of 100 will produce a solid image and anythingTXT2PDF User Reference GuidePage 14 of 544/18/2009

less will produce transparent images.Default: 100%fore(LINES) Color of the line(RECT) Color of the outline around the rectangle. Omitting itwill produce a rectangle without a bounding box.Default: Blackback(RECT) Specifies the background or fill color.Default: nonethicknessThe thickness of the line or bounding box.Default: 0style(LINE) The type of encaps that will be placed at thebeginning and end of the line. The ROUND and SQUAREcaps project past the line end points so you will need toaccount for it when positioning.Possible values are:ButtRoundSquareSquare ends with no projectionRound ends with projectionSquare ends with projectionDefault: Butt(RECT) The shape used for the corners of the rectangle.Possible values are:MiterRoundBevelPointed (like a picture frame)RoundedLike miter, but the points are chopped.Default: Miterdoton/dotoffThese 2 values work together to create lines and boundingboxes with different dash patterns. Line thickness and capstyle affect the dashes, so it will take a bit of trial and error toget exactly what you want.The “doton” value specifies the number of units dashes willhave within the pattern. If you do not specify this, then avalue of 0 will be used.The “dotoff” value specifies the number of units the gaps willhave between dashes. If you do not specify a “dotoff” value,it will default to the “doton” value and the result will be samesized dashes and gaps.Default: none (solid line)TEXT and STRING:xTXT2PDF User Reference GuideThe lower left x-axis coordinate.Default: nonePage 15 of 544/18/2009

yThe lower left y-axis coordinate.Default: nonefontThe name of the font to use.Default: CouriersizeThe size in pointsDefault: 9opacityA value specifying the percentage of opacity the text willhave. A value of 100 will produce solid text and anything lesswill produce transparent text.Default: 100%foreSpecifies the color of the outline around the characters.Default: nonebackSpecifies the fill color of the characters.Default: nonethicknessThe thickness of the line or bounding box.Default: 0styleThe shape used for the corners of the glyphs.Possible values are:MiterRoundBevelPointed (like a picture frame)RoundedLike miter, but the points are chopped.Default: MiterrotationA value specified in degrees which controls the rotation of thetext. Negative numbers rotate clockwise.Default: 0zoomZoom is a percentage factor used to increase or decrease thefont size.Default: 100%textThe text to draw.The value may contain certain format sequences that getreplaced with different values. These sequences fall into 2categories, date/time and dynamic.Date and time sequences can be used in both TEXT andSTRING types. The date and time used is that at time ofparsing.The sequences start with a percent (%) and are followed byone of:%aAbBTXT2PDF User Reference Guide-literal percentabbreviated weekday namefull weekday nameabbreviated month namefull month namePage 16 of 544/18/2009

cdeHIjmMpSwxXyY-format: Sun Oct 26 02:00:00 20032 digit day of month (zero padded)2 digit day of month (space padded)2 digit (24) hour2 digit (12) hour3 digit day of year2 digit month of year2 digit minutemeridian2 digit second1 digit day of the week (0 Sunday)date format: 10/26/03time format: 02:00:002 digit year4 digit yearDynamic sequences can only be used with the STRING type.The values for these sequences change during processing.The sequences start with an at sign (@) and are followed byone of:@ - literal at signp - PDF page number (1 based)*A zero pad and length may be specified forsequences marked with an “*” like so:@4p - blank pad page number to 4 [email protected] - zero pad page number to 4 bytesDefault: noneExamples:DRAW LINE/0/0/700/600/100/RedDRAW line/100/300/400/300///4/Round/0/4DRAW RECT/0/0/700/600/50/Red/GreenDRAW rect/50/50/400/90/Blue///BevelDRAW “text/10/600/Times/30/100/Blue/Red///-45/300/ Just Some Test Text ”DRAW “text/10/600/Times/30/100/Blue/Red/////Date: %c”DRAW “string/10/600//////////Date %m/%d/%Y – Time %H:%M:%S – Page @4p”TXT2PDF User Reference GuidePage 17 of 544/18/2009

ENCODINGThe ENCODING parameter allows you to define Unicode character map which are used to mapcharacters in the PDF file to their Unicode equivalents. This is mostly important when usinglanguages to do not use a Latin character set, but may also be used instead of the translation table inTXT2PDFX or the one specified via the XLATE parameter.The UCM files can be obtained from the ICU Project source code repository. Select the desiredmapping and save it as a plain text file. If needed, upload it to either a PDS or sequential file as ASCIIto allow conversion to EBCDIC.Syntax:ENCODING DEFINE/name/file-specificationDEFINE:nameThe name to assign to the encoding. Use this name toassociate the encoding to a font via the XFONT parameter.file-specificationSpecifies the file name or dataset name that contains the UCMformat encoding.Examples:ENCODING DEFINE/ibm1047/‟userid.stream.data set‟ENCODING DEFINE/1255/ibm-1255 P100-1995.ucmENCRYPTEncryption enables the securing of the created PDF file. At present only the PDF Standard security issupported. Note: This option is only supported on OS/390, z/OS, and CMS at this time.Syntax:ENCRYPT ST/owner/user/key-length/parmsThe currently defined encryption types are:STUses PDF standard encryptionownerA password granting full access to the document. Only thefirst 32 characters are used. The rest are ignored.Default: noneuserA password giving the user access to the document based onthe selected parms (see below). It is limited to 32 charactersas well.Default: nonekey-lengthSpecifies the length of the encryption key. Valid values are:ST:4012840-bit key (all Acrobat versions)128-bit key (Acrobat 5 or above)Default: 40parmsTXT2PDF User Reference GuideControls what the user can do with the document. Specify anyof the following, separated by a “/”:Page 18 of 544/18/2009

RINTNONENASNHPNNo printingNo editingNo copyingNo editing notes/formsDon't allow Save AsNo fill/sign formsNot accessible(Not Recommended!)No insert/rotate/No Hires printingNo permissionsDefault: (all permissions)Examples:ENCRYPT ST/Owner//128/np/ne/ncENCRYPT ST/Owner/User/40/neENCRYPT “ST/owner password with blanks//nc”FONTDefines the font to be used.Syntax:FONT size/name/zoomsizeSize of the font in points (1/72 of an inch)Default: 9nameName of the font defined via the XFONT parameter or one ofthe following predefined PDF Type 1 font t: CourierzoomExamples:Zoom factor in percent of original font size. Specifying apercentage less than 100 will cause the font to shrink and apercentage greater than 100 will cause the font to enlarge.Default: 100FONT 9/Courier/100FONT 12/TB/50TXT2PDF User Reference GuidePage 19 of 544/18/2009

HLQHigh level qualifier for OS/390 data set names. It will be prepended to any DSN not beginning witha single quote (') or the special "DD:" syntax.Under TSO, the default value will be the prefix from the current profile. If one is not assigned, thecurrent userid will be used. If the current prefix and userid are both assigned AND they aren't thesame, both will be used, separated by a period.Under IRXJCL, the default value will be the current userid, if available.For all other environments, the default will be null.Syntax:HLQ high-level-qualiferDefault: (see above)Examples:HLQ SYS1HLQ Z891001IFEMPTYAlters the behavior when an empty input file is detected.Syntax:IFEMPTY optionOptionSpecify one of the following:ERROR – causes an error message to be generatedBLANK – produces a warning message and a blank PDF fileAnything else will cause a warning message to be producedand a PDF file will be created with the text you specify here.Default: ERROR.Examples:IFEMPTY ERRORIFEMPTY “The input file was empty”IFEMPTY BLANKTXT2PDF User Reference GuidePage 20 of 544/18/2009

IMAGEThe IMAGE parameter allows you to draw images on the page. Currently, this only includes JPEGand BMP files but more are planned.You use the LOAD function to load the image from a file and assign it a name. Then you use theDRAW or TILE functions to draw the image on the page using the name you assigned.An advantage of separating the LOAD and DRAW/TILE functions is that you may LOAD severalimages in the default configuration file (TXT2PDFD) and they will always be available. Just DRAWit by name when you need it.To provide the most flexibility, coordinates are specified in PDF user space units. Each unit is 1/72 ofan inch and the origin is the bottom left of the page. In addition, margins are ignored.Syntax:IMAGE Load/name/file-specificationIMAGE /skewyIMAGE Tile/name/x/y/w/h/opacitySupported functions are:LoadDrawTileLoads specified file and associates it with “name”Draws “name” using given parametersTiles “name” within given constraintsnameThe name to assign the imageDefault: nonefile-specificationThe name of the file containing the imageDefault: nonenameThe name of the image to drawDefault: nonexThe position on the horizontal axis where the image will beplaced. This is relative to the left edge of the page.Default: noneyThe position on the vertical axis where the image will beplaced. This is relative to the bottom edge of the page.Default: noneopacityA value specifying the percentage of opacity the image willhave. A value of 100 will produce a solid image and anythingless will produce transparent images.Default: 100%rotationA value specified in degrees which controls the rotation of theimage. Negative numbers rotate clockwise.Default: 0LOAD:DRAW:TXT2PDF User Reference G

TXT2PDF User Reference Guide Page 1 of 54 4/18/2009 TXT2PDF User Reference Guide Convert Text Files to Portable Do