pjs.definePrinter()

API Overview

The pjs.definePrinter() API defines a printer file in the calling scope, defines the file's record formats and fields, and creates a file instance that can be used to perform operations on the file.

When output is specified as "pdf", the report is generated using the pdfmake npm package. When output is specified as "html", an HTML document is generated. Otherwise, an IBM i printer file is used and the report is written to a spooled file. Generated PDF and HTML go into the “reports” directory in the profoundjs installation directory.

 This API serves the same purpose as an RPG printer file specification and/or output specifications (for program described printer files).

RPG Equivalent

PRINTER file specification

Important!

This API requires the Profound.js Connector module.

Parameters

  • Internal name - A String containing the desired internal file name. A variable of this name will be defined in the calling script and will be populated with a record file instance. I/O operations are then performed by calling file-specific API.

  • External name (optional) - A String specifying the external name of the file object. The name can optionally be qualified with a library. If the library is not specified, then the library list is used to resolve the file. If the external name is not specified, then the internal name is used instead. This parameter can be omitted; in this case, the file configuration is passed for parameter 2. This parameter can also be specified as an Object with the following properties in order to implement dynamic external file names:

    • field - The name of a declared character field that hold the external file object name

    • extDesc (optional) - The name of the file object to use for file discovery before the file is opened and before the field is declared. If omitted, the internal name is used. 

  • File configuration (optional) - An Object that sets file options using the property names / values shown below. If the external file name parameter is omitted, then the configuration should be passed as parameter 2. The file configuration can be passed inline or stored in an external JSON file and retrieved using the pjs.require() API. 

Element name

Element type

Description

Element name

Element type

Description

userOpen

Boolean

Set to True to enable user-controlled file open / close using the file.open() and file.close() methods. Otherwise the file will be opened automatically before this method returns and closed automatically when the calling function ends.

infDS

String

Name of a File Information data structure which will be populated with feedback information after each file method call. The data structure must be defined in the calling scope using pjs.define().

qualified

Boolean

Set to True to qualify field names with the internal file and record format names

include

Array

A list of record formats to define in the calling scope. If omitted, all record format names are included.

ignore

Array

A list of record formats to ignore. If omitted, all record format names are included.

rename

Object

A list of record formats to rename. The record format name given by each object property is set to the name given in the corresponding value.

likeFile

String

The internal name of another file defined using this method in the calling scope. This defines another instance of the file using the same configuration options.

levelIds

Array

A list of level identifiers for each record format in the file. If specified, record format level checks are performed before opening the file. Otherwise, no level checks are done.

prefix

Object / String

Defines a prefix that will be used to partially rename all the fields of the externally defined printer file. This property can be defined in 2 different ways.

  1. As an object of the following format:

    // numeric value indicating the number of characters, if any, // in the existing field names to replace with the prefix "numberOfCharsToReplace": nn, // string prefix value. If numberOfCharsToReplace is not defined or is 0, // then the prefix is appended to the beginning of the field names "prefix": "xxxx" }
  2. As a string value that will be appended to the beginning of the field names.

template

Boolean

If set to True, the the declared file cannot be opened and used for I/O, but its record formats and fields can be used as templates for field definitions by using the options 'like', 'likeRec', and 'extName' with pjs.define().

static

Boolean

If set to True, the file will hold its state across calls to the function. If the file is open when the function, then the file will still be open on the next call to the function.

alias

Boolean

If set to True, the alias (alternate) names will be used, if present, for the fields associated with the file and also for subfield names in data structures defined with the 'likeRec' option.

renameFields

String

Object containing field names to rename. The field names are given as properties of this object and their new names as values of these properties.

For example:

{ "field1": "newField1", "field2": "newField2" }

If a prefix is defined, the renameFields object properties must be defined with the prefix in place in order for those fields to be renamed.

For example, if the property prefix is defined as string "EX", then renameFields might look like this:

{ "EXfield1": "newField1", "EXfield2": "newField2" }

overflowIndicator

String

Set to the name of an indicator that will be set on when the printer file's overflow line has been printed on. For example, '*inoa', or '*in01', or 'overflow'.

recordLength

Number

Record length, for program described printer files.

output

String

Specifies whether the output is written to a PDF file, and HTML file, or a spooled file on IBM i. Specify "pdf", "html", or omit the property for spooled file output.

Generated PDF and HTML go into the “reports” directory in the profoundjs installation directory.

outputFileName

String

Specifies the desired name of the resulting PDF or HTML file

orientation

String

For PDF output, specifies the file orientation. Valid values are "landscape" and "portrait".

pageMargin (optional)

Object / Number

Specify page margins to be used for the resulting pdf according to the “unitOfMeasurement” option used. When not defined, the page margins default to 0.55 inches (1.4 cm) on all sides. Accepts the following values or properties:

  • Number - Sets all sides of the pages to an equal value, e.g.

  • Object - Sets the margins based on an object’s specific properties

    • left - sets the left margin’s size. If “right” is not defined, this will also set the right side with the same value

    • top - sets the top margin’s size. If “bottom” is not defined, this will also set the bottom side with the same value

    • right (optional) - sets the right margin’s size

    • bottom (optional) - sets the bottom margin’s size

This element corresponds to IBMI’s FRONTMGN setting for the CRTPRTF command.

printControl

String

Name of Print Control (PRTCTL) compatible (*COMPAT) data structure. The data structure must be defined in the calling scope using pjs.define().

printControlExtended

String

Name of Print Control (PRTCTL) extended data structure. The data structure must be defined in the calling scope using pjs.define().

defaultLinesPerInch

Number

For PDF output, specifies the number of lines which will fill an inch.

unitOfMeasurement

String

Specifies the unit of measurement that should be used. Set to either “inch“ or “cm”. Defaults to “inch”

records

Array

Array of record definition objects, for program described printer files. Record definition objects can have the following properties:

  • condition (String, optional) - Set to an indicator expression, such as '50 and N30' or '50 and N30 or 60 and N90'. The record will only be output if the condition is true when the record is written,

  • name (String, optional) - The name of the record being defined.

  • skipBefore (Number, optional) - Line number to skip to before printing the record.

  • spaceBefore (Number, optional) - Number of lines to advance before printing the record.

  • skipAfter (Number) - Line number to skip to after printing the record.

  • spaceAfter (Number) - Number of lines to advance after printing the record. The default is 1 if not specified.

  • linesPerInch (Number, optional) - Number of lines expected to fill an inch.

  • box (Object, optional) - Causes the record to be rendered as a box. The object can have the following properties

    • topLeft (Object) - Specifies the position of the top-left corner of the box

    • bottomRight (Object) - Specifies the position of the bottom-right corner

    • borderWidth (Number or String) - Specifies the border width of the box. Can be set to a number measured in the specified unit of measurement or “*narrow“, “*medium”, or “*wide“

    • color (String or Object) - Specifies the color of the box.

      • Expected strings: “BLK“, “BLU”, “BRN”, “GRN”, “PNK“, “RED“, “TRQ”, “YLW”.

      • RGB Object, type must be set to “*rgb“. The r, g, and b properties can be any value between 0 and 100. Example:

      • CMYK Object, type must be set to “*cmyk“. The c, m, y, and k properties can be any value between 0 and 100. Example:

  • advanced (Object, optional) - Specifies that the record should be rendered as an advanced object. The object can have the following properties:

    • type (String) - Must be set to “*jfif”

    • path (String) - Must be set to the absolute path of an image.

    • position (Object) - Must be set to the position of the resource on the page

    • size (Object, optional) - Specifies the size that the resource should take on the page, measured in the specified unit of measurement. The object should have the following properties

      • width (Number) - The width of the resource

      • height (Number) - The height of the resource

    • mapOption (String, optional) - Can be either “*p”, “*pt”, “*st”, “*ct”, or “*sl”

      • *p - Specifies that the resource should be positioned based on the top-left corner of the image and if the resource cannot fit within the optional size, throws an error

      • *pt - Specifies that the resource should be positioned based on the top-left corner of the image and if the resource cannot fit within the optional size, the image is cropped to fit

      • *st - Specifies that the resource should be positioned based on the center of the image and the image is symmetrically scaled to fit the specified size

      • *ct - Specifies that the resource should be positioned based on the center of the image and if the resource cannot fit within the optional size, the image is cropped to fit

      • *sl - Specifies that the resource should be positioned based on the center of the image and the image is asymmetrically scaled to fit the specified size

    • rotation (Number, optional) - Specifies the rotation of the image

  • fields (Array, optional) - An array of field definition objects. Field definition objects can have the following properties:

    • condition (String, optional) - Set to an indicator expression, such as '50 and N30' or '50 and N30 or 60 and N90'. The field will only be output if the condition is true when the record is written,

    • attributeSet (Array, optional) - A set of objects that contain both a condition and a set of attribute properties each. When a condition matches when the record is written, its corresponding set of attributes will be applied to the field, e.g.:

      • condition (String) - Set to an indicator expression, such as '50 and N30' or '50 and N30 or 60 and N90'. The attribute will only be applied if the condition is true when the record is written,

      • attributes (Object) - An object that contains style properties to apply to a field when the condition matches. Does not apply the attributes by default if the condition is not defined, and cannot contain another set of “attributeSet” objects. When one or more attributes have the same property to update such as “color”, the latest attribute set’s condition that matches will override the other attributes with the same property. See “Record” property description column for a list of available properties to include.

      • barcode (Object, optional) - Specifies that the field should be rendered as a barcode. NOTE: the absPos property must be set for a barcode field. The object can have the following properties:

        • barcodeID (String or Number) - Represents the type of barcode to be displayed. The valid values can be:

          • “MSI” (2), “UPCA” (3), “UPCE” (5), “EAN8” (8), “EAN13” (9), “EAN2” (22), “EAN5” (23), “CODEABAR“ (13), “CODE128“ (17), “CODE3OF9“ (1), “INTERL2OF5“ (12), “INDUST2OF5“ (10), “MATRIX2OF5“ (11), “POSTNET“ (24), “PLANET“ (24), “RM4SCC“ (26), “DUTCHKIX“ (26), “AP4SCC“ (31), “PDF417“ (30), “MAXICODE“ (29), “DATAMATRIX“ (28)

        • height (Object, optional) - Specifies the height of the barcode. The object must have the following properties:

          • type (String) - “unitOfMeasurement“ or “lines“

          • value (Number) - the vertical height of the barcode

        • orientation (String, optional) - Specifies if the barcode should be displayed horizontally or vertically. Valid values are “*HRZ” or “*VRT”, “*HRZ” is the default.

        • humanReadable (String, optional) - Specifies where and if the human readable text should included with the barcode. Valid values are:

          • “*HRI” - The human readable text will display below the barcode

          • “*HRITOP” - The human readable text will display above the barcode

          • “*NOHRI” - No human readable text

        • includeAsterisks (String, optional) - Specifies whether the asterisks are displayed with CODE3OF9 barcodes. Valid values are “*AST” or “*NOAST”

        • unitWidth (number, optional) - Specifies the width of the thinnest bar in inches

        • pdf417 (Object, optional) - This property is only valid with PDF417 barcodes and must have the following properties:

          • rowSize (Number) - The length of the rows

          • numRows (Number) - The number of rows

          • security (Number) - The level of security

        • matrix (Object, optional) - This property is only valid with DATAMATRIX barcodes and must have the following properties:

          • rowSize (Number) - The length of the rows

          • numRows (Number) - The number of rows

        • maxicode (Object, optional) - This property is only valid with MAXICODE barcodes and must have the following properties:

          • symbolMode (Number) - the symbol-mode of the maxicode barcode

    • pos (optional) - Specifies the end or start position of the field. If a number is specified, the field will end at the given position. If a string like '+1', '+2', '-1', etc. is specified, the field will start at the given offset, relative to the previous field in the record. If no position is specified, the field will start immediately after the previous field in the record.

    • blankAfter (Boolean, optional) - If set to true, the field will be set to a default value after the record is written, based on the field data type. i,.e. blank, zero, etc.

    • text (String, optional) - Constant field text.
      -Or-

    • name (String, optional) - Name of dynamic field. The field must be defined in the calling scope using pjs.define(), or from a file defined using pjs.defineDisplay(), pjs.defineTable(), or pjs.definePrinter().

    • editCode (String, optional) - Set to an IBM i edit code to format the dynamic field data.

    • editWord (String, optional) - Set to an IBM i edit word to format the dynamic field data. This property is ignored if 'editCode' is used.

    • dateFormat (String, optional) - Specifies a date format, such as "*usa"

  • html - Used to specify HTML output. Can only be used with "html" output type. Dynamic values can be specified using EJS syntax.

For PDF output, fields can also implement the following properties:

  • font (String, optional) - name of the font

  • fontSize (Number, optional) - size of the font in pt

  • lineHeight (Number, optional) - the line height (default: 1)

  • bold (Boolean, optional) - whether to use bold text (default: false)

  • italics (Bolean, optional) - whether to use italic text (default: false)

  • alignment (Sstring, optional) - the alignment of the text (‘left’ or ‘center’ or ‘right’ or ‘justify’)

  • characterSpacing (Number, optional) - size of the letter spacing in pt

  • color (String, optional) - the color of the text (color name e.g., ‘blue’ or hexadecimal color e.g., ‘#ff5500’)

  • background (String, optional) - string the background color of the text

  • decoration (String, optional) - the text decoration to apply (‘underline’ or ‘lineThrough’ or ‘overline’)

  • decorationStyle (String, optional) - the style of the text decoration (‘dashed’ or ‘dotted’ or ‘double’ or ‘wavy’)

  • decorationColor (String, optional) - the color of the text decoration

  • style (String or Array of Strings, optional) - the style name(s) as defined by the styles configuration property

  • image (String, optional) - the image source of an image to embed in the PDF

  • absPos (Object, optional) - specifies the absolute position of the field based on the unitOfMeasurement setting used, and adjusts relatively to the pageMargins setting (including the default value if pageMargins is not specified). For example:

    • This option corresponds to the POSITION keyword for RPG’s CRPRTF command.

  • textRotation (Number, optional) - specifies the angle that the text of the field should be displayed as, absPos must also be defined within the field



Exception Handling

An Error instance will be thrown with the following properties:

  • message - The IBM i message text.

  • error - The message id.

  • help - The message help text.

Examples

Using a Program Described Printer File



Using an externally described printer file



Using pjs.definePrinter() to generate a PDF

Download the example files below. Specify the "output": "pdf" property. The report definitions are in a separate JSON file for your convenience. This allows you to open it in the Visual Designer using Preview Mode, as shown in the screenshot below. 



Example Files