Supported Print Controls

9.6A

Sunbelt's PDF implementation provides support for the PRTPAGE controls controls as follows:

Note:

1. Several new advanced print controls have been added for the PRTPAGE instruction to provide extended capabilities with regard to the PDF support. The new PDF print controls are defined as follows:

 

Control	Meaning
*INFO={svarslit}	This advanced print control takes a comma separated list of fields as provided in the {svarslit} data string to include additional user information in the PDF output file. Each field is composed of a field identifier assigned using a '=' character followed by field data. The data <string> field data can be specified with or without double quote characters. Each *INFO data field is optional and is not required when generating a PDF output file.   The following *INFO fields are supported:   Where: <string> A user specified string that may or may not include double quote characters. <date> A date string is specified as a YYYMMDDhhmmss format.   Fields: A=<string> //Optional Author Include an author description in the PDF output file. P=<string> //Optional Producer Include a producer description in the PDF output file. T=<string> //Optional Title Include a title description in the PDF output file. K=<string> //Optional Keywords Include keyword data in the PDF output file. Keywords are provided as simple associations in a PDF file as applied by a PDF reader. In this case, the <string> data can be specified as one or more keywords separated by a white space (blank) character. C=<date> or C //Optional CreationDate & ModDate Include the creation date and modification date field data in the PDF output file. If the 'C' syntax format is used without a '=' character, a default timestamp is included in the PDF output file. Note: Only one PRTPAGE *INFO can be executed for inclusion in a PDF output file. If a second is executed a S30 subcode 106 error is generated. All of the expected *INFO field information must be included in the first and only PRTPAGE *INFO when executed. Examples: xInfo INIT "A=Bill,C,K=#"Test Sample Plbwin#",":                  "P=Plbwin,T=Test"         PRTPAGE Prt;*Info="A=Bill,C,K=Plbwin"         PRTPAGE Prt;*Info=xInfo
*ATTACH={svarslit}	This advanced print control takes a comma separated list of fields as provided in the {svarslit} data string to specify parameters that allow an attachment to be embedded into a PDF output file along with other pertinent information. Each field is composed of a field identifier assigned using a '=' character followed by field data. The data <string> field data can be specified with or without double quote characters. The 'F' field is required while all other *ATTACH data fields are optional when embedding an attachment in a PDF output file.   The following *ATTACH fields are supported:   Where: <string> A user specified string that may or may not include double quote characters. <date> A date string is specified as a YYYMMDDhhmmss format.   Fields: C=<date> or C //Optional Creation Date Used to provide a creation date for the attachment file. If the <date> is specified by the user application, the specified <date> is a static date that is output to the PDF file. If the <date> is not specified, the <date> is the current OS creation date for the attachment file when the PDF file is created. D=<string> //Optional Description Used to provide a user specific description for the attachment to be included in the PDF output file. F=<string> //Required Filename Required to specify the fully qualified path and file name to be embedded in the PDF output file as an attachment. Please note that the attachment file must be available when the PDF file is created. I=<string> //Optional Icon Optional field to specify whether an Icon will represent the attachment by a PDF reader. The <string> for the 'I' field can be specified as one of the following decimal ASCII characters:   0 - Paperclip (default if 'I' not used) 1 - Attachment 2 - Graph 3 - Tag O=<string> //Optional Output filename Optional output file name that is created by a PDF reader for the attachment specified by the 'F' field. If the 'O' filename is not specified, the 'F' filename is used by default. P=<string> //Optional Position t:b:l:r Optional field to specify the position where an Icon for the attachment is to be placed. If this 'P' field is not specified, the Icon for an attachment is placed at the current print position. If the <string> is specified as a 't:b:l:r' data, the 't', 'b', 'l', and 'r' are specified as a decimal characters to represent the position of the Icon. In addition, when the 't:b:l:r' syntax format is being used, the 'b' and 'r' values can be specified as a 0 character. In this case, the 't' and 'l' location identifies are used to position the top/left of the attachment Icon. The 't', 'b', 'l', and 'r' decimal values represent the number of units as applied by the *UNITS for a PRTPAGE instruction. Example: P=5:15:20:35      //Use full position P=5:0:20:0      //Use top/left position T=<string> //Optional Title Optional field to specify the title to be put into the PDF output file for the attachment file. M=<date> or M //Optional Modification Date Used to provide a modification date for the attachment file. If the <date> is specified by the user application, the specified <date> is a static date that is output to the PDF file. If the <date> is not specified, the <date> is the current OS modification date for the attachment file when the PDF file is created. Note: The PRTPAGE *ATTACH print control can be executed at any point in the generation of a PDF output file. Also, the print control can be executed more than one time. The PRTPAGE *ATTACH file name as specified by the 'F=<string>' field can use a vertical bar '|' character appended to the <string> file name so an IP address or URL can be applied. This allows the attachment to be retrieved from a Data Manager. To avoid any conflicts with the field comma delimiter, the double quote (") characters can be used for the <string>. Examples of *ATTACH:      FINDFILE "tpdf.pls",write=moddate      PACK EmbedLine:                "F=#"tpdf.pls#",":                "T=tpdf,":                "D=#"PL/B Source Code#",":                "M=",moddate ;Static mod date!      PRTPAGE Prt; *ATTACH=EmbedLine        PACK EmbedLine:                "F=#"tpdf.pls|127.0.0.1#",":                "T=tpdf,":                "D=#"PL/B Source Code#",":                "M" ;Use file mod date!      PRTPAGE Prt; *ATTACH=EmbedLine
*ENCRYPT={svarslit}	This advanced print control takes a comma separated list of fields as provided in the {svarslit} data string to specify parameters that allow PDF encryption to be used for the PDF output file. Each field is composed of a field identifier assigned using a '=' character followed by field data. The data <string> field data can be specified with or without double quote characters. The *ENCRYPT fields are optional.   The following *ENCRYPT fields are supported:   Where: <string> A user specified string that may or may not include double quote characters. <date> A date string is specified as a YYYMMDDhhmmss format.   Fields: O=<string> //Optional Owner password When the owner password field is specified, this password encrypts the user password. U=<string> //Optional User password When the user password field is specified, a PDF reader will ask for input of this password. P=<string> //Optional Permissions as a set of bits This field specifies the permissions that are to be applied by a PDF reader. The <string> specified for the permissions is composed of decimal characters that represents a bit mask value. The permissions are defined as follows:   Permissions as Bit Mask:   Permissions = D7+D6+D5+D4+D3+D2+D1+D0   D0 - Reserved must be 0 D1 - Reserved must be 0 D2 - Allow document to be printed. Add a value of (4) to enable this permission. D3 - Allow the contents of the PDF document to be modified. Add a value of (8) to enable this permission. D4 - Allow text and graphics to be copied or extracted from the PDF document. Add a value of (16) to enable this permission. D5 - Allow additions and modifications for document text annotations. Also, allow interactive form fields to be filled. In addition, if the D3 permission is enabled, allow form fields to be set, created, or modified. Add a value of (32) enable this permission. D6 - Not used D7 - Not used    Where each 'Dn' represents the corresponding bit in the permissions byte bit mask value. Note: Only one PRTPAGE *ENCRYPT can be executed to invoke encryption for the PDF output file. If a second is executed a S30 error occurs. All of the expected *ENCRYPT field settings must be included in the first and only PRTPAGE *ENCRYPT when executed. A S30 error with appropriate subcode is generated if the PRTPAGE *ENCRYPT is executed after the PDF data output has already been started. Therefore, if encryption is to be used, the *ENCRYPT control should be executed after the PRTOPEN and before print data has started. Example:      PRTPAGE Prt;*ENCRYPT="O=sunbelt,P=4,U=Bill"

 

