Description

pjs.defineDisplay() creates a Rich Display File object that the module uses to show screens and read the user's response. Each record format in the file becomes a screen object on the display object (for example display.detail), and each grid becomes a grid object that is used with the Grid API. By default, the fields bound to the record formats are also declared as strongly typed global fields in the module, so they can be referenced directly by name.

Unless the userOpen option is set, the display file is opened as soon as it is defined. It stays open until display.close() is called or the defining function ends (see the static option).

Syntax

pjs.defineDisplay(name, fileName)
pjs.defineDisplay(name, fileName, configuration)
pjs.defineDisplay(fileName)
pjs.defineDisplay(fileName, configuration)

Parameters

Name (String, optional) - The object name used throughout the module to reference the Rich Display File. A common convention is "display", as used throughout this documentation. If the name is omitted, the object name is the JSON file name without its extension (for example pjs.defineDisplay("customer.json") creates an object named customer).
File name (String) - The name of the JSON file that contains the Rich Display definition created with the Visual Designer. The file is searched for in the modules directory of the Profound.js installation, and the name can be qualified with a subdirectory (for example "subdir/mydisplay.json"). A name that starts with ./ is resolved relative to the module that makes the call, and an absolute path can also be given. If the name is not qualified, the pathlist is used to search for the file. The .json extension is optional.
Configuration (Object, optional) - Configuration options for the Rich Display File. See the table below. An unknown property name causes an error when the display is defined.

Configuration Object

Property	Type	Description

Property	Type	Description
`ignore`	Array	Array of record format names that should be ignored. The module runs as if the listed record formats did not exist. When `ignore` is specified, `include` should not be specified.
`include`	Array	Array of record format names that should be included; all other record formats in the Rich Display File are ignored. When `include` is specified, `ignore` should not be specified.
`infDS`	String	Name of a data structure to use as the File Information Data Structure for the Rich Display File. The following positions in the data structure are populated automatically: 1-8 (Character) or special `file` - The first 8 characters of the file name. 9-10 (Character) - Open indicator (`1` when the file is open). 16-21 (Character) - Last operation code, for example `OPEN F` for an explicit open or `OPEN I` for an implicit open. 38-45 (Character) or special `record` - The first 8 characters of the record format name being processed. 81-82 (Character) - Open Data Path type. `DS` for Rich Display Files. 83-92 (Character) - Name of the file being opened. 93-102 (Character) - Name of the library containing the file. 197-206 (Character) - Name of the requester device (the job name). 261-270 (Character) - Record format name. 369-369 (Unsigned integer - length: 3) - AID byte value. 370-370 (Unsigned integer - length: 3) - Cursor row. 371-371 (Unsigned integer - length: 3) - Cursor column. 376-377 (Unsigned integer - length: 5) - Subfile relative record number (RRN). 378-379 (Unsigned integer - length: 5) - Top record RRN. 380-381 (Unsigned integer - length: 5) - Number of records in the subfile. 382-382 (Unsigned integer - length: 3) - Active window cursor row. 383-383 (Unsigned integer - length: 3) - Active window cursor column. Subfields beyond the declared length of the data structure are not populated, so the data structure only needs to be as long as the positions the program uses.
`flagDS`	String	Name of a data structure that holds the display file indicators (flags). The data structure contains the conditioning and response indicators passed to and from the display. If not specified, the module's built-in indicator array is used.
`mode`	String	Controls how field names are exposed to the module: `"compatibility"` - All field names for this Rich Display File are converted to lower case. `"case-sensitive"` - Field names keep the same case as the bound properties in the Rich Display File. If omitted, `"compatibility"` is used; the default can be changed with the defaultMode option in the Profound.js configuration file.
`prefix`	Object / String	Defines a prefix that partially renames all fields of the Rich Display File, in the same way as the RPG `PREFIX` keyword. It can be specified in two ways: As a string that is added to the beginning of every field name. As an object with the properties `prefix` (the string to add) and `numberOfCharsToReplace` (the number of leading characters, if any, to remove from each field name before the prefix is added). If `numberOfCharsToReplace` is omitted or `0`, the prefix is simply added to the beginning of the field names. `{ numberOfCharsToReplace: 2, // remove the first 2 characters of each field name... prefix: "cu" // ...and add "cu" in their place }`
`rename`	Object	Renames record formats. Each property is an existing record format name and its value is the new name to use in the module. `{ "format1": "newFormat1", "format2": "newFormat2" }`
`renameFields`	Object	Renames individual fields. Each property is a record format name; its value is an object whose properties are the existing field names and whose values are the new names. `{ "format1": { "field1": "newField1", "field2": "newField2" } }` If a `prefix` is also defined, the `renameFields` entries must use the prefixed names. For example, if `prefix` is `"EX"`: `{ "format1": { "EXfield1": "newField1", "EXfield2": "newField2" } }`
`rrnFields`	Object	Names the relative record number (RRN) field for each grid (subfile) record format. Each property is a grid record format name and its value is the name of the field that receives the RRN. The fields must be defined in the module. `{ "sfl": "rrn", "sfl2": "rrn2" }`
`static`	Boolean	If `true`, the display file remains open until display.close() is called or the activation group ends. If `false` (the default), the display file remains open until display.close() is called or the function that defined it exits.
`userOpen`	Boolean	If `true`, the display file is not opened implicitly. The module must open it with display.open() before any screen is used, in the same way as the RPG `USROPN` keyword. If omitted, `false` is assumed and the display file is opened as soon as it is defined.
`alias`	Boolean	If `true`, the alias (alternate) names are used, when present, for the fields of the file and for the subfield names of data structures defined with the `likeRec` option.
`prefixWithFormatName`	Boolean	If `true`, every field is created with the name of its record format as a prefix, separated by an underscore (for example `ctl_field1`). This allows two record formats that contain a field with the same name to be used independently.
`preciseDecimal`	Boolean / Number	Overrides the global preciseDecimal configuration option for the packed and zoned decimal fields defined by this display file.

