Data Aware Grid Channels

For BBj-specific information, see Data Aware Grid Channels - BBj.

Once the channel is passed to the grid via this function, the program should not manipulate it. Do not read from the channel, write to it, or change the record pointer.

Attribute	Description	Example
SHOW	Directs the grid to display or hide the identified grid column. If the attribute is unspecified, or the attribute is set to 1, the field is displayed. If the attribute is set to zero the field is not displayed.	This template creates two columns in the grid control: "cust_number:c(1*):SHOW=0:, first_name:c(1*):SHOW=1:, last_name:c(1*):SHOW=1:"
MASK	Specifies the field's edit mask, which follows the INPUTE control's masking conventions. (Cannot be used in conjunction with the length attribute.) Use the underscore character ('_') to indicate spaces in the mask.	The following specifies an edit mask for a North American-style telephone number: "phone:c(10):MASK=(000)000-0000:"
OMASK	Optional output mask to apply to fields when they are displayed in the grid but not being edited. If the mask is used to force spaces in the display, use the underscore character ('_') in the mask to indicate each space.	"amount:n(4):OMASK=$##,##0.00"
LABEL	Sets the field's column heading grid label. If this attribute is omitted, the field name is used by default, unless the column heading is explicitly set by the program. If spaces are required, use the underscore character ('_') in the label text. Underscores will be removed when the column heading displays.	"first:c(1*):LABEL=first_name:"
LENGTH	Limits the field length. (Cannot be used in conjunction with the mask attribute.)	"first:c(1*):LENGTH=15:"
ALIGN	Sets the column alignment. If set to 0, the data will be left-justified. If set to 1, the data will be right-justified. If set to 2, the data will be centered.	The following centers the "first" field: "first:c(1*):ALIGN=2:"
STYLE	Sets the column style. The style parameter values are identical to the values used in the style field of the grid information block. See Set Default Style, SENDMSG() Function 83 for details.	The following sets the raised button style for the "first" field: "first:c(1*):STYLE=1:"
TCOLOR	Sets the column text color, using a hex representation of the RGB() color.	The following sets the text color of the "first" field to black: "first:c(1*):TCOLOR=$000000$:"
BCOLOR	Sets the column background color, using a hex representation of the RGB() color.	The following sets the background color of the "first" field to white: "first:c(1*):BCOLOR=$ffffff$:"
CVSIN	Sets the value of the CVS() function described on page 48 of the Commands Manual) to apply to a field before it is edited.	The following strips white space before the "first" field can be edited: "first:c(1*):CVSIN=3:"
CVSOUT	Sets the value of the CVS() function to apply to the field before displaying it.	The following strips white space before the first" field is displayed: "first:c(1*):CVSOUT=3:"

If the channel is set to zero, the grid resets and is no longer data-aware. The application is responsible for closing the channel passed to the grid. To specify an SQL SELECT file channel, specify the negated value of the open channel. This convention allows the grid control to distinguish an SQL channel (opened with the SQLOPEN verb) from a channel opened with an OPEN verb. For example, if sqlchan is a value used with an SQLOPEN() verb, the following syntax might be used:

TF$=SENDMSG(sysgui,id,80,-sqlchan,template$)

If the channel is an SQL SELECT channel, the program must have already performed the SQLPREP() and SQLEXEC() verbs. The grid control will manage the SQLFETCH() calls.

The data-aware grid works with at least two channels: the input channel passed by Set Channel and Template, SENDMSG() Function 80, and the channel for the temporary file created to manage the displayed grid. If the grid is expected to handle a very large number of records, ensure that the TMP, TEMP, or TMPDIR environment variables are set to a location that can handle the temporary file, which is removed when the grid is destroyed or another call is issued to the grid to set a new channel. The temporary file channel references a single-keyed MKEYED file that contains the query result for Visual PRO/5 SELECTs or SQL SELECTs, or it references a single-keyed MKEYED file that is an index file for an editable multi-keyed file. If the grid allows editing, two more channels may be used to update and validate records. The application should be designed to support the considerable resources needed to operate a data aware grid control.

For SQL SELECT and Visual PRO/5 SELECT channels performing SELECT operations on read-only files, or for MKEYED file channels that lack write permissions, the grid is set to read-only mode. A grid can also be set to read-only by sending the $01$ value to the grid with Perform Data-Aware Function - Grid SENDMSG() Function 81.