2. For FONT usage when redirecting the output to a 'pdf:' device, there are some guidelines that should be observed. There are four basic points that must be considered:

 

1. There are built-in fonts named 'Times', 'Helvetica', and 'Courier' that can be used. When a PDF reader encounters these fonts in a PDF file, the PDF reader substitutes\uses an appropriate font based on the OS platform being used. When any of these built-in fonts are used, the substituted font is not embedded in the PDF output file.

2. The PDF implementation only supports TrueType (.ttf) fonts for Advanced Print output to a 'pdf:' device. The TrueType fonts are supported by Windows and Linux OS platforms.

3. The Sunbelt runtimes support a new configuration section named '[pdffonts]' that exist in the runtime's .ini file. The keywords that are put into the [pdffonts] section allow a PL/B application to define font alias names that can be used in the PRTPAGE *FONT control. The defined font alias names are associated with TrueType (.ttf) font files. The keywords that can be defined in the '[pdffonts]' section are described as follows:

 

{fontname}[_{B|I|BI}]={fontfile}

 

These keywords allow a user to define specific font names that can be used in a PRTPAGE *FONT control. When the PRTPAGE *FONT control is processed, the runtimes can find the appropriate font that can be used when creating the 'pdf:' output file. The font mapping capability was originally implemented for the Linux runtimes. This would allow Windows TrueType (.ttf) fonts to be copied to a Linux platform and used in PRTPAGE *FONT operations on a Linux platform where the fonts are not installed on the Linux system. The font mapping capability is also available when executing in a Windows environment for some special scenarios. Keep in mind, that fonts must be installed on a Windows system when Advanced Print Preview viewing is to be done.

 

