Global features: Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (more conversion cleanup)
m (mixed case for statements)
 
(21 intermediate revisions by 3 users not shown)
Line 1: Line 1:
<div class="toclimit-3">
==Overview==
==Overview==
<p>
<p>
<var class="product">Model&nbsp;204</var> offers several global features to store information in memory so that it is not automatically cleared between requests. The memory area for storing global information is a <var class="product">Model&nbsp;204</var> internal work area or server table called global table or GTBL. </p>
<var class="product">Model&nbsp;204</var> offers several global features to store information in memory so that it is not automatically cleared between requests. The memory area for storing global information is a <var class="product">Model&nbsp;204</var> internal work area or server table called the <b>global table</b> or GTBL. </p>
<p>
<p>
The global features are:</p>
The global features are:</p>
<ul>
<ul>
<li>Global string variables</li>
<li>Global string variables</li>
<li>Global objects</li>
<li>Global objects
<ul>
<li>Global found sets and lists</li>
<li>Global screens, images, and menus</li>
<li>Global positions</li>
</ul></li>
</ul>
</ul>
<p>
<p>
Global found sets and lists</p>
Global information is available only to the user who creates it. </p>
<p>
Global screens, images, and menus</p>
<p>
Global positions</p>
<p>
Global information is available only to the user who creates it.</p>
   
   
===GTBL internal work area===
===GTBL internal work area===
Line 23: Line 23:
For a discussion of GTBL space requirements, see [[Large request considerations#GTBL (global variable table)|GTBL (global variable table)]].</p>
For a discussion of GTBL space requirements, see [[Large request considerations#GTBL (global variable table)|GTBL (global variable table)]].</p>
<p>
<p>
Global items are stored in a specific order in GTBL. As shown in [[#GTBL internal work area|GTBL internal work area]], the area that stores global string variables is at the beginning of the table, and is built from the top down. The area that stores global objects is at the end of the table and is built from the bottom up. The unused or free space is between these two areas.</p>
Global items are stored in a specific order in GTBL. As shown in [[#GTBL internal work area|GTBL internal work area]], the area that stores global string variables is at the beginning of the table, and is built from the top down. The area that stores global objects is at the end of the table and is built from the bottom up. The unused or free space is between these two areas.  
[[File:Storage_of_global_vars_in_GTBL.jpg]]
</p>
<p class="caption" style="width:450px">Storage of global variables and global objects in GTBL </p>
====Storage of global variables and global objects in GTBL====
<p class="figure">[[File:Storage_of_global_vars_in_GTBL.png|450px]] </p>
 
==Global string variables==
==Global string variables==
<p>
<p>
Line 34: Line 33:
<ul>
<ul>
<li>Pass information from one request to another request</li>
<li>Pass information from one request to another request</li>
</li>
<li>Include procedures conditionally at the <var class="product">Model&nbsp;204</var> command level</li>
<li>Include procedures conditionally at the <var class="product">Model&nbsp;204</var> command level</li>
</li>
<li>Tailor a request dynamically</li>
<li>Tailor a request dynamically  
</li>
</li>
</ul>
</ul>
<p>
<p>
As of Version 5.1, you can increase the speed and reduce the CPU time to find and update a global string variable by setting the <var>[[GTBLHASH parameter|GTBLHASH]]</var> parameter to a nonzero value. The GTBLHASH parameter specifies the number of buckets allocated in the global string variable section of GTBL.
As of Version 5.1, you can increase the speed and reduce the CPU time to find and update a global string variable by setting the <var>[[GTBLHASH parameter|GTBLHASH]]</var> parameter to a nonzero value. The <var>GTBLHASH</var> parameter specifies the number of buckets allocated in the global string variable section of GTBL.
When GTBLHASH is a nonzero value, and you set or get a global string variable, the global string variable name is hashed to determine the bucket in which the name is located. </p>
When <var>GTBLHASH</var> is a nonzero value, and you set or get a global string variable, the global string variable name is hashed to determine the bucket in which the name is located. </p>
<p>
<p>
This reduces the overall amount of data that must be scanned to find a global string variable or must be moved when a value is deleted or changes in size. If GTBLHASH=0, global string variables are processed as in pre-5.1 versions of <var class="product">Model&nbsp;204</var>.
This reduces the overall amount of data that must be scanned to find a global string variable or must be moved when a value is deleted or changes in size. If <var>GTBLHASH</var> is 0, global string variables are processed as in pre-5.1 versions of <var class="product">Model&nbsp;204</var>. </p>
</p>
<p>
<p>
The <var>[[GTBLPCT parameter|GTBLPCT]]</var> parameter determines the initial percentage of GTBL to allocate for global string variables. The default value of GTBLPCT is 50, meaning 50 percent of GTBL is initially allocated for global variable strings. The remainder, in this case 50 percent, is the initial allocation for global objects. However, if GTBLHASH=0, a nonzero setting for GTBLPCT has no effect. </p>
The <var>[[GTBLPCT parameter|GTBLPCT]]</var> parameter determines the initial percentage of GTBL to allocate for global string variables. The default value of <var>GTBLPCT</var> is 50, meaning 50 percent of GTBL is initially allocated for global variable strings. The remainder, in this case 50 percent, is the initial allocation for global objects. However, if <var>GTBLHASH</var> is 0, a nonzero setting for <var>GTBLPCT</var> has no effect. </p>
<p>
<p>
When in effect, if either area of GTBL fills and there are still free pages in GTBL, then GTBL can be rearranged if more space is required in the full area of GTBL. Because these rearrangements can be CPU intensive, Rocket Software recommends that you determine an accurate setting for GTBLPCT to avoid frequent rearrangements. You can monitor the performance of the hash GTBL feature using the GTBLRU user statistic and the GTBLRS since-last statistic.
When in effect, if either area of GTBL fills and there are still free pages in GTBL, then GTBL can be rearranged if more space is required in the full area of GTBL. Because these rearrangements can be CPU intensive, Rocket Software recommends that you determine an accurate setting for <var>GTBLPCT</var> to avoid frequent rearrangements. You can monitor the performance of the hash GTBL feature using the <code>GTBLRU</code> user statistic and the <code>GTBLRS</code> since-last statistic.
</p>
</p>
   
   
Line 60: Line 58:
<th>Tracking</th>
<th>Tracking</th>
</tr>
</tr>
<tr>
<tr>
<td>GTBLRU </td>
<td>GTBLRU </td>
<td>Number of GTBL rearrangements required to add a string variable global.</td>
<td>Number of GTBL rearrangements required to add a string variable global.</td>
</tr>
</tr>
<tr>
<tr>
<td>GTBLRS </td>
<td>GTBLRS </td>
Line 72: Line 72:
After reviewing the GTBLRU and GTBLRS statistics, you can consider taking the following actions: </p>
After reviewing the GTBLRU and GTBLRS statistics, you can consider taking the following actions: </p>
<ul>
<ul>
<li>If both of these values are high, increase the size of GTBL by increasing LGTBL. </li>
<li>If both of these values are high, increase the size of GTBL by increasing <var>LGTBL</var>. </li>
</li>
<li>If GTBLRU is high but GTBLRS is not, increase GTBLPCT or decrease GTBLHASH. </li>
<li>If GTBLRU is high but GTBLRS is not, increase <var>GTBLPCT</var> or decrease <var>GTBLHASH</var>. </li>
</li>
<li>If GTBLRS is high but GTBLRU is low, decrease GTBLPCT.</li>
<li>If GTBLRS is high but GTBLRU is low, decrease <var>GTBLPCT</var>. </li>
</li>
</ul>
</ul>
   
   
===Global found sets and lists===
===Global found sets and lists===
<p>
<p>
You can use global found sets and lists to make found sets and lists available across request boundaries. A global found set or list remains in GTBL until you:</p>
You can use global found sets and lists to make found sets and lists available across request boundaries. A global found set or list remains in GTBL until you: </p>
<ul>
<ul>
<li>Explicitly delete it</li>
<li>Explicitly delete it</li>
</li>
<li>Issue a RELEASE or COMMIT RELEASE statement</li>
<li>Issue a <var>Release</var> or <var>Commit Release</var> statement </li>
</li>
<li>The file or group it refers to is closed, including the file close processing done when exiting a subsystem or stopping</li>
<li>The file or group it refers to is closed, including the file close processing done when exiting a subsystem or stopping </li>
</li>
<li>Log out</li>
<li>Log out </li>
</li>
</ul>
</ul>
<p>
<p>
Sorted sets are a subgroup of found sets; they are treated the same by the CLEAR statement that is used to clear global found sets.</p>
Sorted sets are a subgroup of found sets; they are treated the same by the <var>Clear</var> statement that is used to clear global found sets.</p>
   
   
====Faster global variable processing option====
====Faster global variable processing option====
<p>
<p>
When global lists or found sets are processed as part of the FIND or PLACE RECORDS ON statement, it must be verified that a global variable representing the list or found set exists in GTBL. The CLEARG command or CLEAR statement may delete the global variable, so an internal routine is called to verify whether the global variable is in GTBL. The internal routine creates a new copy, if it was deleted. </p>
When global lists or found sets are processed as part of the <var>Find</var> or <var>Place Records On</var> statement, it must be verified that a global variable representing the list or found set exists in GTBL. The <var>CLEARG</var> command or <var>Clear</var> statement may delete the global variable, so an internal routine is called to verify whether the global variable is in GTBL. The internal routine creates a new copy, if it was deleted. </p>
<p>
<p>
The internal routine scans NTBL to find an entry that points to the required variable, then it uses its hash value to scan GTBL. Scanning a large NTBL may take considerable time. </p>
The internal routine scans NTBL to find an entry that points to the required variable, then it uses its hash value to scan GTBL. Scanning a large NTBL may take considerable time. </p>
Line 104: Line 102:
The NTBL scan can be eliminated, if internal variables representing global lists and found sets contain a global name hash value. Thus, an internal variable with a length of eight bytes that contains an NTBL entry offset points to the internal variable representing a global list or found set. This method avoids an NTBL scan, if a global variable has been deleted from GTBL. </p>
The NTBL scan can be eliminated, if internal variables representing global lists and found sets contain a global name hash value. Thus, an internal variable with a length of eight bytes that contains an NTBL entry offset points to the internal variable representing a global list or found set. This method avoids an NTBL scan, if a global variable has been deleted from GTBL. </p>
<p>
<p>
This faster global variable processing requires larger VTBL, because every global list or found set needs eight more bytes. If you want the benefit of this increased processing speed and can accommodate the increased VTBL requirement, set FASTGLOB=1. To maintain existing processing you can let <var>[[FASTGLOB parameter|FASTGLOB]]</var> default to 0 or explicitly set FASTGLOB=0.
This faster global variable processing requires larger VTBL, because every global list or found set needs eight more bytes. If you want the benefit of this increased processing speed and can accommodate the increased VTBL requirement, set <var>FASTGLOB</var> to 1. To maintain existing processing you can let <var>[[FASTGLOB parameter|FASTGLOB]]</var> default to 0, or you can explicitly set <var>FASTGLOB</var> to 0.
</p>
</p>
   
   
===Global positions===
===Global positions===
<p>
<p>
You can use REMEMBER and POSITION statements to save and recall a place in a FOR loop, either globally or non globally. This lets you suspend processing in a FOR loop and resume it later, either within the same request or in a subsequent request.</p>
You can use <var>Remember</var> and <var>Position</var> statements to save and recall a place in a <var>For</var> loop, either globally or non-globally. This lets you suspend processing in a <var>For</var> loop and resume it later, within the same request or in a subsequent request. </p>
   
   
===Global images and screens===
===Global images and screens===
Line 116: Line 114:
<ul>
<ul>
<li>Pass image and screen data from one request to another</li>
<li>Pass image and screen data from one request to another</li>
</li>
<li>Manage more than one image or screen in one request</li>
<li>Manage more than one image or screen in one request</li>
</li>
<li>Manage menus, which are a special type of screen</li>
<li>Manage menus, which are a special type of screen</li>
</li>
<li>Reduce I/O by swapping modified global screens to CCASERVR instead of paging them between the buffer pool and CCATEMP</li>
<li>Reduce I/O by swapping modified global screens to CCASERVR instead of paging them between the buffer pool and CCATEMP </li>
</li>
</ul>
</ul>
===Global string variables===
===Global string variables===
   
   
===Global string variable names and values===
===Global string variable names and values===
<p>
<p>
Entries in the GTBL consist of global name=value pairs. The names and values of the global string variables are created with the $SETG function from within a request. </p>
Entries in the GTBL consist of global name=value pairs. The names and values of the global string variables are created with the <var>$Setg</var> function from within a request. </p>
<ul>
<ul>
<li>A global string variable name can consist of up to 255 characters and follows the naming conventions for variables (see [[Using variables and values in Computation#%Variable names|%Variable names]]). Global string variables that contain special characters, other than a period (.) cannot be used as ?&amp; dummy strings.</li>
<li>A global string variable name can consist of up to 255 characters and follows the naming conventions for variables (see [[Using variables and values in computation#%Variable names|%Variable names]]). Global string variables that contain special characters, other than a period (<tt>.</tt>) cannot be used as <code>?&amp;</code> dummy strings. </li>
</li>
<li>A value can be 0, null string, to 255 characters.</li>
<li>A value can be 0, the null string, or up to 255 characters. </li>
</li>
</ul>
</ul>
   
   
===Clearing global string variables===
===Clearing global string variables===
<p>
<p>
When a new value for an existing name is stored, the old entry is first deleted. Entries remain in the table until you delete them by issuing a CLEARG command, execute a CLEAR statement, execute a $DELG function call, or you log out. </p>
When a new value for an existing name is stored, the old entry is first deleted. Entries remain in the table until you delete them by issuing a <var>CLEARG</var> command, execute a <var>Clear</var> statement, execute a <var>$Delg</var> function call, or you log out. </p>
<p>
<p>
If you define a large number of global string variables, <var class="product">Model&nbsp;204</var> performance can be adversely affected. </p>
If you define a large number of global string variables, <var class="product">Model&nbsp;204</var> performance can be adversely affected. </p>
Line 146: Line 143:
===Global variable functions and commands===
===Global variable functions and commands===
<p>
<p>
The following functions, statements, commands, and facilities manipulate entries in the global variable table:</p>
The following functions, statements, commands, and facilities manipulate entries in the global variable table: </p>
<ul>
<ul>
<li>Use the functions $SETG and $GETG within a request to store and retrieve global string variables. Use $INCRG to perform simple arithmetic on global string variables with numeric values. Use the $DELG function to delete global string variables created by either $SETG or $INCRG. The format of these functions is described in <b>See User Language Functions</b>.       </li>
<li>Use the functions <var>[[$Setg]]</var> and <var>[[$Getg]]</var> within a request to store and retrieve global string variables. Use <var>[[$Incrg]]</var> to perform simple arithmetic on global string variables with numeric values. Use the <var>[[$Delg]]</var> function to delete global string variables created by <var>$Setg</var> or <var>$Incrg</var>. </li>
</li>
<li>Use the ?&amp; dummy string within a request to read a variable in the GTBL. Refer to [[Procedures#Procedures|Procedures]] for more information about dummy strings.</li>
<li>Use the <code>?&amp;</code> dummy string within a request to read a variable in the GTBL. Refer to [[Procedures]] for more information about dummy strings. </li>
</li>
<li>Use the conditional INCLUDE command (IF A = B,name) to search the global variable table for an entry whose name is A and whose value is B. If the entry is found, the named procedure is included. The IF command is discussed on [[#Conditional and unconditional INCLUDEs|Conditional and unconditional INCLUDEs]].     </li>
<li>Use the conditional <var>INCLUDE</var> command (<code>IF A=B,<i>name</i></code>) to search the global variable table for an entry whose name is A and whose value is <code>B</code>. If the entry is found, the named procedure is included. The <var>IF</var> command is discussed on [[#Conditional and unconditional INCLUDEs|Conditional and unconditional INCLUDEs]]. </li>
</li>
</ul>
</ul>
 
===Using global string variables in application subsystems===
===Using global string variables in application subsystems===
<p>
<p>
In addition to the above facilities, an application subsystem can designate specific global string variables in the subsystem definition. For more information about subsystem global string variables, refer to: </p>
In addition to the above facilities, an application subsystem can designate specific global string variables in the subsystem definition. For more information about subsystem global string variables, refer to: </p>
<ul>
<ul>
<li>[[Application Subsystem Development#Command line global variable|Command line global variable]]</li>
<li>[[Application Subsystem development#Command line global variable|Command line global variable]] </li>
</li>
<li>[[Application Subsystem Development#Communication global variable|Communication global variable]]</li>
<li>[[Application Subsystem development#Communication global variable|Communication global variable]] </li>
</li>
<li>[[Application Subsystem Development#Error global variable|Error global variable]]</li>
<li>[[Application Subsystem development#Error global variable|Error global variable]] </li>
</li>
</ul>
</ul>
   
   
Line 174: Line 169:
====Example 1====
====Example 1====
<p>
<p>
Suppose that you want to store the current date in every record created during a session in YYMMDD format, a modified form of the value returned by the $DATE function. You can derive the date once at the beginning of the day and hold it for use throughout the day.</p>
Suppose that you want to store the current date in every record created during a session in YYMMDD format, a modified form of the value returned by the <var>$Date</var> function. You can derive the date once at the beginning of the day and hold it for use throughout the day. </p>
<p>
<p>
At the beginning of the terminal session, you enter:</p>
At the beginning of the terminal session, you enter:</p>
Line 189: Line 184:
</p>
</p>
<p>
<p>
Later in the terminal session, you can use the specially formatted date:</p>
Later in the terminal session, you can use the specially formatted date: </p>
<p class="code">BEGIN
<p class="code">BEGIN
     %DATE = $GETG('DATE')
     %DATE = $GETG('DATE')
Line 259: Line 254:
Commands and User Language statements have different effects and are used in different ways: </p>
Commands and User Language statements have different effects and are used in different ways: </p>
<ul>
<ul>
<li>System control commands can be issued only outside a request &mdash; at command level. They are acted upon immediately. User Language statements can be used only within a request. They are compiled on a line-by-line basis, but the entire request is not executed until <var class="product">Model&nbsp;204</var> receives an END statement.   </li>
<li>System control commands can be issued only outside a request &mdash; at command level. They are acted upon immediately. User Language statements can be used only within a request. They are compiled on a line-by-line basis, but the entire request is not executed until <var class="product">Model&nbsp;204</var> receives an END statement. </li>
</li>
<li>INCLUDE is both a command and a User Language statement. In either context, <var class="product">Model&nbsp;204</var> is directed to take the next input line from an appropriate stored procedure. When the procedure lines are exhausted, the next input line is taken from the command or User Language statement immediately following the INCLUDE.</li>
<li>INCLUDE is both a command and a User Language statement. In either context, <var class="product">Model&nbsp;204</var> is directed to take the next input line from an appropriate stored procedure. When the procedure lines are exhausted, the next input line is taken from the command or User Language statement immediately following the INCLUDE. </li>
</li>
<li>IF has two formats:
<li>IF has two formats:</li>
<ul>
</li>
<li>Conditional INCLUDE command</li>
 
<li>User Language statement </li>
</ul></li>
</ul>
</ul>
<p>
Conditional INCLUDE command</p>
<p>
User Language statement </p>
   
   
===Conditional and unconditional INCLUDEs===
===Conditional and unconditional INCLUDEs===
Line 340: Line 334:
====How Example 2 is processed====
====How Example 2 is processed====
<p>
<p>
The dialog produced by these procedures is shown below, with user input in boldface:</p>
The dialog produced by these procedures is shown below, with user input in boldface: </p>
<p class="code">INCLUDE A
<p class="code"><b>INCLUDE A</b>
??SELECT.RECORDS
??SELECT.RECORDS
REGION = SOUTH OR WEST
<b>REGION = SOUTH OR WEST</b>
$$ENTER REPORT NO
$$ENTER REPORT NO
2
<b>2</b>
output from Procedure C
<i>output from Procedure C </i>
</p>
</p>
 
====Keep IF commands at as high a nesting level as possible====
====Keep IF commands at as high a nesting level as possible====
<p>
<p>
Line 366: Line 360:
           IF $SETG('FILES','FILEA OR FILE$ FILEC') THEN
           IF $SETG('FILES','FILEA OR FILE$ FILEC') THEN
               PRINT '***REQUEST TOO LONG -- GTBL'
               PRINT '***REQUEST TOO LONG -- GTBL'
               %IGNORE = $SETG('FILES', '')
               %IGNORE = $SETG('FILES', &apos;&apos;)
           END IF
           END IF
END MORE
END MORE
MORE
MORE
           IF $GETG('files') = '' THEN
           IF $GETG('files') = &apos;&apos; THEN
               STOP
               STOP
           END IF
           END IF
Line 388: Line 382:
===General rules for declarations===
===General rules for declarations===
<ul>
<ul>
<li>You must declare global lists, found sets, and sorted sets in every request that references them; the DECLARE statement must come before the reference.</li>
<li>You must declare global lists, found sets, and sorted sets in every request that references them; the <var>Declare</var> statement must come before the reference. </li>
</li>
<li>If a global object is used in multiple subroutines, or in both the main program and a subroutine, the label must be declared as global in the main program before the subroutine(s). The subroutine(s) must then declare the label as common.</li>
<li>If a global object is used in multiple subroutines, or in both the main program and a subroutine, the label must be declared as global in the main program before the subroutine(s). The subroutine(s) must then declare the label as common. </li>
</li>
<li>If you refer to a global object before a DECLARE statement, the system issues a duplicate label compilation error. Such a reference implicitly makes the object non global.</li>
<li>If you refer to a global object before a <var>Declare</var> statement, the system issues a duplicate label compilation error. Such a reference implicitly makes the object non global. </li>
</li>
</ul>
</ul>
   
   
===Incompatibility===
===Incompatibility===
<p>
<p>
The PQO product does not support global found sets, lists, positions, or sorted sets. These global objects cannot be used in conjunction with remote files or scattered groups. This limitation exists, because GTBL does not exist on the PQO server.</p>
The [[PQO]] product does not support global found sets, lists, positions, or sorted sets. These global objects cannot be used in conjunction with remote files or scattered groups. This limitation exists, because GTBL does not exist on the PQO server. </p>
   
   
===Clearing global objects from GTBL===
===Clearing global objects from GTBL===
<p>
<p>
For syntax, details and examples of clearing global objects, see [[#Clearing the GTBL work area|Clearing the GTBL work area]].</p>
For syntax, details and examples of clearing global objects, see [[#Clearing the GTBL work area|Clearing the GTBL work area]]. </p>
 
==Using global found sets and lists==
==Using global found sets and lists==
<p>
<p>
You can pass found sets and lists from request to request by declaring them as GLOBAL. A global found set or list is stored in the internal work area GTBL for the duration of the terminal session unless it is intentionally cleared, or the file or group with which it is associated is closed.</p>
You can pass found sets and lists from request to request by declaring them as <var>Global</var>. A global found set or list is stored in the internal work area GTBL for the duration of the terminal session unless it is intentionally cleared, or the file or group with which it is associated is closed. </p>
   
   
====Creating a global found set or sorted set====
====Creating a global found set or sorted set====
<p>
<p>
You can create a global found set using this syntax:</p>
You can create a global found set using this syntax: </p>
   
   
====Syntax====
====Syntax====
<p class="code"><var>[</var>DECLARE<var>]</var> LABEL labelname [GLOBAL | COMMON]
<p class="syntax">[Declare] Label <span class="term">labelname</span> [Global | Common] </p>
</p>
<p>
<p>
Where labelname is a unique global object name.</p>
Where <var class="term">labelname</var> is a unique global object name.</p>
   
   
====Creating a global list====
====Creating a global list====
<p>
<p>
You can declare a global list using the following syntax:</p>
You can declare a global list using the following syntax:</p>
<p class="code">[Declare] List <span class="term">listname</span>  
====Syntax====
   [In [File [Perm | Temp] Group] <span class="term">name</span>]
<p class="code"><var>[</var>DECLARE<var>]</var> LIST listname
   [Global | Common] </p>
   [IN [FILE [PERM | TEMP] GROUP] name]
   [GLOBAL | COMMON]
</p>
<p>
<p>
In both cases, the keyword GLOBAL implies COMMON. These two keywords are mutually exclusive in the declaration statement. </p>
In both cases, the keyword <var>Global</var> implies <var>Common</var>. These two keywords are mutually exclusive in the declaration statement. </p>
<ul>
<ul>
<li>Because GLOBAL implies COMMON, a list or found set can be declared GLOBAL at any scope. See [[Subroutines#Scope of elements|Scope of elements]] for a discussion. </li>
<li>Because <var>Global</var> implies <var>Common</var>, a list or found set can be declared <var>Global</var> at any scope. See [[Subroutines#Scope of elements|Scope of elements]] for a discussion. </li>
</li>
<li>The global name, labelname, or listname, must be unique across all global objects. For a discussion, see [[Subroutines#Sharing common elements|Sharing common elements]].</li>
<li>The global name, label name, or list name, must be unique across all global objects. For a discussion, see [[Subroutines#Sharing common elements|Sharing common elements]]. </li>
</li>
</ul>
</ul>
   
   
====Usage rules====
====Usage rules====
<p>
<p>
The following rules apply to global found sets and lists:</p>
The following rules apply to global found sets and lists: </p>
<ul>
<ul>
<li>You must declare each global list or global found set as labelname GLOBAL in each procedure that uses it.</li>
<li>You must declare each global list or global found set as <code><i>labelname</i> Global</code> in each procedure that uses it. </li>
</li>
<li>The file context in which a global list or found set is used must be the same as the file context in which it was created.</li>
<li>The file context in which a global list or found set is used must be the same as the file context in which it was created.  
<p>
<p>
The <var class="product">Model&nbsp;204</var> compiler does not currently enforce this rule; therefore, your code must maintain this requirement. Rocket Software recommends that you populate a global found set or list only once within the scope of these global objects. However, this is not a restriction as long as file context is maintained.</p>
The <var class="product">Model&nbsp;204</var> compiler does not currently enforce this rule; therefore, your code must maintain this requirement. Rocket Software recommends that you populate a global found set or list only once within the scope of these global objects. However, this is not a restriction as long as file context is maintained. </p>
</li>
<li>Global found sets and lists are invalid in ad hoc group context.</li>
</li>
<li>Each global object name must be unique.</li>
</li>
<li>Global found sets and lists are not supported in remote file or scattered group contexts.</li>
</li>
</li>
<li>Global found sets and lists are invalid in ad hoc group context. </li>
<li>Each global object name must be unique. </li>
<li>Global found sets and lists are not supported in remote file or scattered group contexts. </li>
</ul>
</ul>
   
   
===Example 1: Referencing a global found set===
===Example 1: Referencing a global found set===
<p>
<p>
In this example, Procedure 1 declares the global found set and then performs the find. Procedure 2 needs only to declare the global found set and then reference the global found set labeled F1. The FOR loops in both procedures process records in the VEHICLES file for which the value of the field COLOR was equal to BLUE at the time of the evaluation of the FIND command in Procedure 1.</p>
In this example, Procedure 1 declares the global found set and then performs the find. Procedure 2 needs only to declare the global found set and then reference the global found set labeled F1. The <var>For</var> loops in both procedures process records in the <code>VEHICLES</code> file for which the value of the field <code>COLOR</code> was equal to <code>BLUE</code> at the time of the evaluation of the <var>Find</var> statement in Procedure 1. </p>
   
   
====Procedure 1====
<b>Procedure 1</b>
<p class="code">BEGIN
<p class="code">BEGIN
DECLARE LABEL F1 GLOBAL
DECLARE LABEL F1 GLOBAL
Line 470: Line 457:
</p>
</p>
   
   
====Procedure 2====
<b>Procedure 2</b>
<p class="code">BEGIN
<p class="code">BEGIN
DECLARE LABEL F1 GLOBAL
DECLARE LABEL F1 GLOBAL
Line 481: Line 468:
===Example 2: Maintaining file context===
===Example 2: Maintaining file context===
<p>
<p>
Example 2 illustrates repopulating a global found set across the scope of its usage, maintaining the same file context throughout. In this example, Procedure 1 is identical to Procedure 1 in Example 1 above, and Procedure 3 is identical to Procedure 2 in Example 1. The second procedure in this example, however, performs a different find than the first. Procedure 3 then processes the records found in Procedure 2.</p>
Example 2 illustrates repopulating a global found set across the scope of its usage, maintaining the same file context throughout. In this example, Procedure 1 is identical to Procedure 1 in Example 1 above, and Procedure 3 is identical to Procedure 2 in Example 1. The second procedure in this example, however, performs a different find than the first. Procedure 3 then processes the records found in Procedure 2. </p>
<p>
<p>
So in this example, Procedure 1 processes records in the VEHICLES file for which the value of the field COLOR is equal to BLUE, while Procedures 2 and 3 process records for which COLOR was equal to RED at the time of the FIND command evaluation in Procedure 2.</p>
So in this example, Procedure 1 processes records in the <code>VEHICLES</code> file for which the value of the field <code>COLOR</code> is equal to <code>BLUE</code>, while Procedures 2 and 3 process records for which <code>COLOR</code> was equal to <code>RED</code> at the time of the <var>Find</var> statement evaluation in Procedure 2. </p>
   
   
====Procedure 1====
<b>Procedure 1</b>
<p class="code">BEGIN
<p class="code">BEGIN
DECLARE LABEL F1 GLOBAL
DECLARE LABEL F1 GLOBAL
Line 496: Line 483:
</p>
</p>
   
   
====Procedure 2====
<b>Procedure 2</b>
<p class="code">BEGIN
<p class="code">BEGIN
DECLARE LABEL F1 GLOBAL
DECLARE LABEL F1 GLOBAL
Line 507: Line 494:
</p>
</p>
   
   
====Procedure 3====
<b>Procedure 3</b>
<p class="code">BEGIN
<p class="code">BEGIN
DECLARE LABEL F1 GLOBAL
DECLARE LABEL F1 GLOBAL
Line 522: Line 509:
===Limiting subsequent references===
===Limiting subsequent references===
<p>
<p>
For example, in Procedure 1 below, MAKE is the only field referenced in the request. Therefore, MAKE is the only field that can be referenced in subsequent requests. Thus, in Procedure 2, because the field MODEL was not referenced in the previous request, a blank is printed each time through the FOR loop.</p>
For example, in Procedure 1 below, MAKE is the only field referenced in the request. Therefore, MAKE is the only field that can be referenced in subsequent requests. Thus, in Procedure 2, because the field MODEL was not referenced in the previous request, a blank is printed each time through the FOR loop. </p>
   
   
====Procedure 1====
====Procedure 1====
Line 553: Line 540:
If you are not going to refer to the sorted set in the request that creates the sorted set, you can code a FOR loop, which is compiled but never executed, that refers to each field that you want to refer to in a subsequent request. </p>
If you are not going to refer to the sorted set in the request that creates the sorted set, you can code a FOR loop, which is compiled but never executed, that refers to each field that you want to refer to in a subsequent request. </p>
   
   
==Saving and recalling a POSITION in a FOR loop==
==Saving and recalling a position in a For loop==
<p>
<p>
You can include statements in a FOR loop to provide for the possibility of terminating the loop before the set of records or values being processed is exhausted. For example, you might use a JUMP TO or LOOP END statement in conjunction with an IF statement to test each record or value before processing, and terminating the loop if a certain condition is met.</p>
You can include statements in a <var>For</var> loop to provide for the possibility of terminating the loop before the set of records or values being processed is exhausted. For example, you might use a <var>Jump To</var> or <var>Loop End</var> statement in conjunction with an <var>If</var> statement to test each record or value before processing, and terminating the loop if a certain condition is met. </p>
<p>
<p>
The REMEMBER and POSITION statements let you store the current processing position in a FOR loop, then recall it at a later time and resume FOR processing where you left off earlier.</p>
The <var>Remember</var> and <var>Position</var> statements let you store the current processing position in a <var>For</var> loop, then recall it at a later time and resume <var>For</var> processing where you left off earlier. </p>
   
   
===Remember statement===
===REMEMBER statement===
<p>
<p>
The purpose of the REMEMBER statement is to store the processing position in a FOR loop. Each REMEMBER statement creates a GTBL entry of variable length. See [[Large request considerations]] for detailed descriptions of GTBL entries. If you remember a position as GLOBAL, the entry remains in GTBL after the current request ends. <var class="product">Model&nbsp;204</var> clears non global REMEMBER positions at the end of each request.</p>
The purpose of the <var>Remember</var> statement is to store the processing position in a <var>For</var> loop. Each <var>Remember</var> statement creates a GTBL entry of variable length. See [[Large request considerations]] for detailed descriptions of GTBL entries. If you remember a position as <var>Global</var>, the entry remains in GTBL after the current request ends. <var class="product">Model&nbsp;204</var> clears non-global <var>Remember</var> positions at the end of each request.</p>
   
   
====Syntax====
====Syntax====
<p class="code">REMEMBER <var>[</var>GLOBAL<var>]</var> position_name
{{Template:Remember statement syntax}}
Where:
<ul>
<li>The <var>Global</var> option retains the <var>Remember</var> position after the current request terminates. If <var>Global</var> is not specified, the position is temporary, and it is cleared from GTBL after the current request terminates. </li>
   
   
  [IN foundsortset_name | ON list_name]
<li><var class="term">position_name</var> is a unique object name you assign to the <var>Remember</var> position. </li>
</p>
Where:
<li><var class="term">foundsortset_name</var> or <var class="term">list_name</var> must be identical to the listname or label specified on the <var>For</var> loop:
<ul>
<ul>
<li>The GLOBAL option retains the REMEMBER position after the current request terminates. If GLOBAL is not specified, the position is temporary, and is cleared from GTBL after the current request terminates.</li>
<li>If you are processing a found set or a sorted set, <code>In <i>foundsortset_name</i></code> is the label of the <var>Find</var> statement that generated it. </li>
</li>
 
<li>position_name is a unique object name you assign to the REMEMBER position.</li>
<li>If you are processing a list, <code>On <i>list_name</i></code> is the name you gave to the list when you originally declared it. </li>
</li>
</ul></li>
<li>The foundsortset_name or list_name must be identical to the listname or label specified on the FOR loop:</li>
</li>
</ul>
</ul>
<p>
If you are processing a found set or a sorted set, IN foundsortset_name is the label of the FIND statement that generated it. </p>
<p>
If you are processing a list, ON list_name is the name you gave to the list when you originally declared it.</p>
   
   
====Usage notes====
====Usage notes====
<p>
<p>
The following rules apply to the use of the REMEMBER statement:</p>
The following rules apply to the use of the <var>Remember</var> statement:</p>
<ul>
<ul>
<li>Can appear only within a FOR loop, but not a nested FOR loop. The file context must be identical to the context of the FOR loop.</li>
<li>Can appear only within a <var>For</var> loop, but not a nested <var>For</var> loop. The file context must be identical to the context of the <var>For</var> loop. </li>
</li>
<li>Is invalid in ad hoc group context, if used with the GLOBAL option.</li>
<li>Is invalid in ad hoc group context, if used with the <var>Global</var> option. </li>
</li>
<li>The REMEMBER statement is incompatible with FOR EACH RECORD IN ORDER BY clauses.</li>
<li>The <var>Remember</var> statement is incompatible with <var>For Each Record In Order By</var> clauses. </li>
</li>
</ul>
</ul>
 
===POSITION statement===
===Position statement===
<p>
<p>
A POSITION statement recalls a remembered position, so you can resume FOR processing in a list or found set that was terminated at an earlier time. For example, if you remembered the position at record number 5, then your foundset is positioned at record number 6 for further processing.</p>
A <var>Position</var> statement recalls a remembered position, so you can resume <var>For</var> processing in a list or found set that was terminated at an earlier time. For example, if you remembered the position at record number 5, then your foundset is positioned at record number 6 for further processing.</p>
<p>
<p>
This POSITION statement is not to be confused with the POSITION statement used to read records sequentially in an external VSAM KSDS file. See [[Images#POSITION statement|POSITION statement]]. </p>
This <var>Position</var> statement is not to be confused with the <var>Position</var> statement used to read records sequentially in an external VSAM KSDS file. See [[Images#Position statement|Position statement]]. </p>
   
   
====Syntax====
====Syntax====
<p class="code">POSITION {FOUNDSET foundsortset_name
<p class="syntax">Position {Foundset <span class="term">foundsortset_name</span> | List <span class="term">list_name</span>} [At] <span class="term">position_name</span>
  | LIST list_name} [AT] position_name
</p>
</p>
Where:
Where:
<ul>
<ul>
<li>The foundsortset_name or list_name must be identical to the list or label name used on a previous REMEMBER statement and in the FOR statement that follows. </li>
<li><var class="term">foundsortset_name</var> or <var class="term">list_name</var> must be identical to the list or label name used on a previous <var>Remember</var> statement and in the <var>For</var> statement that follows.
</li>
</ul>
<p>
<p>
If you are about to resume the processing of a found set, foundsortset_name is the label of the FIND statement that generated it. </p>
If you are about to resume the processing of a found set, <var class="term">foundsortset_name</var> is the label of the <var>Find</var> statement that generated it. </p>
<p>
<p>
If you are about to resume the processing of a list, list_name is the name you gave to the list when you originally declared it.</p>
If you are about to resume the processing of a list, <var class="term">list_name</var> is the name you gave to the list when you originally declared it.</p></li>
<ul>
 
<li>position_name is a name that you assigned to the remembered position when you stored it on a previous REMEMBER statement.</li>
<li><var class="term">position_name</var> is a name that you assigned to the remembered position when you stored it on a previous <var>Remember</var> statement. </li>
</li>
</ul>
</ul>
   
   
Line 624: Line 601:
The following rules apply:</p>
The following rules apply:</p>
<ul>
<ul>
<li>The POSITION statement must appear outside, immediately before the FOR loop to which it refers; it cannot be in the FOR loop itself.</li>
<li>The <var>Position</var> statement must appear outside, immediately before the <var>For</var> loop to which it refers; it cannot be in the <var>For</var> loop itself.</li>
</li>
<li>The FOR statement that follows the POSITION statement must have an identical file context and list name or label name as the statement that initiated the FOR loop of the remembered position.</li>
<li>The <var>For</var> statement that follows the <var>Position</var> statement must have an identical file context and list name or label name as the statement that initiated the <var>For</var> loop of the remembered position.</li>
</li>
<li>The POSITION statement is incompatible with FOR EACH RECORD IN ORDER BY clauses. </li>
<li>The <var>Position</var> statement is incompatible with <var>For Each Record In Order By</var> clauses. </li>
</li>
</ul>
</ul>
   
   
==Global images and screens==
==Global images and screens==
<p>
<p>
You can use global images and screens to pass image and screen data from one request to another and to efficiently manage more than one image or screen in one request.</p>
You can use global images and screens to pass image and screen data from one request to another and to efficiently manage more than one image or screen in one request. </p>
<p>
<p>
You can also declare global menus, because a menu is a special type of screen. In this section, the term "screen" applies to both screens and menus, unless otherwise noted.</p>
You can also declare global menus, because a menu is a special type of screen. In this section, the term "screen" applies to both screens and menus, unless otherwise noted. </p>
   
   
===Declaring global images and screens===
===Declaring global images and screens===
<p>
<p>
You make an image or screen global by specifying the keyword GLOBAL in its declaration statement. You can declare global images and screens to be TEMPORARY, deleted at request termination, or PERMANENT, persist across request termination. </p>
You make an image or screen global by specifying the keyword <var>Global</var> in its declaration statement. You can declare global images and screens to be <var>Temporary</var>, deleted at request termination, or <var>Permanent</var>, persist across request termination. </p>
   
   
===How images and screens are processed===
===How images and screens are processed===
<p>
<p>
When you declare an image or screen as GLOBAL, it is stored in GTBL. Non global images and screens, declared as COMMON, or neither COMMON nor GLOBAL, are stored in FSCB.</p>
When you declare an image or screen as <var>Global</var>, it is stored in GTBL. Nonglobal images and screens, declared as <var>Common</var>, or neither <var>Common</var> nor <var>Global</var>, are stored in FSCB. </p>
<p>
<p>
This section provides some background information about how <var class="product">Model&nbsp;204</var> processes images and screens, contrasting how global and non global images and screens are processed.</p>
This section provides some background information about how <var class="product">Model&nbsp;204</var> processes images and screens, contrasting how global and nonglobal images and screens are processed. </p>
   
   
===Images and screen processing===
===Images and screen processing===
<p>
<p>
The following figures represent how non global and global objects are processed. Comparing the two types of processing highlights the I/O and storage savings associated with the global images and screens</p>
The figures in the following subsections represent how nonglobal and global objects are processed. Comparing the two types of processing highlights the I/O and storage savings associated with the global images and screens.
[[File:Nonglobal_object_processing.gif]]
</p>
 
====Processing of nonglobal objects====
====Processing of nonglobal objects====
<p class="figure">[[File:Nonglobal_object_processing.png|550px]] </p>
<p>
<p>
The <b>Nonglobal object processing</b> figure illustrates the process in the following steps:</p>
The <b>Nonglobal object processing</b> figure illustrates the process in the following steps:</p>
<ol>
<ol>
<li>The compiler loads a compiled version of the screen or image into FSCB in the user's server.</li>
<li>The compiler loads a compiled version of the screen or image into FSCB in the user's server.</li>
<li>A copy of the compiled object is stored in the buffer pool.</li>
<li>A copy of the compiled object is stored in the buffer pool.</li>
<li>A PREPARE statement acts on the compiled object in the buffer pool and copies it into FSCB.</li>
 
<li>A <var>Prepare</var> statement acts on the compiled object in the buffer pool and copies it into FSCB.</li>
 
<li>Update statements act on the copy of the object in FSCB.</li>
<li>Update statements act on the copy of the object in FSCB.</li>
<li>The updated object is copied from FSCB to a working copy of the object in the buffer pool.</li>
<li>The updated object is copied from FSCB to a working copy of the object in the buffer pool.</li>
<li>If a user waits too long or the buffer pool fills up, the object is written to CCATEMP. When a user presses<var> ENTER</var> for that object, the object is loaded back from CCATEMP to the buffer pool. </li>
 
<li>If a user waits too long or the buffer pool fills up, the object is written to CCATEMP. When a user presses Enter for that object, the object is loaded back from CCATEMP to the buffer pool. </li>
</ol>
</ol>
<p>&nbsp;</p>
====GLOBAL object processing====
 
====Processing of global objects====  
[[File:Global_object_processing.gif]]
<p class="figure">[[File:Global_object_processing.png|550px]] </p>
====Processing of global objects====
<p>
<p>
The <b>Global object processing</b> figure illustrates the process in the following steps:</p>
The <b>Global object processing</b> figure illustrates the process in the following steps: </p>
<ol>
<ol>
<li>The compiler loads a compiled version of the screen or image into FSCB in the user's server.</li>
<li>The compiler loads a compiled version of the screen or image into FSCB in the user's server. </li>
<li>A copy of the compiled object is stored in the buffer pool. This copy is called 'VIRGIN', as it is never updated.</li>
 
<li>A PREPARE statement acts on the compiled object in the buffer pool and copies it into GTBL.</li>
<li>A copy of the compiled object is stored in the buffer pool. This copy is called 'VIRGIN', as it is never updated. </li>
<li>Update statements act on the copy in GTBL.</li>
 
<li>A <var>Prepare</var> statement acts on the compiled object in the buffer pool and copies it into GTBL. </li>
 
<li>Update statements act on the copy in GTBL. </li>
</ol>
</ol>
   
   
===Using PREPARE and IDENTIFY statements===
===Using Prepare and Identify statements===
<p>
<p>
To help you decide how to use the PREPARE and IDENTIFY statements review the following:</p>
To help you decide how to use the <var>Prepare</var> and <var>Identify</var> statements, review the following:</p>
<ul>
<ul>
<li>[[#GTBL internal work area|GTBL internal work area]]</li>
<li>[[#GTBL internal work area|GTBL internal work area]] </li>
</li>
   
   
<li>[[#Timing and placement of a CLEAR statement|Timing and placement of a CLEAR statement]]</li>
<li>[[#Timing and placement of a CLEAR statement|Timing and placement of a CLEAR statement]] </li>
</li>
   
   
<li>For syntax and usage of the PREPARE statement, see [[Full-screen feature#PREPARE statement|PREPARE statement]]</li>
<li>For syntax and usage of the <var>Prepare</var> statement, see [[Full-screen feature#PREPARE statement|Prepare statement]]</li>
</li>
   
   
<li>For syntax and usage of the IDENTIFY statement, see [[Images#IDENTIFY statement|IDENTIFY statement]]</li>
<li>For syntax and usage of the <var>Identify</var> statement, see [[Images#Identify statement|Identify statement]]  
<p>
<p>
Also when using the IDENTIFY statement, see [[#Consistency checks performed|Consistency checks performed]].</p>
Also when using the <var>Identify</var> statement, see [[#Consistency checks performed|Consistency checks performed]]. </p></li>
</li>
</ul>
</ul>
   
   
===Performance and efficiency benefits===
===Performance and efficiency benefits===
<p>
<p>
Global images and screens can simply and efficiently perform image-to-image processing and screen to image processing, eliminating the need to map screen items to image items when passing or preserving screens. Using global images and screens:</p>
Global images and screens can simply and efficiently perform image-to-image processing and screen-to-image processing, eliminating the need to map screen items to image items when passing or preserving screens. Using global images and screens: </p>
<ul>
<ul>
<li>Reduces CPU resources required to pass data between requests in applications where a large number of global variables would have been necessary. </li>
<li>Reduces CPU resources required to pass data between requests in applications where a large number of global variables would have been necessary. </li>
</li>
<li>Reduces the FSCB I/O between multiple images and between images and screens. </li>
<li>Reduces the FSCB I/O between multiple images and between images and screens. </li>
</li>
<li>Makes the declaration of global data explicit, thus traceable by using naming conventions and cross-reference tools.</li>
<li>Makes the declaration of global data explicit, thus traceable by using naming conventions and cross-reference tools. </li>
</li>
<li>Simplifies code, eliminating the need for <var>IF $SETG() THEN ...</var> sequences to map request %variables into global variables and for <var>%XYZ = $GETG()</var> sequences to map global variables into request %variables. </li>
<li>Simplifies code, eliminating the need for <var>If $Setg() Then ...</var> sequences to map request %variables into global variables and for <var>%xyz = $Getg()</var> sequences to map global variables into request %variables. </li>
</li>
<li>Reduces I/O by swapping modified global screens to CCASERVR instead of paging them between the buffer pool and CCATEMP.</li>
<li>Reduces I/O by swapping modified global screens to CCASERVR instead of paging them between the buffer pool and CCATEMP. </li>
</li>
</ul>
</ul>
   
   
===When to use global images and screens===
===When to use global images and screens===
<p>
<p>
You achieve the greatest benefit by declaring as GLOBAL the most frequently used images and screens in an application.</p>
You achieve the greatest benefit by declaring as <var>Global</var> the most frequently used images and screens in an application. </p>
<p>
<p>
Infrequently used images and screens declared as non global do not put pressure on the buffer pool, because there would not be many copies in the buffer pool for many users, and little I/O with CCATEMP. If an application has many images and/or screens, GTBL might overflow if all the images and/or screens are defined as global. </p>
Infrequently used images and screens declared as nonglobal do not put pressure on the buffer pool, because there would not be many copies in the buffer pool for many users, and little I/O with CCATEMP. If an application has many images and/or screens, GTBL might overflow if all the images and/or screens are defined as global. </p>
   
   
===Consistency checks performed===
===Consistency checks performed===
<p>
<p>
When a global image or screen is first referred to in a request, GTBL is searched for the object.</p>
When a global image or screen is first referred to in a request, GTBL is searched for the object. </p>
<p>
<p>
If the object is<var> not</var> already present in GTBL, the object is written into GTBL.</p>
If the object is<var> not</var> already present in GTBL, the object is written into GTBL. </p>
<p>
<p>
If the object is present, two consistency checks are performed:</p>
If the object is present, two consistency checks are performed:</p>
<ul>
<ul>
<li>Persistence &mdash; PERMANENT or TEMPORARY status &mdash; of the new object must match the persistence of the object already in GTBL.</li>
<li>Persistence &mdash; <var>Permanent</var> or <var>Temporary</var> status &mdash; of the new object must match the persistence of the object already in GTBL. </li>
</li>
<li>Definition &mdash; PERMANENT or TEMPORARY &mdash; of the new object must match the definition of the object already in GTBL.</li>
<li>Definition &mdash; <var>Permanent</var> or <var>Temporary</var> &mdash; of the new object must match the definition of the object already in GTBL.  
</li>
</li>
</ul>
</ul>
<p class="note"><b>Note:</b> If a global image has an array that uses the DEPENDING ON %variable option, the names of the %variables are not compared when the definition check is performed.</p>
<p class="note"><b>Note:</b> If a global image has an array that uses the <var>Depending On <i>%variable</i></var> option, the names of the %variables are not compared when the definition check is performed. </p>
<p>
<p>
If either of these consistency checks fails &mdash; for example, an image is declared as TEMPORARY, but the same image already exists in GTBL, declared as PERMANENT &mdash; then the request is canceled and the following message is generated: </p>
If either of these consistency checks fails &mdash; for example, an image is declared as <var>Temporary</var>, but the same image already exists in GTBL, declared as <var>Permanent</var> &mdash; then the request is canceled and the [[M204.2158]] message is generated: </p>
<p class="code">M204.2158: GLOBAL object-type DEFINITION DOESN'T MATCH DEFINITION IN GTBL error-description, NAME HASH=hash-code
 
<p class="code">Global <i>object-type</i> definition doesn't match value in GTBL​,​ <i>error-description</i>, name hash=<i>hash-code</i>
</p>
</p>
 
==Using global images and screens==
==Using global images and screens==
<p>
<p>
Line 798: Line 774:
===System administration issues===
===System administration issues===
<p>
<p>
To review the implications of the global images and screens feature for system administrators, see the
To review the implications of the global images and screens feature for system administrators, see the following topics:</p>
<var class="book">[http://www.rocketsoftware.com/m204/products/model204/documentation/v7r4/M204-System-Mgr/view Rocket Model 204 System Manager's Guide]</var> on the following topics:</p>
<ul>
<ul>
<li>GTBL size</li>
<li>GTBL size &mdash; [[Large request considerations#GTBL (global variable table)|GTBL (global variable table)]], [[Defining the runtime environment (CCAIN)#Understanding the global variable table (GTBL)|Understanding the global variable table (GTBL)]], and [[GTBLHASH parameter]]</li>
</li>
<li>VTBL usage with COMMON images and screens</li>
<li>VTBL usage with COMMON images and screens &mdash; [[Large request considerations#VTBL (compiler variable table)|VTBL (compiler variable table)]] and [[Defining the runtime environment (CCAIN)#Compiler variable table (VTBL)|Compiler variable table (VTBL)]]</li>
</li>
<li>User since-last statistics</li>
<li>User since-last statistics &mdash; [[Using system statistics#User since-last statistics|User since-last statistics]] </li>
</li>
</ul>
</ul>
   
   
Line 826: Line 800:
<th>To Remove...</th>
<th>To Remove...</th>
</tr>
</tr>
<tr>
<tr>
<td><var>[[CLEARG command|CLEARG]]<var> </td>
<td><var>[[CLEARG command|CLEARG]]</var> </td>
<td>Only global string variables. </td>
<td>Only global string variables. </td>
</tr>
</tr>
<tr>
<tr>
<td><var>[[CLEARGO command|CLEARGO]]<var></td>
<td><var>[[CLEARGO command|CLEARGO]]</var></td>
<td>A<var class="term">ll</var> global objects: images, screens, menus, found sets, lists, and temporary and permanent positions from GTBL; it does not clear global string variables. </td>
<td>All global objects: images, screens, menus, found sets, lists, and temporary and permanent positions from GTBL; it does not clear global string variables. </td>
</tr>
</tr>
</table>
</table>
<p>
<p>
The CLEARGO command takes no arguments.
The <var>CLEARGO</var> command takes no arguments.
</p>
</p>
   
   
===Using the $DELG function===
===Using the $DELG function===
<p>
<p>
You can use the <var>[[$DELG]]<var> function to delete global string variables created by either $SETG or $INCRG.</p>
You can use the <var>[[$Delg]]</var> function to delete global string variables created by either <var>[[$Setg]]</var> or <var>[[$Incrg]]</var>. </p>
<p>
<p>
The $DELG function deletes a single or group of similar global string variables, releasing and compacting the GTBL space for reuse.</p>
The <var>[[$Delg]]</var> function deletes a single or group of similar global string variables, releasing and compacting the GTBL space for reuse. </p>
   
   
===Using the CLEAR statement===
===Using the CLEAR statement===
<p>
<p>
You can use the CLEAR statement to clear global objects of the same type, an individual global object, or all global string variables, as shown in the following table:</p>
You can use the <var>Clear</var> statement to clear global objects of the same type, an individual global object, or all global string variables, as shown in the following table: </p>
<table>
<table>
<tr class="head">
<tr class="head">
Line 853: Line 829:
<th>Clears...</th>
<th>Clears...</th>
</tr>
</tr>
<tr>
<tr>
<td>CLEAR [type-of-object] OBJECTS </td>
<td nowrap><var>Clear <i>type-of-object</i> Objects</var> </td>
<td>A class of global objects or all global objects. Global string variables are not cleared, because they are not objects.</td>
<td>A class of global objects or all global objects. Global string variables are not cleared, because they are not objects. </td>
</tr>
</tr>
<tr>
<tr>
<td>CLEAR GLOBAL </td>
<td><var>Clear Global</var> </td>
<td>Individual global objects from GTBL. </td>
<td>Individual global objects from GTBL. </td>
</tr>
</tr>
<tr>
<tr>
<td>CLEAR GLOBALS </td>
<td><var>Clear Globals</var> </td>
<td>All global string variables. You cannot selectively clear individual global string variables with the CLEAR statement.</td>
<td>All global string variables. You cannot selectively clear individual global string variables with the <var>Clear</var> statement. </td>
</tr>
</tr>
</table>
</table>
Line 869: Line 848:
====Syntax====
====Syntax====
<p>
<p>
The format for the CLEAR statement is:</p>
The format for the <var>Clear</var> statement is:</p>
<p class="code">CLEAR {[[ALL | TEMP | LISTFDST | POSITION] [GLOBAL]]
{{Template:Clear statement syntax}}
Where:
<ul>
<li><var>All</var> clears all permanent and temporary global objects, including: found sets, lists, images, menus, positions, screens, and sorted sets from GTBL. </li>
<li><var>Temp</var> clears only global objects explicitly declared as <var>Temp</var> in your request, including images, menus, and screens from GTBL. </li>
   
   
  OBJECTS
<li><var>ListFdst</var> clears all global found sets, lists, and sorted sets from GTBL. </li>
   
   
  | GLOBAL {IMAGE | SCREEN | MENU | LIST | FOUNDSET
<li><var>Position</var> clears all permanent and temporary positions from GTBL. </li>
   
   
    | POSITION [PERM | TEMP]} {'objectname'
<li><var>Objects</var> specifies that the <var>CLEAR</var> command is operating on the object type you specified, or operating on all types of objects. </li>
   
   
    | %variable}}
<li><var>Global</var> clears a specific global object from GTBL. You cannot clear a global string variable created with the <var>$Setg</var> function using this form. </li>
   
   
  | GLOBALS
<li><var class="term">objectname</var> is the literal name of the specific global object to be cleared from GTBL. Enclose <var class="term">objectname</var> in single quotation marks.</li>
</p>
 
Where:
<li><var class="term">%variable</var> contains a value that specifies the global object to be cleared from GTBL. </li>
<ul>
<li>ALL clears all permanent and temporary global objects, including: found sets, lists, images, menus, positions, screens, and sorted sets from GTBL.</li>
<li><var>Globals</var> clears all global string variables created with the <var>$Setg</var> function from GTBL. This form does <em>not</em> clear any global objects. </li>
</li>
<li>TEMP clears only global objects explicitly declared as TEMP in your request, including images, menus, and screens from GTBL.</li>
</li>
<li>LISTFDST clears all global found sets, lists, and sorted sets from GTBL.</li>
</li>
<li>POSITION clears all permanent and temporary positions from GTBL.</li>
</li>
<li>OBJECTS specifies CLEAR command is operating on the object type you specified or all types of objects.</li>
</li>
<li>GLOBAL clears a specific global object from GTBL. You cannot clear a global string variable created with the $SETG function using this form.</li>
</li>
<li>objectname is the literal name of the specific global object to be cleared from GTBL. Enclose objectname in single quotation marks.</li>
</li>
<li>%variable contains a value that specifies the global object to be cleared from GTBL.</li>
</li>
<li>GLOBALS clears all global string variables created with the $SETG function from GTBL. This form does not clear any global objects.</li>
</li>
</ul>
</ul>
====Usage notes====
====Usage notes====
<p>
<p>
The following statements clear all permanent and temporary global found sets, images, lists, menus, positions, screens, and sorted sets:</p>
The following statements clear all permanent and temporary global found sets, images, lists, menus, positions, screens, and sorted sets:</p>
<p class="code">CLEAR OBJECTS
<p class="code">Clear Objects
   
   
CLEAR ALL OBJECTS
Clear All Objects
   
   
CLEAR ALL GLOBAL OBJECTS
Clear All Global Objects
   
   
CLEAR GLOBAL OBJECTS
Clear Global Objects
</p>
</p>
   
   
===Clearing global found sets and lists===
===Clearing global found sets and lists===
<p>
<p>
You can clear global found sets and lists in GTBL without logging off using the following examples:</p>
You can clear global found sets and lists in GTBL without logging off using the following examples: </p>
<ul>
<ul>
<li>Clear a specific global list or found set by issuing one of these statements:</li>
<li>Clear a specific global list or found set by issuing one of these statements:
<p class="code">CLEAR GLOBAL LIST 'objectname'
<p class="code">Clear Global List '<i>objectname</i>'
   
   
CLEAR GLOBAL LIST %variable
Clear Global List <i>%variable</i>
   
   
CLEAR GLOBAL FOUNDSET 'objectname'
Clear Global Foundset '<i>objectname</i>'
   
   
CLEAR GLOBAL FOUNDSET %variable
Clear Global Foundset <i>%variable</i>
</p></li>
</p></li>
<li>Clear all global found sets and lists with the statement:</li>
 
<p class="code">CLEAR LISTFDST <var>[</var>GLOBAL<var>]</var> OBJECTS
<li>Clear all global found sets and lists with the statement:  
</p>
<p class="code">Clear ListFdst [Global] Objects </p>
<p>
<p>
(Global found sets and lists are among the global objects cleared by the CLEARGO command.)</p>
(Global found sets and lists are among the global objects cleared by the <var>CLEARGO</var> command.) </p></li>
</li>
 
<li>Close a file or group with which a global list or found set is associated. This includes the file close processing done when exiting or stopping a subsystem.</li>
<li>Close a file or group with which a global list or found set is associated. This includes the file close processing done when exiting or stopping a subsystem. </li>
</li>
<li>Issue a UTABLE command that changes the size of FTBL, XTBL, or GTBL. </li>
<li>Issue a <var>UTABLE</var> command that changes the size of FTBL, XTBL, or GTBL. </li>
</li>
</ul>
</ul>
<p>
<p>
If you clear a global list or global found set, then any request that uses the global and does not have the FIND statement that creates the global object receives either of the following error messages:</p>
If you clear a global list or global found set, then any request that uses the global and does not have the <var>Find</var> statement that creates the global object receives either of the following error messages:
<p class="code">M204.0301 REFERENCED STATEMENT LABEL UNDEFINED
</p>
<p class="code">M204.0301 Referenced statement label undefined
   
   
M204.0311 UNACCEPTABLE STATEMENT REFERENCE
M204.0311 Unacceptable statement reference
</p>
</p>
   
   
===RELEASE and COMMIT RELEASE statements with global foundsets and lists===
===RELEASE and COMMIT RELEASE statements with global foundsets and lists===
<p>
<p>
The RELEASE statements and the COMMIT RELEASE statements empty the contents of a global found set, global sort set, or global list. The label and positions associated with a found set, sort set, or the list is still considered global, but it is empty. Global positions are not cleared by RELEASE or COMMIT RELEASE statements, however, without records there is nothing to process.</p>
The <var>Release</var> statements and the <var>Commit Release</var> statements empty the contents of a global found set, global sort set, or global list. The label and positions associated with a found set, sort set, or the list is still considered global, but it is empty. Global positions are not cleared by <var>Release</var> or <var>Commit Release</var> statements, however, without records there is nothing to process.</p>
   
   
===Clearing remembered positions===
===Clearing remembered positions===
<p>
<p>
Each REMEMBER statement creates a GTBL entry, whether or not GLOBAL is specified. If GLOBAL is not specified, the position is temporary and is cleared from GTBL at the end of request execution.</p>
Each <var>Remember</var> statement creates a GTBL entry, whether or not <var>Global</var> is specified. If GLOBAL is not specified, the position is temporary and is cleared from GTBL at the end of request execution.</p>
<p>
<p>
All remembered positions, along with all other GTBL entries, are cleared when you log off. You can also clear remembered positions in the following ways:</p>
All remembered positions, along with all other GTBL entries, are cleared when you log off. You can also clear remembered positions in the following ways:</p>
<ul>
<ul>
<li>You can clear a specific temporary position by issuing one of these statements:</li>
<li>You can clear a specific temporary position by issuing one of these statements:
<p class="code">CLEAR GLOBAL POSITION TEMP 'objectname'
<p class="code">Clear Global Position Temp '<i>objectname</i>'
   
   
CLEAR GLOBAL POSITION TEMP %variable
Clear Global Position Temp <i>%variable</i>
</p></li>
</p></li>
<li>You can clear a specific permanent position by issuing one of these statements:</li>
 
<p class="code">CLEAR GLOBAL POSITION PERM 'objectname'
<li>You can clear a specific permanent position by issuing one of these statements:  
<p class="code">Clear Global Position Perm '<i>objectname</i>'
   
   
CLEAR GLOBAL POSITION PERM %variable
Clear Global Position Perm <i>%variable</i>
</p></li>
</p></li>
<li>You clear all global found sets, lists, or sorted sets with which a remembered position is associated.</li>
 
<p class="code">CLEAR LISTFDST [GLOBAL] OBJECTS
<li>You clear all global found sets, lists, or sorted sets with which a remembered position is associated:
<p class="code">Clear ListFdst [Global] Objects
</p></li>
</p></li>
<li>You clear all remembered positions by issuing the statement:</li>
 
<p class="code">CLEAR POSITION <var>[</var>GLOBAL<var>]</var> OBJECTS
<li>You clear all remembered positions by issuing the statement:
<p class="code">Clear Position [Global] Objects
</p></li>
</p></li>
</ul>
</ul>
   
   
====Usage notes====
====Usage notes====
<p>
<ul>
When you are using the CLEAR GLOBAL POSITION statement, PERM is the default.</p>
<li>When you are using the <var>Clear Global Position</var> statement, <var>Perm</var> is the default. </li>
<p>
 
The CLEARGO command has the effect of clearing all remembered positions.</p>
<li>The <var>CLEARGO</var> command has the effect of clearing all remembered positions.</li>
<p>
 
Any UTABLE command that changes the size of FTBL, GTBL, or XTBL clears all remembered positions.</p>
<li>Any <var>UTABLE</var> command that changes the size of FTBL, GTBL, or XTBL clears all remembered positions.</li>
</ul>
   
   
===Timing and placement of a CLEAR statement===
===Timing and placement of a Clear statement===
<p>
<p>
The CLEAR GLOBAL statement takes effect at evaluation time and its placement in a request can have significant consequences:</p>
The <var>Clear Global</var> statement takes effect at evaluation time and its placement in a request can have significant consequences: </p>
<ul>
<ul>
<li>If the global object being cleared is referenced in the same request, it is marked as pending clear. The global is then emptied (zero records), and all its record locks are removed. It is cleared and deleted from GTBL at the end of the request.</li>
<li>If the global object being cleared is referenced in the same request, it is marked as pending clear. The global is then emptied (zero records), and all its record locks are removed. It is cleared and deleted from GTBL at the end of the request.  
</li>
</li>
</ul>
</ul>
   
   
</div> <!-- end of toc limit div -->
[[Category:SOUL]]
[[Category:SOUL]]

Latest revision as of 23:46, 29 May 2018

Overview

Model 204 offers several global features to store information in memory so that it is not automatically cleared between requests. The memory area for storing global information is a Model 204 internal work area or server table called the global table or GTBL.

The global features are:

  • Global string variables
  • Global objects
    • Global found sets and lists
    • Global screens, images, and menus
    • Global positions

Global information is available only to the user who creates it.

GTBL internal work area

Each user's GTBL is empty when the user logs in. GTBL accumulates global information that is available for the duration of the terminal session, unless you intentionally clear it. You can clear GTBL information selectively.

For a discussion of GTBL space requirements, see GTBL (global variable table).

Global items are stored in a specific order in GTBL. As shown in GTBL internal work area, the area that stores global string variables is at the beginning of the table, and is built from the top down. The area that stores global objects is at the end of the table and is built from the bottom up. The unused or free space is between these two areas.

Storage of global variables and global objects in GTBL

Global string variables

You can use global string variables to:

  • Pass information from one request to another request
  • Include procedures conditionally at the Model 204 command level
  • Tailor a request dynamically

As of Version 5.1, you can increase the speed and reduce the CPU time to find and update a global string variable by setting the GTBLHASH parameter to a nonzero value. The GTBLHASH parameter specifies the number of buckets allocated in the global string variable section of GTBL. When GTBLHASH is a nonzero value, and you set or get a global string variable, the global string variable name is hashed to determine the bucket in which the name is located.

This reduces the overall amount of data that must be scanned to find a global string variable or must be moved when a value is deleted or changes in size. If GTBLHASH is 0, global string variables are processed as in pre-5.1 versions of Model 204.

The GTBLPCT parameter determines the initial percentage of GTBL to allocate for global string variables. The default value of GTBLPCT is 50, meaning 50 percent of GTBL is initially allocated for global variable strings. The remainder, in this case 50 percent, is the initial allocation for global objects. However, if GTBLHASH is 0, a nonzero setting for GTBLPCT has no effect.

When in effect, if either area of GTBL fills and there are still free pages in GTBL, then GTBL can be rearranged if more space is required in the full area of GTBL. Because these rearrangements can be CPU intensive, Rocket Software recommends that you determine an accurate setting for GTBLPCT to avoid frequent rearrangements. You can monitor the performance of the hash GTBL feature using the GTBLRU user statistic and the GTBLRS since-last statistic.

Rearranging GTBL and tracking the rearrangements

The following statistics are available as system statistics, user statistics and since-last statistics to keep track of GTBL rearrangements required for the hashed GTBL feature:

Statistic Tracking
GTBLRU Number of GTBL rearrangements required to add a string variable global.
GTBLRS Number of GTBL rearrangements required to add a global object.

After reviewing the GTBLRU and GTBLRS statistics, you can consider taking the following actions:

  • If both of these values are high, increase the size of GTBL by increasing LGTBL.
  • If GTBLRU is high but GTBLRS is not, increase GTBLPCT or decrease GTBLHASH.
  • If GTBLRS is high but GTBLRU is low, decrease GTBLPCT.

Global found sets and lists

You can use global found sets and lists to make found sets and lists available across request boundaries. A global found set or list remains in GTBL until you:

  • Explicitly delete it
  • Issue a Release or Commit Release statement
  • The file or group it refers to is closed, including the file close processing done when exiting a subsystem or stopping
  • Log out

Sorted sets are a subgroup of found sets; they are treated the same by the Clear statement that is used to clear global found sets.

Faster global variable processing option

When global lists or found sets are processed as part of the Find or Place Records On statement, it must be verified that a global variable representing the list or found set exists in GTBL. The CLEARG command or Clear statement may delete the global variable, so an internal routine is called to verify whether the global variable is in GTBL. The internal routine creates a new copy, if it was deleted.

The internal routine scans NTBL to find an entry that points to the required variable, then it uses its hash value to scan GTBL. Scanning a large NTBL may take considerable time.

The NTBL scan can be eliminated, if internal variables representing global lists and found sets contain a global name hash value. Thus, an internal variable with a length of eight bytes that contains an NTBL entry offset points to the internal variable representing a global list or found set. This method avoids an NTBL scan, if a global variable has been deleted from GTBL.

This faster global variable processing requires larger VTBL, because every global list or found set needs eight more bytes. If you want the benefit of this increased processing speed and can accommodate the increased VTBL requirement, set FASTGLOB to 1. To maintain existing processing you can let FASTGLOB default to 0, or you can explicitly set FASTGLOB to 0.

Global positions

You can use Remember and Position statements to save and recall a place in a For loop, either globally or non-globally. This lets you suspend processing in a For loop and resume it later, within the same request or in a subsequent request.

Global images and screens

You can use global images and screens to:

  • Pass image and screen data from one request to another
  • Manage more than one image or screen in one request
  • Manage menus, which are a special type of screen
  • Reduce I/O by swapping modified global screens to CCASERVR instead of paging them between the buffer pool and CCATEMP

Global string variables

Global string variable names and values

Entries in the GTBL consist of global name=value pairs. The names and values of the global string variables are created with the $Setg function from within a request.

  • A global string variable name can consist of up to 255 characters and follows the naming conventions for variables (see %Variable names). Global string variables that contain special characters, other than a period (.) cannot be used as ?& dummy strings.
  • A value can be 0, the null string, or up to 255 characters.

Clearing global string variables

When a new value for an existing name is stored, the old entry is first deleted. Entries remain in the table until you delete them by issuing a CLEARG command, execute a Clear statement, execute a $Delg function call, or you log out.

If you define a large number of global string variables, Model 204 performance can be adversely affected.

For details and examples of clearing global string variables, see Clearing the GTBL work area.

Global variable functions and commands

The following functions, statements, commands, and facilities manipulate entries in the global variable table:

  • Use the functions $Setg and $Getg within a request to store and retrieve global string variables. Use $Incrg to perform simple arithmetic on global string variables with numeric values. Use the $Delg function to delete global string variables created by $Setg or $Incrg.
  • Use the ?& dummy string within a request to read a variable in the GTBL. Refer to Procedures for more information about dummy strings.
  • Use the conditional INCLUDE command (IF A=B,name) to search the global variable table for an entry whose name is A and whose value is B. If the entry is found, the named procedure is included. The IF command is discussed on Conditional and unconditional INCLUDEs.

Using global string variables in application subsystems

In addition to the above facilities, an application subsystem can designate specific global string variables in the subsystem definition. For more information about subsystem global string variables, refer to:

Passing string values from one request to another

It is often necessary to generate data in one request and to save the data for use in other independent requests to be run later in the terminal session.

Example 1

Suppose that you want to store the current date in every record created during a session in YYMMDD format, a modified form of the value returned by the $Date function. You can derive the date once at the beginning of the day and hold it for use throughout the day.

At the beginning of the terminal session, you enter:

BEGIN %DATE = $DATE %DATE = $SUBSTR(%DATE, 1, 2) - WITH $SUBSTR(%DATE, 4, 2) WITH - $SUBSTR(%DATE, 7, 2) IF $SETG('DATE', %DATE) THEN PRINT '*** REQUEST TOO LONG - GTBL' STOP END IF END

Later in the terminal session, you can use the specially formatted date:

BEGIN %DATE = $GETG('DATE') STORE RECORD FIELD = VALUE FIELDB = VALUE DATE = %DATE . . . END STORE

Example 2

Assume that different sets of records are processed and the results are used to produce a final report. Because of compiler table limitations, you have to process requests that cannot be continued with the MORE command (see Large request considerations). You can store intermediate results in GTBL and produce the final report exclusively from the table.

For example:

BEGIN . . . process hourly workers' wages . . . IF $SETG('HOURLY TOTAL', %TOTAL) THEN PRINT '*** REQUEST TOO LONG - GTBL' STOP END IF END BEGIN . . . process monthly workers' wages . . . IF $SETG('MONTHLY TOTAL', %TOTAL) THEN PRINT '*** REQUEST TOO LONG - GTBL' STOP END IF END BEGIN %HOURLY = $GETG('HOURLY TOTAL') %MONTHLY = $GETG('MONTHLY TOTAL') . . . format report . . . END

Using global string variables with a conditional INCLUDE command

You can use global string variables to create a modular programming environment in which you select procedures to perform a particular function without compiling and evaluating procedures designed for other related functions.

To use global string variables effectively in creating such an environment, it is useful to review the differences between commands and User Language statements and between conditional and unconditional includes, as described in the following sections.

Differences between commands and User Language statements

Commands and User Language statements have different effects and are used in different ways:

  • System control commands can be issued only outside a request — at command level. They are acted upon immediately. User Language statements can be used only within a request. They are compiled on a line-by-line basis, but the entire request is not executed until Model 204 receives an END statement.
  • INCLUDE is both a command and a User Language statement. In either context, Model 204 is directed to take the next input line from an appropriate stored procedure. When the procedure lines are exhausted, the next input line is taken from the command or User Language statement immediately following the INCLUDE.
  • IF has two formats:
    • Conditional INCLUDE command
    • User Language statement

Conditional and unconditional INCLUDEs

A conditional include can be coded within an IF statement using the INCLUDE statement or with an INCLUDE command.

An unconditional include can be coded with a standalone INCLUDE statement or command.

This section describes conditional INCLUDE commands by providing examples and discussing how each example is processed.

Example 1

The following request illustrates the conditional INCLUDE command:

BEGIN ALL: FIND ALL RECORDS END FIND FOR EACH RECORD IN ALL IF AGE GT '10' THEN IF $SETG('AGE', 'YES') THEN PRINT '*** REQUEST TOO LONG - GTBL' STOP END IF END IF END FOR END IF AGE = YES, COUNT

How Example 1 is processed

The statements between the BEGIN and END are compiled and evaluated. If the AGE condition is true, a global string variable is set. Model 204 then processes the IF command. Statements in the COUNT procedure are compiled and executed only if the condition is true. Otherwise, the statements are never compiled.

Example 2

Suppose that you enter record selection criteria and then select one of three reports to be generated. A set of four procedures can be created.

For example, procedure A might contain the prompts for record selection and report type. Procedures B, C, and D might contain statements to produce the individual reports. Only procedure A and one of the other three procedures is compiled and evaluated.

PROCEDURE A BEGIN FIND.RECS: FIND ALL RECORDS FOR WHICH  ??SELECT.RECORDS END FIND IF $SETG('REPORTNUM', $READ('ENTER REPORT NO')) THEN PRINT '*** REQUEST TOO LONG - GTBL' STOP END IF END MORE IF REPORTNUM = 1, B IF REPORTNUM = 2, C IF REPORTNUM = 3, D END PROCEDURE

Procedures B, C, and D have the same basic format, but variations in processing are applied to each record.

PROCEDURE B MORE PROCESS: FOR EACH RECORD IN FIND.RECS . . . processing . . . END FOR PROCESS END END PROCEDURE

How Example 2 is processed

The dialog produced by these procedures is shown below, with user input in boldface:

INCLUDE A ??SELECT.RECORDS REGION = SOUTH OR WEST $$ENTER REPORT NO 2 output from Procedure C

Keep IF commands at as high a nesting level as possible

An alternate method of writing procedures is to follow each report's END MORE statement with IF commands. However, each procedure might then INCLUDE itself or another procedure, creating a lower level of nesting. If the procedure continued to INCLUDE itself, the maximum nesting level would be reached. As a general rule in a complex set of procedures, keep IF commands at as high a nesting level as possible. The global string variables to be tested can be set at any level.

Using global string variables to tailor a request

Global string variables can be used in conjunction with the FILE$ condition (see FILE$ condition) to access a set of files in a group.

Example

In the following example, the value of the global string variable, FILES, can be changed to access an alternative set of files. This example consists of two requests. The first — BEGIN through END MORE — sets the global string variable during the execution phase; the second — MORE through END — is then compiled with the correct value.

BEGIN . . . IF $SETG('FILES','FILEA OR FILE$ FILEC') THEN PRINT '***REQUEST TOO LONG -- GTBL' %IGNORE = $SETG('FILES', '') END IF END MORE MORE IF $GETG('files') = '' THEN STOP END IF GET.A: FIND ALL RECORDS FOR WHICH (FILE$ ?&FILES) AND FIELDX = 'A' END FIND FOR EACH RECORD IN GET.A PRINT ALL INFORMATION END FOR END

Global objects

Global objects include found sets, images, lists, menus, positions, screens, and sorted sets.

General rules for declarations

  • You must declare global lists, found sets, and sorted sets in every request that references them; the Declare statement must come before the reference.
  • If a global object is used in multiple subroutines, or in both the main program and a subroutine, the label must be declared as global in the main program before the subroutine(s). The subroutine(s) must then declare the label as common.
  • If you refer to a global object before a Declare statement, the system issues a duplicate label compilation error. Such a reference implicitly makes the object non global.

Incompatibility

The PQO product does not support global found sets, lists, positions, or sorted sets. These global objects cannot be used in conjunction with remote files or scattered groups. This limitation exists, because GTBL does not exist on the PQO server.

Clearing global objects from GTBL

For syntax, details and examples of clearing global objects, see Clearing the GTBL work area.

Using global found sets and lists

You can pass found sets and lists from request to request by declaring them as Global. A global found set or list is stored in the internal work area GTBL for the duration of the terminal session unless it is intentionally cleared, or the file or group with which it is associated is closed.

Creating a global found set or sorted set

You can create a global found set using this syntax:

Syntax

[Declare] Label labelname [Global | Common]

Where labelname is a unique global object name.

Creating a global list

You can declare a global list using the following syntax:

[Declare] List listname [In [File [Perm | Temp] Group] name] [Global | Common]

In both cases, the keyword Global implies Common. These two keywords are mutually exclusive in the declaration statement.

  • Because Global implies Common, a list or found set can be declared Global at any scope. See Scope of elements for a discussion.
  • The global name, label name, or list name, must be unique across all global objects. For a discussion, see Sharing common elements.

Usage rules

The following rules apply to global found sets and lists:

  • You must declare each global list or global found set as labelname Global in each procedure that uses it.
  • The file context in which a global list or found set is used must be the same as the file context in which it was created.

    The Model 204 compiler does not currently enforce this rule; therefore, your code must maintain this requirement. Rocket Software recommends that you populate a global found set or list only once within the scope of these global objects. However, this is not a restriction as long as file context is maintained.

  • Global found sets and lists are invalid in ad hoc group context.
  • Each global object name must be unique.
  • Global found sets and lists are not supported in remote file or scattered group contexts.

Example 1: Referencing a global found set

In this example, Procedure 1 declares the global found set and then performs the find. Procedure 2 needs only to declare the global found set and then reference the global found set labeled F1. The For loops in both procedures process records in the VEHICLES file for which the value of the field COLOR was equal to BLUE at the time of the evaluation of the Find statement in Procedure 1.

Procedure 1

BEGIN DECLARE LABEL F1 GLOBAL F1: IN VEHICLES FIND ALL RECORDS WHERE COLOR = 'BLUE' END FIND FOR EACH RECORD IN F1 PAI END FOR END

Procedure 2

BEGIN DECLARE LABEL F1 GLOBAL FOR EACH RECORD IN F1 PAI END FOR END

Example 2: Maintaining file context

Example 2 illustrates repopulating a global found set across the scope of its usage, maintaining the same file context throughout. In this example, Procedure 1 is identical to Procedure 1 in Example 1 above, and Procedure 3 is identical to Procedure 2 in Example 1. The second procedure in this example, however, performs a different find than the first. Procedure 3 then processes the records found in Procedure 2.

So in this example, Procedure 1 processes records in the VEHICLES file for which the value of the field COLOR is equal to BLUE, while Procedures 2 and 3 process records for which COLOR was equal to RED at the time of the Find statement evaluation in Procedure 2.

Procedure 1

BEGIN DECLARE LABEL F1 GLOBAL F1: IN VEHICLES FIND ALL RECORDS WHERE COLOR = 'BLUE' END FIND FOR EACH RECORD IN F1 PAI END FOR END

Procedure 2

BEGIN DECLARE LABEL F1 GLOBAL F1: IN VEHICLES FIND ALL RECORDS WHERE COLOR = 'RED' END FIND FOR EACH RECORD IN F1 PAI END FOR END

Procedure 3

BEGIN DECLARE LABEL F1 GLOBAL FOR EACH RECORD IN F1 PAI END FOR END

Using global sorted sets

A global sorted set is created when a SORT RECORDS statement or a FOR EACH RECORD IN ORDER BY statement is preceded by a label that has been declared GLOBAL.

Limiting subsequent references

For example, in Procedure 1 below, MAKE is the only field referenced in the request. Therefore, MAKE is the only field that can be referenced in subsequent requests. Thus, in Procedure 2, because the field MODEL was not referenced in the previous request, a blank is printed each time through the FOR loop.

Procedure 1

BEGIN DECLARE LABEL S1 GLOBAL F1: IN VEHICLES FIND ALL RECORDS END FIND S1: SORT RECORDS IN F1 BY MAKE FOR EACH RECORD IN S1 PRINT MAKE END FOR END

Procedure 2

BEGIN DECLARE LABEL S1 GLOBAL FOR EACH RECORD IN S1 PRINT MODEL END FOR END

Keeping all fields accessible for subsequent references

To ensure that all fields are accessible to subsequent requests, use a PAI or field name variable with the statement that creates the found set.

The sort key field(s) used on the SORT statement cannot be referred to by a subsequent request unless referred to in the SORT statement FOR loop in the request creating the set. While this restriction applies to the use of the SORT RECORDS statement, it does not apply to the use of the SORT RECORD KEYS statement.

If you are not going to refer to the sorted set in the request that creates the sorted set, you can code a FOR loop, which is compiled but never executed, that refers to each field that you want to refer to in a subsequent request.

Saving and recalling a position in a For loop

You can include statements in a For loop to provide for the possibility of terminating the loop before the set of records or values being processed is exhausted. For example, you might use a Jump To or Loop End statement in conjunction with an If statement to test each record or value before processing, and terminating the loop if a certain condition is met.

The Remember and Position statements let you store the current processing position in a For loop, then recall it at a later time and resume For processing where you left off earlier.

Remember statement

The purpose of the Remember statement is to store the processing position in a For loop. Each Remember statement creates a GTBL entry of variable length. See Large request considerations for detailed descriptions of GTBL entries. If you remember a position as Global, the entry remains in GTBL after the current request ends. Model 204 clears non-global Remember positions at the end of each request.

Syntax

Remember [Global] position_name [In foundsortset_name | On list_name]

Where:

  • The Global option retains the Remember position after the current request terminates. If Global is not specified, the position is temporary, and it is cleared from GTBL after the current request terminates.
  • position_name is a unique object name you assign to the Remember position.
  • foundsortset_name or list_name must be identical to the listname or label specified on the For loop:
    • If you are processing a found set or a sorted set, In foundsortset_name is the label of the Find statement that generated it.
    • If you are processing a list, On list_name is the name you gave to the list when you originally declared it.

Usage notes

The following rules apply to the use of the Remember statement:

  • Can appear only within a For loop, but not a nested For loop. The file context must be identical to the context of the For loop.
  • Is invalid in ad hoc group context, if used with the Global option.
  • The Remember statement is incompatible with For Each Record In Order By clauses.

Position statement

A Position statement recalls a remembered position, so you can resume For processing in a list or found set that was terminated at an earlier time. For example, if you remembered the position at record number 5, then your foundset is positioned at record number 6 for further processing.

This Position statement is not to be confused with the Position statement used to read records sequentially in an external VSAM KSDS file. See Position statement.

Syntax

Position {Foundset foundsortset_name | List list_name} [At] position_name

Where:

  • foundsortset_name or list_name must be identical to the list or label name used on a previous Remember statement and in the For statement that follows.

    If you are about to resume the processing of a found set, foundsortset_name is the label of the Find statement that generated it.

    If you are about to resume the processing of a list, list_name is the name you gave to the list when you originally declared it.

  • position_name is a name that you assigned to the remembered position when you stored it on a previous Remember statement.

Usage notes

The following rules apply:

  • The Position statement must appear outside, immediately before the For loop to which it refers; it cannot be in the For loop itself.
  • The For statement that follows the Position statement must have an identical file context and list name or label name as the statement that initiated the For loop of the remembered position.
  • The Position statement is incompatible with For Each Record In Order By clauses.

Global images and screens

You can use global images and screens to pass image and screen data from one request to another and to efficiently manage more than one image or screen in one request.

You can also declare global menus, because a menu is a special type of screen. In this section, the term "screen" applies to both screens and menus, unless otherwise noted.

Declaring global images and screens

You make an image or screen global by specifying the keyword Global in its declaration statement. You can declare global images and screens to be Temporary, deleted at request termination, or Permanent, persist across request termination.

How images and screens are processed

When you declare an image or screen as Global, it is stored in GTBL. Nonglobal images and screens, declared as Common, or neither Common nor Global, are stored in FSCB.

This section provides some background information about how Model 204 processes images and screens, contrasting how global and nonglobal images and screens are processed.

Images and screen processing

The figures in the following subsections represent how nonglobal and global objects are processed. Comparing the two types of processing highlights the I/O and storage savings associated with the global images and screens.

Processing of nonglobal objects

The Nonglobal object processing figure illustrates the process in the following steps:

  1. The compiler loads a compiled version of the screen or image into FSCB in the user's server.
  2. A copy of the compiled object is stored in the buffer pool.
  3. A Prepare statement acts on the compiled object in the buffer pool and copies it into FSCB.
  4. Update statements act on the copy of the object in FSCB.
  5. The updated object is copied from FSCB to a working copy of the object in the buffer pool.
  6. If a user waits too long or the buffer pool fills up, the object is written to CCATEMP. When a user presses Enter for that object, the object is loaded back from CCATEMP to the buffer pool.

 

Processing of global objects

The Global object processing figure illustrates the process in the following steps:

  1. The compiler loads a compiled version of the screen or image into FSCB in the user's server.
  2. A copy of the compiled object is stored in the buffer pool. This copy is called 'VIRGIN', as it is never updated.
  3. A Prepare statement acts on the compiled object in the buffer pool and copies it into GTBL.
  4. Update statements act on the copy in GTBL.

Using Prepare and Identify statements

To help you decide how to use the Prepare and Identify statements, review the following:

Performance and efficiency benefits

Global images and screens can simply and efficiently perform image-to-image processing and screen-to-image processing, eliminating the need to map screen items to image items when passing or preserving screens. Using global images and screens:

  • Reduces CPU resources required to pass data between requests in applications where a large number of global variables would have been necessary.
  • Reduces the FSCB I/O between multiple images and between images and screens.
  • Makes the declaration of global data explicit, thus traceable by using naming conventions and cross-reference tools.
  • Simplifies code, eliminating the need for If $Setg() Then ... sequences to map request %variables into global variables and for %xyz = $Getg() sequences to map global variables into request %variables.
  • Reduces I/O by swapping modified global screens to CCASERVR instead of paging them between the buffer pool and CCATEMP.

When to use global images and screens

You achieve the greatest benefit by declaring as Global the most frequently used images and screens in an application.

Infrequently used images and screens declared as nonglobal do not put pressure on the buffer pool, because there would not be many copies in the buffer pool for many users, and little I/O with CCATEMP. If an application has many images and/or screens, GTBL might overflow if all the images and/or screens are defined as global.

Consistency checks performed

When a global image or screen is first referred to in a request, GTBL is searched for the object.

If the object is not already present in GTBL, the object is written into GTBL.

If the object is present, two consistency checks are performed:

  • Persistence — Permanent or Temporary status — of the new object must match the persistence of the object already in GTBL.
  • Definition — Permanent or Temporary — of the new object must match the definition of the object already in GTBL.

Note: If a global image has an array that uses the Depending On %variable option, the names of the %variables are not compared when the definition check is performed.

If either of these consistency checks fails — for example, an image is declared as Temporary, but the same image already exists in GTBL, declared as Permanent — then the request is canceled and the M204.2158 message is generated:

Global object-type definition doesn't match value in GTBL​,​ error-description, name hash=hash-code

Using global images and screens

The following example illustrates using global images and screens to pass screen and image data between User Language requests. The example consists of the following procedures:

  • SCREENDEF defines a global screen.
  • IMAGEDEF defines a global image.
  • PROCA sets the screen item value and an image item value.
  • PROCB displays the updated image item and the original screen item.

PROCEDURE SCREENDEF * KEEP GLOBAL SCREENS AND IMAGES IN SEPARATE PROCEDURES * FOR CENTRAL DEFINITION SCREEN SCREEN1 GLOBAL PROMPT 'SCREEN1' INPUT ITEM NUMERIC LEN 4 AT 10 END SCREEN END PROCEDURE PROCEDURE IMAGEDEF * KEEP GLOBAL SCREENS AND IMAGES IN SEPARATE PROCEDURES * FOR CENTRAL DEFINITION IMAGE IMAGE1 GLOBAL ITEM IS FLOAT LEN 8 END IMAGE END PROCEDURE PROCEDURE PROCA BEGIN INCLUDE SCREENDEF INCLUDE IMAGEDEF * INITIALIZE SCREEN1 AND IMAGE1 PREPARE SCREEN SCREEN1 PREPARE IMAGE IMAGE1 * USER SEES SCREEN1 AND ENTERS A VALUE N (E.G., 10) AS INPUT READ SCREEN SCREEN1 %IMAGE1:ITEM = %SCREEN1:ITEM + 3 END END PROCEDURE PROCEDURE PROCB BEGIN INCLUDE SCREENDEF INCLUDE IMAGEDEF * DO NOT INITIALIZE, JUST IDENTIFY FOR SUBSEQUENT REFERRAL IDENTIFY IMAGE IMAGE1 * USER SEES UPDATED IMAGE ITEM (N+3) IN NEW REQUEST PRINT 'IMAGE ITEM = ' WITH %IMAGE1:ITEM * USER SEES ORIGINAL SCREEN ITEM WITH DATA THAT USER ENTERED READ SCREEN SCREEN1 END END PROCEDURE

Note: You can run several procedures between PROCA and PROCB with the same results as if you ran those two procedures sequentially, because the defined global objects persist.

System administration issues

To review the implications of the global images and screens feature for system administrators, see the following topics:

Clearing the GTBL work area

When you log off, all global objects and global variables are cleared. If you want to clear some or all global objects or global variables from GTBL during your working session, prior to logging out, you can issue:

  • CLEAR statement
  • CLEARG and/or CLEARGO commands
  • $DELG function to selectively delete global string variables
  • RESET command for the GTBLEHASH and GTBLPCT parameters
  • UTABLE command that changes the size of FTBL, XTBL, or GTBL clears all global objects of any type

Using the CLEARG and CLEARGO commands

Use this command To Remove...
CLEARG Only global string variables.
CLEARGO All global objects: images, screens, menus, found sets, lists, and temporary and permanent positions from GTBL; it does not clear global string variables.

The CLEARGO command takes no arguments.

Using the $DELG function

You can use the $Delg function to delete global string variables created by either $Setg or $Incrg.

The $Delg function deletes a single or group of similar global string variables, releasing and compacting the GTBL space for reuse.

Using the CLEAR statement

You can use the Clear statement to clear global objects of the same type, an individual global object, or all global string variables, as shown in the following table:

The statement Clears...
Clear type-of-object Objects A class of global objects or all global objects. Global string variables are not cleared, because they are not objects.
Clear Global Individual global objects from GTBL.
Clear Globals All global string variables. You cannot selectively clear individual global string variables with the Clear statement.

Syntax

The format for the Clear statement is:

Clear {[[All | Temp | ListFdst | Position] [Global]] Objects | Globals | Global {Image | Screen | Menu | List | Foundset | Position [Perm | Temp]} {'objectname' | %variable}}

Where:

  • All clears all permanent and temporary global objects, including: found sets, lists, images, menus, positions, screens, and sorted sets from GTBL.
  • Temp clears only global objects explicitly declared as Temp in your request, including images, menus, and screens from GTBL.
  • ListFdst clears all global found sets, lists, and sorted sets from GTBL.
  • Position clears all permanent and temporary positions from GTBL.
  • Objects specifies that the CLEAR command is operating on the object type you specified, or operating on all types of objects.
  • Global clears a specific global object from GTBL. You cannot clear a global string variable created with the $Setg function using this form.
  • objectname is the literal name of the specific global object to be cleared from GTBL. Enclose objectname in single quotation marks.
  • %variable contains a value that specifies the global object to be cleared from GTBL.
  • Globals clears all global string variables created with the $Setg function from GTBL. This form does not clear any global objects.

Usage notes

The following statements clear all permanent and temporary global found sets, images, lists, menus, positions, screens, and sorted sets:

Clear Objects Clear All Objects Clear All Global Objects Clear Global Objects

Clearing global found sets and lists

You can clear global found sets and lists in GTBL without logging off using the following examples:

  • Clear a specific global list or found set by issuing one of these statements:

    Clear Global List 'objectname' Clear Global List %variable Clear Global Foundset 'objectname' Clear Global Foundset %variable

  • Clear all global found sets and lists with the statement:

    Clear ListFdst [Global] Objects

    (Global found sets and lists are among the global objects cleared by the CLEARGO command.)

  • Close a file or group with which a global list or found set is associated. This includes the file close processing done when exiting or stopping a subsystem.
  • Issue a UTABLE command that changes the size of FTBL, XTBL, or GTBL.

If you clear a global list or global found set, then any request that uses the global and does not have the Find statement that creates the global object receives either of the following error messages:

M204.0301 Referenced statement label undefined M204.0311 Unacceptable statement reference

RELEASE and COMMIT RELEASE statements with global foundsets and lists

The Release statements and the Commit Release statements empty the contents of a global found set, global sort set, or global list. The label and positions associated with a found set, sort set, or the list is still considered global, but it is empty. Global positions are not cleared by Release or Commit Release statements, however, without records there is nothing to process.

Clearing remembered positions

Each Remember statement creates a GTBL entry, whether or not Global is specified. If GLOBAL is not specified, the position is temporary and is cleared from GTBL at the end of request execution.

All remembered positions, along with all other GTBL entries, are cleared when you log off. You can also clear remembered positions in the following ways:

  • You can clear a specific temporary position by issuing one of these statements:

    Clear Global Position Temp 'objectname' Clear Global Position Temp %variable

  • You can clear a specific permanent position by issuing one of these statements:

    Clear Global Position Perm 'objectname' Clear Global Position Perm %variable

  • You clear all global found sets, lists, or sorted sets with which a remembered position is associated:

    Clear ListFdst [Global] Objects

  • You clear all remembered positions by issuing the statement:

    Clear Position [Global] Objects

Usage notes

  • When you are using the Clear Global Position statement, Perm is the default.
  • The CLEARGO command has the effect of clearing all remembered positions.
  • Any UTABLE command that changes the size of FTBL, GTBL, or XTBL clears all remembered positions.

Timing and placement of a Clear statement

The Clear Global statement takes effect at evaluation time and its placement in a request can have significant consequences:

  • If the global object being cleared is referenced in the same request, it is marked as pending clear. The global is then emptied (zero records), and all its record locks are removed. It is cleared and deleted from GTBL at the end of the request.