For a writable MKEYED file or SELECT channel that refers to a writable MKEYED file, the grid can be edited unless it has explicitly been set to read-only. The update operation is governed by the rules described below and is performed on the file being used by the SELECT channel. This is done by opening the file internally. This internal channel is closed automatically when the grid is destroyed or a new channel is set using this message.

Data is read from the channel according to the initial channel setup. Therefore, for a SELECT or SQL SELECT channel, the order is determined by the sort clause that is part of the operation itself. If the channel is a multi-keyed MKEYED file, the user program sets the key chain and the data is read in that order. Usually, only read records are issued on the input channel.

Channel Insert/Delete/Update Rules

The following describes the rules for writable MKEYED files or SELECT channels that refer to writable MKEYED files. For all the operations described below, an EXTRACT RECORD is performed before the operation takes place.

If a locked record is encountered during any of the initial EXTRACTs, the operation is canceled and an ERROR Notify event message is sent to the application. Duplicate or Missing errors suspend the operation. Deleting a row deletes the corresponding record in the file and sends a ROWDELETE Notify event (Notify code 25) to inform the program of the deletion.

Records to be removed are first extracted on the update channel, then removed. A tag in the header of the affected row displays a tag, indicating that the row has been removed. No further editing is allowed on the row. If the extract fails because of a duplicate or missing record, the record is simply marked as "removed" and an error message is sent to the application.

Inserting a row inserts a record in the corresponding file and puts the inserted row into edit mode on the first column. The record is automatically updated when the user moves focus from the inserted row. If the record is successfully written to the file, a ROWINSERT Notify event message is sent to inform the program of the record insert. If the record cannot be written a message box prompts the user to abort the insert operation and delete the new row or continue entering information into the row. The default text is "Record Incomplete! Continue editing?". This text can be changed with Set Continue Message - Grid SENDMSG() Function 82. If the user aborts the insert, the grid sends a ROWCANCEL Notify event to inform the program of the insert cancellation.

Records can only be inserted at the end of the grid. Therefore, if an insert operation is initiated, the grid moves to the end of the data that has already been read and displays a new empty row that is tagged "new" in the row header. The grid then goes into an update state without an existing record.

When the application determines the user wants to edit a row/record, it should send a message to the cell(s) via Start Edit - Grid SENDMSG() Function 31 to enter edit mode. During editing, the grid locks the record on a verify channel, and it is released when the editing is completed via a cancel command from the application or the user, or when the user changes focus to a different row. If the update is not canceled, the new record is extracted to ensure that it does not already exist. If the record exists, the current row is forced back to the user row and an ERROR notify message is sent to the application for handling. If the new record does not already exist, the old record is removed on the verify channel and the new record is written. The grid sends a ROWUPDATE Notify event to inform the program of the update. The return value is a one-byte string that indicates the success or failure of an operation; $01$ indicates success, $00$ indicates failure.

Visual Clues During Grid Operations

The grid will give two types of visual clues to the user indicating the status of records: record status icons in the left column or row header, and asterisks in all fields of unavailable records. Records that are locked on another channel display all fields as asterisks, and a locked icon displays in the row header, if there are row headers, or the left column if there are no row headers. When a new record is added, an add icon displays in the left column if there are no row headers. This icon persists after the record is added. If there are row headers, no icon displays. When a record is edited, an update icon displays in the left column if there are no row headers. This icon persists after the editing is completed. If there are row headers, no icon displays.

After a record has been deleted, all fields display as asterisks, and a delete icon displays in the row header, if there are row headers, or the left column if there are no row headers. The only way to remove a deleted record's row from the grid display is to disconnect the grid from the data channel by sending a SENDMSG() Function 80 with a channel number of zero, then reattach the grid with another SENDMSG() Function 80 (see the Data-Aware Grid Tutorial for a example of this). The icons displayed after a record is added or edited can be removed with the same process.

Errors

!ERROR=1 is returned if the minimum required record size for the specified template is larger than the file's record size.

!ERROR=14 is returned if the channel number specified is not open.

!ERROR=26 is returned if the template includes any incorrect template definition syntax.