Return Value

Object - The display object. The object is also stored under the given name, so the return value does not normally need to be captured.

Examples

Example 1: Define and Display a Screen

The simplest use: define the display with the object name display, set a field value, and show a screen. The custname field is created as a global field by pjs.defineDisplay() because it is bound to a widget in the record format.

Prerequisite: a Rich Display File named customer.json with a record format named detail that contains the fields custno, custname, and balance, and a button whose response property is bound to an indicator field named exit.

pjs.defineDisplay("display", "customer.json");   // Creates display.detail and the global fields custno, custname, balance, exit

custname = "ACME Corporation";     // Set an output field...
display.detail.execute();          // ...show the screen and wait for the user's response

console.log("The user entered customer number " + custno);

Example 2: Omit the Object Name

When the name parameter is omitted, the object name defaults to the file name without the extension, so test.json creates an object named test.

Prerequisite: a Rich Display File named test.json with a record format named fmt.

pjs.defineDisplay("test.json");    // The object name defaults to "test"

// Logic setting initial values, etc...

test.fmt.execute();

// Process the screen submission...

Example 3: Use a Prefix and Rename a Field

Adds the prefix xx to every field name and then renames one of the prefixed fields. The module refers to the field as newField even though the Rich Display File calls it field1.

Prerequisite: a Rich Display File named test.json with a record format named ctl that contains a character field named field1.

pjs.defineDisplay("test.json", {
  prefix: "xx",                   // field1 becomes xxfield1...
  renameFields: {
    ctl: {
      xxfield1: "newField"        // ...and xxfield1 is then renamed to newField
    }
  }
});

pjs.define("data", { type: "char", length: 50, varying: true });

test.ctl.execute();

// The module refers to newField, even though the field is named field1 in the Rich Display File
data = pjs.char(newField);

Example 4: Use a File Information Data Structure, RRN Field, Renamed Format, and User Open

Defines a subfile display with several options: the FILEFBK data structure receives file feedback, the RRN field receives the grid's relative record number, the ctl format is renamed to ctlx, and the file is opened and closed explicitly.

Prerequisite: a Rich Display File named subfiled.json with a control record format named ctl and a grid whose record format name is sfl, with the fields product, description, and quantity bound to its columns.

pjs.defineDisplay("display", "subfiled.json", {
  infDS: "FILEFBK",             // File information data structure
  rrnFields: {
    sfl: "RRN"                  // The RRN of the sfl grid is placed in the RRN field
  },
  rename: {
    ctl: "ctlx"                 // Refer to the ctl format as display.ctlx
  },
  userOpen: true                // Do not open the file until display.open() is called
});

pjs.define("RRN", { type: "integer" });
pjs.define("FILEFBK", { type: "data structure", elements: {
  "FILE":     { special: "*file" },                    // Positions 1-8: file name
  "OPEN_IND": { type: "boolean" },                     // Positions 9-10: open indicator
  "RCD_FMT":  { type: "char", from: 261, to: 270 }     // Record format name
}});

display.open();

// Clear and load the grid here...

display.ctlx.execute();      // Show the renamed control format
console.log("Last record format used: " + RCD_FMT);

// Process the screen submission...

display.close();

Example 5: Prefix Fields with the Format Name

Two record formats each contain a field named field1. With prefixWithFormatName the fields become ctl1_field1 and ctl2_field1, so both can be set independently.

Prerequisite: a Rich Display File named test.json with two record formats named ctl1 and ctl2 that both contain a character field named field1.

pjs.defineDisplay("display", "test.json", {
  prefixWithFormatName: true
});

// Each field1 can now be referenced individually
pjs.set("ctl1_field1", "Field1 in format ctl1");
pjs.set("ctl2_field1", "Field1 in format ctl2");

display.ctl1.write();
display.ctl2.execute();

RPG Equivalent

File specification (DCL-F) for a WORKSTN file.

pjs.defineDisplay()