Description

display.screen.read() reads the user's response to a record format that was previously written with display.screen.write(). If the written screens have not been sent to the browser yet, the call sends them, waits for the user to respond, and then populates the input-capable fields, response indicators, and function key indicators for the record format. When the response has already been received by an earlier read of another format on the same screen, the fields are populated from that response without prompting the user again.

The method is typically used when several overlaid record formats are displayed; otherwise display.screen.execute() can be used in place of separate write() and read() calls. It is the equivalent of the RPG READ operation on a display file record format. To read whichever format was written last, use display.read().

Syntax

display.screenName.read()
display.screenName.read(dataStructure)

Parameters

Data structure (Object, optional) - A Profound.js data structure reference, or a plain JavaScript object. If specified, the user's response is placed into the data structure or object instead of the program's global fields. If a data structure is not qualified, wrap the parameter with the pjs.ds() API.

Return Value

Object - The display file's field collection. The return value is not normally used; the response is read from the global fields or from the data structure passed as the parameter.

The display file must be open. Calling this method on a closed display throws error 1211 (I/O operation to a closed file). Reading a format that was never written causes an error, because there is no record area to read.

Examples

Example 1: Read Overlaid Record Formats

Three overlaid record formats are written and then read. The first read() sends the screen and waits; the following reads collect the remaining input fields from the same response.

Prerequisite: a Rich Display File named mydisplay.json with three record formats named top, middle, and bottom that overlay one another.

pjs.defineDisplay("mydisplay.json");

// Write 3 overlaid screens
mydisplay.top.write();
mydisplay.middle.write();
mydisplay.bottom.write();

// Read the user's input for each format
mydisplay.top.read();              // Sends the screen and waits for the user
mydisplay.middle.read();           // Populated from the same response
mydisplay.bottom.read();

Example 2: Read the Response into a Data Structure

The response for the detail format is placed into a qualified data structure rather than the global fields, which keeps the screen data separate from the rest of the module.

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");

pjs.define("cust", { type: "data structure", qualified: true,
                     extName: { file: "customer.json", format: "detail" } });

cust.custno = 1001;
display.detail.write(cust);        // Populate the screen from the data structure
display.detail.read(cust);         // Place the response into the data structure

console.log(cust.custname);

RPG Equivalent

READ

display.screen.read()