Where:

{fontname}

The {fontname} is the font name that is used in the PRTPAGE *FONT control. This font name can be any name that is desired by an PL/B developer. However, it is highly recommended that the {fontname} should be representative of the true font name expected for a associated '.ttf' file. When the expected font name normally has embedded blank characters, the blank characters should be replaced by an underscored (_) character. By using a font name that is representative of a true font name, the same program can be executed on Windows and Linux runtime to generate a PDF output file. In addition, a suffix attribute clarifier can be appended to the {fontname} keyword. The attribute suffix clarifiers are defined as '_B',', '_I', or '_BI'. These suffix identifiers allow the runtime to use the appropriate font file when a PRTPAGE *FONT control is specified with the appropriate syntax format used to specify the attributes for 'Bold', 'Italic', or 'Bold\Italic' respectively. Note, these attribute suffix clarifiers are not included in the PRTPAGE *FONT font name in a program.

Examples:

 

[pdffonts]

Courier_New=/tmp/fonts/cour.ttf

Courier_New_B=/tmp/fonts/courbd.ttf

Courier_New_I=/tmp/fonts/couri.ttf

Courier_New_BI=/tmp/fonts/courbi.ttf

 

[pdffonts]

Courier_New=c:\temp\fonts/cour.ttf

Courier_New_B=c:\temp\fonts/courbd.ttf

Courier_New_I=/tmp/fonts/couri.ttf

Courier_New_BI=/tmp/fonts/courbi.ttf

 

{fontfile}

The {fontfile} is a fully qualified path and file name where the font file is located that is to be processed when the {fontname} is encountered in a PRTPAGE *FONT control. The {fontfile} file name can be specified with a vertical bar '|' character to allow an IP address or URL of a Data Manager to be appended. The vertical bar file name syntax format allows fonts to be retrieved and used from a Data Manager.

Note:

1. When executing on a Linux system, make sure that the appropriate permissions are being used by the PLB runtime to access the mapped font files.

Example [PDFFONTS] Section Linux 'plb.ini':

 

[pdffonts]

MS_LineDraw=/home/myfonts/linedraw.ttf

Example Program Code Windows & Linux:

 

P PFILE

 

       PRTOPEN P,"pdf:", "myfile.pdf"

.

       PRTPAGE P;*FONT="Times":

               "Something in 'Times'!"

               PRTPAGE P;*FONT="MS LineDraw":

               "LineDraw is used!"

4. When using a Linux runtime, a new keyword named 'FONT_PATH={dir}[;{dir1}[;...]]' can be placed in the '[pdffonts]' section of the 'plb.ini' runtime configuration file. The 'FONT_PATH' is one or more directories that contain the TrueType fonts that can be used in the PRTPAGE *FONT control operations. When the 'FONT_PATH' keyword is being used, a Linux OS file named 'fonts.scale' must exist in each specified directory that is an Linux OS font index file that defines the font names, attributes and their associated TrueType (.ttf) files. If the Linux OS font index file does not exist, the Linux command named 'mkfontscale' can create the 'fonts.scale' index file for each directory specified in the 'FONT_PATH' keyword.

 

 

See Also: PDF Support, Printer Instructions

 




---