Convert a text file to a PDF file
Component: | CONV2PDF |
Functional area: | File processing |
Domain: | FILE, SPOOL-PRINT-SERVICES, UTILITIES |
Privileges: | STD-PROCESSING |
Function
The CONVERT-FILE-TO-PDF command converts text files (SAM or ISAM files and text-based library elements) to PDF files. These can then be easily read or printed out page by page using a PDF viewer (e.g. Adobe Reader) on a PC.
The user can also specify more than one text file in a command call. In addition, a list of files can also be read from a list file or CSV file. In this case, the files will be converted one after the other. The resulting messages contain the corresponding line number. All file names of a list are edited, even if an error occurs.
Output then takes place either to individual PDF files or to one combined PDF file. When a combined PDF file is used, bookmarks are automatically set for the start pages of the text files which have been converted. Further parameters enable the user to control the content and layout of the PDF file:
processing records fully or only in part
line spacing (existing print control characters are optionally interpreted)
page size
Character density
margins
font
truncating or wrapping of long data lines
background picture on the PDF pages
Alternatively, the user can also control the layout via spool parameters, as with the PRINT-DOCUMENT command.
It must be borne in mind that depending on the layout only a particular number of characters can be displayed in a line. Data lines which extend beyond the right-hand margin are truncated or optionally wrapped when a PDF file is created.
The data in the PDF file is compressed. File transfer must be performed in binary mode.
Format
CONVERT-FILE-TO-PDF | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Operands
FROM-FILE = list-poss(16): <filename 1..54 with-wild(80)> / *FROM-FILE(…) / *FROM-CSV-FILE(…) /
*LIBRARY-ELEMENT(...)
Name of the text file to be converted which exists either as a file or a library element. Multiple files or library elements can be specified using wildcards or in a list. Only SAM or ISAM files are accepted (except for SAM files with REC-FORM=U). *FROM-FILE can also specify a list file containing the names of the text files to be converted. *FROM-CSV-FILE can be used to specify a CSV file containing the names of the text files to be converted and the target files.
FROM-FILE = *FROM-FILE(…)
The names of the files to be converted should be read from a list file. Each line of the list file contains exactly one (source) file name. It is not case-sensitive and spaces are ignored. Each file name is validated and, if there is no error, a PDF file is generated from this file. The PDF file has the same name as the source file with the extension .PDF.
If an error occurs, a message is output with the line number of the currently processed file name.
LIST-FILE-NAME = <filename 1..54 without-gen-vers>
Specifies the name of the list file.
FROM-FILE = *FROM-CSV-FILE(…)
The names of the files to be converted should be read from a CSV file. Each line of the CSV file contains exactly 2 file names - source and destination files, separated by a comma or semicolon. It is not case-sensitive and spaces are ignored. Each source file name is validated and, if there is no error, a PDF file is created with the name of the respective destination file.
If an error occurs, a message is output with the line number of the currently processed file name.
FROM-FILE = *LIBRARY-ELEMENT(...)
The specified element from a PLAM library is to be converted. An element is fully defined by its name, its type and its version.
The records of an element are assigned to particular record types. There are 255 record types. A distinction is drawn between user record types (1 through 159) and special record types (160 through 255). Only the user record types of an element can be converted to PDF.
LIBRARY = <filename 1..54 without-vers>
Name of the PLAM library from which an element is to be converted.
ELEMENT = <composed-name 1..64 with-under with-wild(80)>(...)
Name of the element to be converted. Multiple elements can be output using wildcards.
VERSION = *HIGHEST-EXISTING / *UPPER-LIMIT /
<composed-name 1..24 with-under with-wild(40)>
The version of the element which is to be output. Default is *HIGHEST-EXISTING, i.e. the last element in alphabetical order. If the version is specified in wildcard format, and if there are library elements with the same names to which the wildcard specification applies, then all of these library elements are output.
BASE = *STD / <composed-name 1..24 with-under with-wild(40)>
Prefix for version selection. In conjunction with VERSION=*HIGHEST-EXISTING this enables the highest version to be addressed with a particular prefix. BASE=*STD has the same effect as BASE=*.
For detailed information on specifying the base, see the "LMS" manual [21].
TYPE = <alphanum-name 1..8 with-wild (12)>
The type of the library element to be output.
If specified in wildcard format, the name consists of a maximum of 12 alphanumeric characters.
Note
The records of LMS elements of type C, L or R belong to the special record types (160 through 255). That is the reason why no records of such elements can be converted.
TO-FILE =
Specifies the name of the PDF file to be created.
TO-FILE = *BY-SOURCE
The name of a created PDF file consists of the name of the corresponding text file (file or element name) and the suffix “PDF”. If an illegal file name results, the command is rejected.
TO-FILE = *CONCATENATE(...)
All the text files (files or elements) specified are to be combined in one PDF file. In this case each text file starts on a new page.
TO-FILE = <filename 1..54 without-gen>
Name of the PDF file.
BOOKMARK =
Controls the setting of bookmarks in the PDF file.
BOOKMARK = *BY-SOURCE
The start page of each of the text files is assigned a bookmark with the name of the text file (file or element name).
BOOKMARK = *NONE
Suppresses the setting of bookmarks.
BOOKMARK = list-poss(16): <filename 1..54 with-wild-constr(80)>
The start page of each of the text files is assigned a bookmark with a name which is specified explicitly. When a list is specified, the names are set as bookmarks in the specified order. When a constructor string is specified, the bookmarks are mapped in accordance with the wildcard sequence specified in the FROM-FILE or ELEMENT-NAME operand.
TO-FILE = list-poss(16): <filename 1..54 without-gen-vers with-wild-constr(80)>(...)
Specifies the name(s) of the PDF file(s) explicitly. If wildcards are specified in FROM-FILE or ELEMENT-NAME, a constructor string can be specified for the PDF files.
The default for library elements is that the specified name is also assigned a suffix containing the type and version of the element (format: <to-file>.<version>.<type>). The creation of this suffix can also be controlled using the following operands:
WITH-VERSION = *STD / *YES / *NO
Evaluated only for library elements:
Specifies whether the suffix should contain the element version. *STD specifies *YES as the default.
WITH-TYPE = *STD / *YES / *NO
Evaluated only for library elements:
Specifies whether the suffix should contain the element type. *STD specifies *YES as the default.
WRITE-MODE = *CREATE / *REPLACE-ONLY / *ANY
Determines the write mode for the PDF files which are to be created. The default value is *CREATE, i.e. a new file is created. The command is rejected for a file which already exists.
WRITE-MODE = *REPLACE-ONLY
The output file must already exist and is overwritten during conversion. If the file does not already exist, the command is rejected.
WRITE-MODE = *ANY
A new output file is created. If the file already exists, it is overwritten.
FILE-FORMAT = *STD / *SAM / *PAM
Determines the file format of the PDF file.
FILE-FORMAT = *STD
Uses the file format which is defined in the SYSPAR.CONV2PDF parameter file. The parameter file is searched for at the following storage locations (search takes place in the specified order):
Caller’s user ID
TSOS user ID
If no parameter file is found, FILE-FORMAT=*SAM applies.
FILE-FORMAT = *SAM
The PDF file is created in SAM file format using REC-FORM=U.
FILE-FORMAT = *PAM
The PDF file is created in PAM file format and BLOCK-CONTROL=NO. In this file format the PDF file can also be created as a node file.
PRESENTATION = *DIRECT-PARAMETERS(...) / *SPOOL-PARAMETERS(...)
Defines the layout of the PDF file. Direct specification of the layout properties is preset. Alternatively the layout can be determined by specifying pool parameters (as with print output).
PRESENTATION = *DIRECT-PARAMETERS(...)
Specifies the layout of the PDF file directly.
RECORD-PART = *ALL / *PARAMETERS(...)
Defines whether the records of the text file are to be processed in full or if only a particular part of each record is to be processed.
When the default value *ALL is specified, the records are processed in full.
RECORD-PART = *PARAMETERS(...)
Specifies which part of the records is to be processed. Only the specified part is taken into account during conversion to PDF. This entry can be used, for example, to omit the ISAM key or control characters in the PDF file.
FIRST-CHARACTER = 1 / <integer 2..32767>
Allows a byte number (record column) to be specified indicating the point as of which the records of a file are to be output. The bytes of a record are numbered consecutively from left to right starting with 1; ISAM keys and control characters are components of a record.
LAST-CHARACTER = *STD / <integer 1..32767>
Specifies the byte indicating the point at which processing of each record is to stop.
LINE-SPACING = 1 / 2 / 3 / *BY-EBCDIC-CONTROL(...) / *BY-IBM-CONTROL(...) / *BY-ASA-CONTROL(...)
Specifies the number of line feeds and the way in which control characters are interpreted.
LINE-SPACING= 1 / 2 / 3
The records are to be printed out with 1-, 2- or 3-line spacing.
LINE-SPACING = *BY-EBCDIC-CONTROL(...) / *BY-IBM-CONTROL(...) / *BY-ASA-CONTROL(...)
The contents of the first byte of each record are to be interpreted as EBCDIC, IBM or ASA feed control characters (refer to PRINT-DOCUMENT command).
CONTROL-CHAR-POS = *STD / <integer 1..2040>
Number of the data byte which is interpreted as the feed control character. In the case of records of variable length, the fields containing the length information are not counted as data.
PAGE-SIZE = *A4 / *A4-LANDSCAPE / *A3 / *A3-LANDSCAPE / *A5 / *A5-LANDSCAPE /
*PARAMETERS(...)
Determines the page size of the PDF file:
Operand value | DIN format | Width x Height (mm) |
|---|---|---|
*A4 | DIN-A4 | 210 x 297 |
*A4-LANDSCAPE | DIN-A4 landscape | 297 x 210 |
*A3 | DIN-A3 | 297 x 420 |
*A3-LANDSCAPE | DIN-A3 landscape | 420 x 297 |
*A5 | DIN-A5 | 148 x 210 |
*A5-LANDSCAPE | DIN-A5 landscape | 210 x 148 |
*PARAMETERS(...) | User-specific | max. 2040 x 2040 |
PAGE-SIZE = *PARAMETERS(...)
Specifies the width and length of a PDF page explicitly.
WIDTH = <integer 2..2040>
Specifies the page width in mm.
HEIGHT = <integer 2..2040>
Specifies the page length in mm.
MARGINS = *PARAMETERS(...)
Defines the distances to the margins.
LEFT = 20 / <integer 0..2040>
Specifies the distance to the left-hand margin in mm.
RIGHT = 20 / <integer 0..2040>
Specifies the distance to the right-hand margin in mm. Data lines which extend beyond the right-hand margin are truncated or wrapped according to the specification in the LINE-TRUNCATION operand.
TOP = 20 / <integer 0..2040>
Specifies the distance to the top margin in mm.
BOTTOM = 20 / <integer 0..2040>
Specifies the distance to the bottom margin in mm.
DENSITY = *PARAMETERS(...)
Defines the line density.
LINES-PER-INCH = 6 / <integer 3..24>
Number of lines which are to be output per inch.
FONT = *PARAMETERS(...)
Determines the font which is to be used.
NAME = *COURIER / *HELVETICA / *TIMES
Specifies the name of the font.
CHARACTER-STYLE = *NORMAL / *BOLD / *ITALIC / *BOLD-ITALIC
Specifies the character style (normal, bold, italics, or bold and italics).
SIZE = 8 / <integer 1..72>
Specifies the font size in points (pt).
LINE-TRUNCATION = *YES / *NO
Specifies whether data lines which extend beyond the right-hand margin are truncated (see also definition of the right-hand margin in the MARGINS operand).
The default is *YES, i.e. longer data lines are truncated. When data lines are truncated, a message to this effect is issued after conversion.
LINE-TRUNCATION = *NO
Longer data lines are wrapped. The line break takes place at the word which extends beyond the margin. Thereby a word is a string which is limited by blanks, punctuation marks or the margin.
OVERLAY = *NONE / *PARAMETERS(...)
Specifies whether a background picture is to be used.
OVERLAY = *PARAMETERS(...)
The PDF pages are to contain a background picture.
FROM-FILE = <filename 1..54 without-gen-vers>
File which contains the background picture.
FRAME = *PAGE / *TEXT / *CUSTOM(...)
Determines the frame in which the background picture is positioned.
FRAME = *PAGE
The background picture is positioned within the physical page (determined by the specifications in the PAGE-SIZE operand).
FRAME = *TEXT
The background picture is positioned within the text frame (determined by the specifications in the MARGINS operand).
FRAME = *CUSTOM(...)
Defines a frame by means of the distances to the margins. This frame is independent of the text frame. However, the preset values are the same as the defaults in the PAGE-SIZE and MARGINS operands.
LEFT = 0 / <integer 0..2040>
Specifies the distance to the left-hand margin in mm.
RIGHT = 0 / <integer 0..2040>
Specifies the distance to the right-hand margin in mm.
TOP = 0 / <integer 0..2040>
Specifies the distance to the top margin in mm.
BOTTOM = 0 / <integer 0..2040>
Specifies the distance to the bottom margin in mm.
HORIZONTAL-ALIGNMENT = *LEFT / *RIGHT / *CENTER
Determines the horizontal alignment of the picture within the frame.
HORIZONTAL-ALIGNMENT = *LEFT
The picture is aligned with the left-hand margin of the frame.
HORIZONTAL-ALIGNMENT = *RIGHT
The picture is aligned with the right-hand margin of the frame.
HORIZONTAL-ALIGNMENT = *CENTER
The picture is centered horizontally in the frame.
VERTICAL-ALIGNMENT = *TOP / *BOTTOM / *CENTER
Determines the vertical alignment of the picture within the frame.
VERTICAL-ALIGNMENT = *TOP
The picture is aligned with the top.
VERTICAL-ALIGNMENT = *BOTTOM
The picture is aligned with the bottom.
VERTICAL-ALIGNMENT = *CENTER
The picture is centered vertically in the frame.
SCALE = *UNCHANGED
Determines the size of the picture.
The default is *UNCHANGED, i.e. the picture size is not changed.
SCALE = *FIT-HEIGHT
The picture is fitted to the height of the frame.
SCALE = *FIT-WIDTH
The picture is fitted to the width of the frame.
SCALE = *FIT-FRAME
The picture is fitted to the height and width of the frame. If the relationships of scale of the frame and picture differ, the picture may be distorted.
PRESENTATION = *SPOOL-PARAMETERS(...)
Specifies spool parameters which control the layout of the PDF file (analogously to print output with the PRINT-DOCUMENT command).
RECORD-PART = *ALL / *PARAMETERS(...)
Defines whether the records of the text file are to be processed in full or if only a particular part of each record is to be processed.
When the default value *ALL is specified, the records are processed in full.
RECORD-PART = *PARAMETERS(...)
Specifies which part of the records is to be processed. Only the specified part is taken into account during conversion to PDF. This entry can be used, for example, to omit the ISAM key or control characters in the PDF file.
FIRST-CHARACTER = 1 / <integer 2..32767>
Allows a byte number (record column) to be specified indicating the point as of which the records of a file are to be output. The bytes of a record are numbered consecutively from left to right starting with 1; ISAM keys and control characters are components of a record.
LAST-CHARACTER = *STD / <integer 1..32767>
Specifies the byte indicating the point at which processing of each record is to stop.
LINE-PER-PAGE = *STD / <integer 1..32767>
Specifies how many lines (including blank lines) are to be output on a page.
LINE-PER-PAGE = *STD
If the operand is omitted, the number of lines per page is calculated using the following formula:
Number of lines = P * L - N - 6
The name sections have the following meanings:
P = paper size in inches
L = line density
N = number of line before the first channel 1
If the value specified for the LINE-PER-PAGE operand is greater than the specified number of lines in the loop, the value in the loop is used.
LINE-SPACING = 1 / 2 / 3 / *BY-EBCDIC-CONTROL(...) / *BY-IBM-CONTROL(...) / *BY-ASA-CONTROL(...)
Specifies the number of line feeds and the way in which control characters are interpreted.
LINE-SPACING= 1 / 2 / 3
The records are to be printed out with 1-, 2- or 3-line spacing.
LINE-SPACING = *BY-EBCDIC-CONTROL(...) / *BY-IBM-CONTROL(...) / *BY-ASA-CONTROL(...)
The contents of the first byte of each record are to be interpreted as EBCDIC, IBM or ASA feed control characters (refer to PRINT-DOCUMENT command).
CONTROL-CHAR-POS = *STD / <integer 1..2040>
Number of the data byte which is interpreted as the feed control character. In the case of records of variable length, the fields containing the length information are not counted as data.
FORM-NAME = *STD / <alphanum-name 1..6>
Determines the page format of the PDF file by specifying the form. The spool parameter file must contain a standard form for the printer type HP-90.
The default setting *STD causes the standard form STD to be used for the printer type specified in the PRINTER-TYPE operand.
FORM-NAME = <alphanum-name 1..6>
Name of the form. Depending on the ROTATION operand, either the normal loop or the loop for page rotation from the form definition is used.
A loop is named implicitly in the form specification. The assigned loop must be contained in the printer control file $SYSSPOOL.PRFILE.
The loop named implicitly via the FORM-NAME operand is ignored if the LOOP-NAME operand is specified at the same time.
When FORM-NAME=*STD and LOOP-NAME=*STD, the standard form entered for the specified printer is used.
Forms are created with the SPSERVE utility routine. The SHOW-SPOOL-FORMS command displays information on forms.
LOOP-NAME = *STD / <alphanum-name 1..3>
Name of the loop to be loaded into the feed information buffer (VFB/FCB).
The loop name must not include the characters '$', '&' or '@'.
The default setting *STD causes the form’s default loop to be used for the specified printer type.
Loops are stored in the PRFILE printer control file. They are created and managed using the PRM utility routine.
LOOP-NAME = <alphanum-name 1..3>
Name of the loop which is to control line feed. The length of the specified loop must match the length of the default loop of the form used.
A loop for LP- HP printers is selected from the PRFILE in accordance with the specification in the PRINTER-TYPE operand.
CHARACTER-SET = *STD / <alphanum-name 1..3>
Name of the font which is to be used for conversion.
Courier is the font which is always used. Only the font properties WEIGHT and CHARACTER-STYLE are evaluated for PDF conversion.
The table below shows the character style resulting from this (see the CHARACTER-STYLE operand in the direct parameters):
Font property WEIGTH= | Font property CHARACTER-STYLE= | |
|---|---|---|
*ITALICS | Other value | |
*BOLD | *BOLD-ITALICS | *BOLD |
Other value | *ITALICS | *NORMAL |
The default setting *STD causes the standard font to be used for the specified printer type. It can be displayed by means of SHOW-SPOOL-FORMS.
Fonts are created with the SPSERVE utility routine. The SHOW-SPOOL-CHARACTER-SETS displays information on the fonts.
PRINTER-TYPE = *HP90-PRINTER / *HP-PRINTER / *LP-PRINTER
Determines which form is to be used for PDF conversion via the printer type.
PRINTER-TYPE = *HP90-PRINTER
The form for HP90 printers is used.
PRINTER-TYPE = *HP-PRINTER
The form for HP printers is used.
PRINTER-TYPE = *LP-PRINTER
The form for LP printers is used.
LEFT-MARGIN = 20 / <integer 0..2040>
The output text is to be indented from the left margin by the specified number of millimeters. An indent of 20 millimeters is preset.
ROTATION = *NO / *YES
Specifies whether page rotation is to be executed.
ROTATION = *NO
Page rotation is not performed. Any control characters for page rotation in the file are not interpreted. The loop for conversion is determined as follows:
- When a loop is specified explicitly in the LOOP-NAME operand, the specified loop is used.
- If no loop was specified (corresponds to LOOP=*STD), the form definition is evaluated:
If a form was specified in the FORM operand, the loop defined for VERTICAL-CONTROL is used.
If no form was specified (corresponds to FORM=*STD), the standard form for the corresponding printer type (see the PRINTER-TYPE operand) is evaluated and the loop defined for VERTICAL-CONTROL is used.
ROTATION = *YES
Page rotation is executed. Any control characters for page rotation contained in the file are evaluated. The loop for conversion is determined as follows:
- When a loop is specified explicitly in the LOOP-NAME operand, the specified loop is used.
- If no loop was specified (corresponds to LOOP=*STD), the form definition is evaluated:
If a form was specified in the FORM operand, the loop defined for ROTATION-CONTROL is used.
If no form was specified (corresponds to FORM=*STD), the standard form for the corresponding printer type (see the PRINTER-TYPE operand) is evaluated and the loop defined for VERTICAL-CONTROL is used.
Return codes
(SC2) | SC1 | Maincode | Meaning/Guaranteed messages |
|---|---|---|---|
0 | CMD0001 | Command executed without error | |
1 | CMD0202 | Syntax or semantic error in command |
Note
The CCS of the specified file is used for conversion. If no file-specific CCS is defined, the CCS defined for the user ID is used. If there is no user-specific CCS, the defined system-global CCS is used.
Only those characters from the CCS are displayed which are also contained in the Windows Code Page WCP1252P (see the “XHCS” manual [51]).
Examples of how the OVERLAY operand is used
The figure below shows four examples of PDF pages on which the background picture draft.jpg is used:
(1) | Positions the background picture draft.jpg in its original size (70 x 70 mm) in the center of the page. Specification in the OVERLAY operand: overlay=*par(from-file=draft.jpg, frame=*page, horizontal-alignment=*center, vertical-alignment=*center) |
(2) | Positions the background picture draft.jpg in its original size at the top right in a user-specific frame. The frame is square (130 x 130 mm) and begins at the top left of the DIN A4 page. Specification in the OVERLAY operand: overlay=*par(from-file=draft.jpg, frame=*custom(left=0,right=80,top=0,bottom=167), horizontal-alignment=*right, vertical-alignment=*top) |
(3) | Positions the background picture draft.jpg in the same user-specific frame as in example 2. Here the picture is fitted to the frame size. As the scale of the frame matches that of the picture, no distortion occurs. Specification in the OVERLAY operand: overlay=*par(from-file=draft.jpg, frame=*custom(left=0,right=80,top=0,bottom=167), SCALE=*FIT-FRAME) |
(4) | Positions the background picture draft.jpg in the text frame and fits the picture to the frame size. In the case of a DIN A4 page with 20 mm spacing, the text frame is 170 mm wide and 257 mm high. As this scale does not match that of the picture, distortion occurs here. Specification in the OVERLAY operand: overlay=*par(from-file=draft.jpg, frame=*text, SCALE=*FIT-FRAME) |