Attached File
The Grid Management Library (GML) can be configured to associate mkeyed file records to rows within a main grid control. This relationship, referred to as "attaching" a file, is one in which the GML manages the reading of the data channel, while the individual application formats the record data and passes the formatted data back to the GML for display within the grid. The current revision of GML supports Mkeyed files with up to 32,000 active keys. The key being used to read through the file must be unique; the attached file may not contain control characters such as $0A$ as part of the key or record data.
The attached file mode is determined by the information contained in variable GML_RCD.KEY$
(Attached File) - a: Mode 1: Upon initialization (attaching of the file) the vertical scroll bar is proportioned to the number of records in the entire file. If records are added or deleted after the file is attached, the vertical scroll bar proportioning is updated to the new number of records within the file.
(Attached File) - b: Mode 2: Attached file mode 2 is used to read through a portion of a file. Upon initialization, the application provides the start key to the GML, which is used to identify row 1 of the grid. Because an end key is not provided, the end key is the last active key of the file. If records are added or deleted after the file is attached, the vertical scroll bar proportioning is updated to the new number of records within the file. As records are read in a forward direction the application indicates, through a flag to the GML, when the last record for the portion of the file has been displayed. The reading of the file is then limited to the records between the start key and the last record designation. The application may change the last record designation each time the file is read in a forward direction.
(Attached File) - c: Mode 3: Attached file Mode 3 is used to read through a portion of a file, however, additions or removal of records between the designated start and end keys is not allowed. Upon initialization, the application provides the start key and end key to be used as markers by program GML_F when reading forward and backwards through the file. Since the start and end keys are provided, the vertical scroll bar is proportioned based on the number of records between these two points in the file. In mode 3 the proportioning is set at initialization and cannot be changed, therefore, the application must control (prevent) additions to the file between the designated start and end keys.
(Attached File) - d: Start-Up: A template named GML_RCD$ is used to interface between the application and the program (GML_F) that manages the reading of the data channel. This template is obtained by using the GML attached file procedure ATTACH_FILE. This procedure may be used at any time after the GML has been initialized.
Prior to the using the ATTACH_FILE procedure, the GML_TPL$ template must be initialized as in the following:
7580 GML.SET%=1
7590 CALL "GML::TPL_PREP"
Next, the ATTACH_FILE procedure is used to obtain the GML_RCD$ template. The file to be
attached must be open at the time this procedure is used:
7600 CALL "GML::ATTACH_FILE"
After execution of this procedure, the GML_RCD$ template is returned to the application by program GML, at which time the file channel is assigned by the application to variable GML_RCD.FLAG%:
7610 GML_RCD.FLAG%=ATTACHED_FILE_CHANNEL
When it is provided to program GML_F by the application at the time of initialization of the attached file configuration:
If variable GML_RCD.KEY$ is null, then the attached file mode is 1 (the entire file).
Example: (Attach FileMode = 1)
7620 GML_RCD.KEY$=""
If variable GML_RCD.KEY$ contains key data, and variable GML_RCD.KEY$ does not contain an embedded $00$, then the key data is used as the start key. The attached file mode is set a 2 (a portion of the file with the full scope undetermined) as in the following:
Example: (Attach File Mode =2)
7620 GML_RCD.KEY$="0091233"
When GML_RCD.KEY$ contains key data, and variable GML_RCD.KEY$ contains an embedded $00$, then the key data is used as the start key, and end key. The attached file mode is set a 3 (a portion of the file with the scope determined by the start and end key) as in the
following:
Example: (Attach File Mode = 3)
7620 GML_RCD.KEY$="0091233"+$00$+"0187623"
After the GML_RCD.KEY$ variable is assigned the key data by the application, program GML_F
is called with a line label reference of INIT as follows:
7630 CALL "GML_F::INIT",GML$,GML_GRL$,GML_RCD$
When program GML_F is called, it sets up three vertical scroll bars which are positioned on the right side of the grid. Depending on the attached file mode, two of the three scroll bars are made visible.
After attached file initialization, program GML_F is called (without a line label reference) to read the first group of records that will be displayed on the grid. Since program GML_F must be called from several points within the application, the code segment containing the call should be placed in a subroutine, as in the following:
7640 GOSUB GML_F
.
.
9050 GML_F:
9160 CALL "GML_F", E$, NOTICE$, GML_TPL$, GML$,GML_GM$[ALL],
9160:GML_GC$[ALL], GML_GR$[ALL], GML_GRL$, GML_RCD$, GML_DATA$
When program GML_F is called for the first time with the above argument list, it reads the amount of records equal to the amount of visible lines on the grid.
(Attached File) - e: Read Cycle: Each time a read occurs, program GML_F places the record data into variable GML_DATA$, the record key into template variable GML_RCD.KEY$, and the grid row number into template variable GML_RCD.ROW_N%.
The application then moves the record data located in GML_DATA$ into the record template specific to the file being read, formats the data, and then loads the GML_TPL$ template variables.
Program GML_F is then called at which time the data in the GML_TPL$ template is loaded into the grid. This cycle (referred to as the read cycle) continues until the read file activity is
completed by program GML_F.
Upon completion, program GML_F places a 0 into variable GML_RCD.ROW_N% which signals the end of the read activity.
(Attached File) - f: Flag Values: Template variable GML_RCD.FLAG% can be used to direct program GML_F to perform a specific action when it is called from an application.. In some cases additional information must also be provided in template variable GML_RCD.KEY$, as noted:
GML_RCD.FLAG% = 1
When the attached file mode is 2 (a portion of the file is being read, with the full scope undetermined), setting the GML_RCD.FLAG% value to 1 indicates to program GML_F that the most recent row (record) displayed on the grid during the read cycle is the last record to be read.
GML_RCD.FLAG% = 10
A flag value of 10 is used to direct program GML_F to position the reading of the file to the key that was designated as the first (start) key when the attached file initialization occurred.
GML_RCD.FLAG% = 11
A flag value of 11 is used to direct program GML_F to position the reading of the file to the key that was designated as the last (end) key when the attached file initialization occurred.
GML_RCD.FLAG% = 18
A value of 18 is used to direct program GML_F to find the key that has been assigned to variable GML_RCD.KEY$, and position the reading of the file to that key as the first row (record) of the
grid display.
GML_RCD.FLAG% = 19
A value of 19 directs program GML_F to refresh the current display by re-reading the records and repainting the grid.
GML_RCD.FLAG% = 20
A value of 20 is used to direct program GML_F to find the key that has been assigned to variable GML_RCD.KEY$, and position the reading of the file to that key as the first row (record) of the grid display if it is not currently displayed within the grid. If the key is currently displayed, the highlighted cell on the grid is moved to the row containing the key.
The actions performed by program GML_F for a flag value of 20 are similar to using a flag value of 18, with the exception that a flag value of 18 always results in displaying the key on the first row of the grid, even if it is currently being displayed on other than row 1.
GML_RCD.FLAG% = 21
A value of 21 directs program GML_F to perform a read cycle equal to the number of visible rows (page) on the grid, in the forward direction.
GML_RCD.FLAG% = 22
A value of 22 directs program GML_F to perform a read cycle equal to the number of visible rows (page) on the grid, in the backward direction.
g. Multiple Grid:
Multigrid capability can be access through the Gml.Set variable. Gml.Set% refers to the current grid being managed by the GML. If you are using GML Multigrid capabilities the only difference between version 2.0 and 2.1 is that you should use variable GML_RCD.KEY$[GML.SET%] instead of GML_RCD.KEY$.
h: Set_Rows Behavior:
SET_ROWS has been enabled to work in the attached file mode. Now you can directly display the last page in a selected range including blank lines, for input.
i: Highlight Rows:
Highlight in the past was made automatically by the program GML_F. In order for the program GML_F to highlight rows, the variable GRL.FLAG_HIGHLIGHT$[SET%] has to be set to 1. If this variable is not set to 1, the program GML_F will not highlight rows when one of the scrollbars is positioned.
j: Skipping Records:
(Mode 1 and 3) In those modes the user can skip records that do not match specific criteria. The technique is based in a calculation of the amount of records that have been skipped. When a record of the file does not match a specific criteria the variable gml_rcd.flag% have to be set to -14. When this variable is set to -14 the current record is not shown in the grid.