The Grid API contains the methods that a Profound.js module uses to load, read, change, and remove the records of a grid (subfile) in a Rich Display File. A grid object is created for every grid in a display file defined with pjs.defineDisplay(), and it is referenced through the display object using the grid's record format name property. For example, if display.json contains a grid whose record format name is mygrid, the grid object is display.mygrid.

The methods fall into two styles:

• Subfile-style methods - write(), update(), getRecord(), readChanged(), and clear() work one record at a time through the program's global fields (or a data structure), in the same way as the RPG WRITE, UPDATE, CHAIN, READC, and SFLCLR operations. These are used heavily in applications converted from RPG.

• Array-style methods - addRecords(), getRecords(), find(), filter(), sort(), and so on work with JavaScript objects and arrays, and are modeled on the standard JavaScript Array methods. Each record is a JavaScript object with one property for each field in the grid.

The methods are listed below, grouped by what they do. Each method has its own page with the syntax, parameters, return value, and working examples.

• display.grid.write() - Writes a record to the grid from the global fields or a data structure (RPG WRITE).

• display.grid.addRecords() - Adds an array of record objects to the end of the grid.

• display.grid.push() - Adds one or more record objects to the end of the grid.

• display.grid.unshift() - Inserts one or more record objects at the beginning of the grid.

• display.grid.insert() - Inserts one or more record objects at a given index.

• display.grid.replaceRecords() - Clears the grid and then adds an array of record objects.

• display.grid.clear() - Removes all records from the grid.

• display.grid.setGridRecNumField() - Names the field that holds the relative record number (RRN).

• display.grid.getRecord() - Retrieves a record by relative record number into the global fields or a data structure (RPG CHAIN).

• display.grid.readChanged() - Retrieves the next record that was changed by the user (RPG READC).

• display.grid.update() - Updates the record most recently retrieved with getRecord() or readChanged() (RPG UPDATE).

• display.grid.getRecords() - Returns a copy of all grid records as an array of objects.

• display.grid.getRecordCount() - Returns the number of records in the grid.

• display.grid.getFieldNames() - Returns the names of the fields in the grid.

• display.grid.getCopyOfData() - Returns a copy of the raw grid data as an array of arrays.

• display.grid.slice() - Returns a copy of a range of grid records.

• display.grid.delete() - Removes a record by index or by relative record number.

• display.grid.pop() - Removes and returns the last record.

• display.grid.shift() - Removes and returns the first record.

• display.grid.splice() - Removes and/or inserts records at a given index.

• display.grid.applyFilter() - Keeps only the records that pass a test function.

• display.grid.find() - Returns the first record that passes a test function.

• display.grid.findIndex() - Returns the index of the first record that passes a test function.

• display.grid.filter() - Returns an array of the records that pass a test function.

• display.grid.every() - Tests whether all records pass a test function.

• display.grid.some() - Tests whether at least one record passes a test function.

• display.grid.forEach() - Runs a function once for each record.

• display.grid.map() - Returns a new array built by running a function on each record.

• display.grid.applyMap() - Replaces the grid records with the results of running a function on each record.

• display.grid.reduce() - Reduces the grid records to a single value.

• display.grid.sort() - Sorts the grid records by field name or with a compare function.

The array-style methods pass records to your code, and accept records from your code, as plain JavaScript objects. Keep the following in mind:

• Property names - Each property is named after a field in the grid. When a record object is added to the grid, any grid field that has no matching property is stored as blank.

• Records are copies - Each record object is a copy of the grid record. Numeric fields (packed, zoned, and float) are returned as JavaScript numbers, character fields as strings, and indicator fields as the strings "1" and "0". Changing the object does not change the record in the grid. To change the grid, use a method that writes back to it, such as applyMap(), replaceRecords(), or update().

• Indexes and relative record numbers - Indexes used by the array-style methods are zero-based, so the first record is index 0. Relative record numbers used by the subfile-style methods are 1-based, so the first record is RRN 1.

• The display must be open - All grid methods require the display file to be open; calling them on a closed display throws error 1211 (I/O operation to a closed file).

• Asynchronous methods - The subfile-style I/O methods and the methods that take a callback function are asynchronous. Inside a Profound.js module the framework waits for them automatically, so they are called exactly as shown in the examples. The callback passed to a method such as forEach() or find() may itself be an async function; the records are then processed one at a time, in order.