Grid Management Library - Variable Names / Calling GML Programs

Description

All GML variables begin with the letters GML. The variables associated with calling two of the three GML programs are as follows, and are used as part of the calling program argument lists:

Program GML_I is called by the workspace program one time during program startup as indicated by the following:

CALL "GML_I",SYSGUI,GML_INIT$,GML$,GML_GM$[ALL],GML_GC$[ALL],GML_GR$[ALL],GML_SET$

SYSGUI is the channel number of the SYSGUI Window.

Program GML_M is called by the workspace program when a notify event associated with object type 107 (grid control) occurs, as in the following example:

IF EVENT.OBJTYPE%=107 THEN IF EVENT.CODE$="N" THEN GOSUB GML_M
GML_M:
CALL "GML_M",SYSGUI,EVENT$,NOTICE$,GML_SET$,GML_TPL$,GML$,
             GML_GM$[ALL],GML_GC$[ALL],GML_GR$[ALL]

EVENT$ contains the event values received from the event queue template.

NOTICE$ contains values received from the grid notice template.

Program GML provides the interface to the Grid control(s) through the use of the GML template and associated procedures. The GML procedures have been created in a manner that minimizes the amount of code a developer is required to write when calling the GML program. The procedure name is also the label reference in the GML (called) program as appearing in the following example that initializes the GML_TPL$ template:

load the GML.SET% variable with the appropriate grid set number: GML.SET%=1

initialize the GML_TPL$ template: CALL "GML::TPL_PREP"

Since calling the GML program does not use an argument list, the called program (GML) shares all variables with the calling program. For this reason, program GML only contains variables that begin with the letters GML. Therefore, variables beginning with the letters GML must be considered as reserved for use by the GML and consequently not assigned by the developer for use in the application code.

If program GML is called from a called program, that program must have been called with the following variables as part of the argument list:

GML_TPL$,GML$,GML_GM$[ALL],GML_GC$[ALL],GML_GR$[ALL]

example:

REM MAIN_PROGRAM
.
CALL "PROGRAM_1",A$,B$,GML_TPL$,GML$,GML_GM$[ALL],GML_GC$[ALL],GML_GR$[ALL]
REM PROGRAM_1
.
ENTER A$,B$,GML_TPL$,GML$,GML_GM$[ALL],GML_GC$[ALL],GML_GR$[ALL]
.
.
GML.SET%=1
CALL "GML::TPL_PREP"

GML: Pre-Assigned Values

When program GML_I is called during program startup, template GML$ is loaded with values that can be used with certain procedures that relate to changing cell attributes. The field names are self explanatory and are as follows:

GML Start-Up: Calling Program GML_I

If an invalid value or a problem is encountered during start-up when calling program GML_I, variable GML.FLAG% will be assigned a negative value that corresponds to one of the following:

If a run time error occurs when calling program GML, GML_M, or GML_I, template variable GML.FLAG% will contain a negative value that corresponds to the VPRO/5 error code +1000. As an example, if program GML_I is called and an !ERROR 17 occurs (Invalid Parameter), the GML.FLAG% variable will contain a value of –1017 which will equate to –(Error Value+1000). In addition, template variable GML.NOTIFY% will contain a value that corresponds to the line number where the error occurred in program GML_I. However, if a run time error occurs in program GML_I prior to initialization of the GML$ template, testing the values in GML.FLAG% and GML.NOTIFY% would prove unsuccessful since these variable names would not exist. Therefore, a global variable STBL("GML_RT_ERROR") is also used to pass error information to the application. If a run time error occurs, as in the following Call/Enter Mismatch example, this global variable will contain the actual error number and error line number:

CALL "GML_I"
PRINT STBL("GML_RT_ERROR")
                            
PROGRAM: GML_I, ERR: 36, LINE: 130, 12/30/99 AT 14:12:09

To insure proper start-up, the values in variables GML.FLAG% and STBL("GML_RT_ERROR") should be checked by the application immediately following the call to program GML_I.

Executing a GML Procedure

A procedure is always executed by calling program GML. If an invalid value or a problem is encountered during execution of the procedure by program GML, the variable GML.FLAG% will be assigned a negative value that corresponds to one of the following: