Global features: Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (Admin moved page Global Features to Global features without leaving a redirect: title caps)
m (mixed case for statements)
 
(23 intermediate revisions by 3 users not shown)
Line 1: Line 1:
===Overview===
<div class="toclimit-3">
<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>
==Overview==
<p>The global features are:</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 the <b>global table</b> or GTBL. </p>
<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>Global found sets and lists</p>
<p>
<p>Global screens, images, and menus</p>
Global information is available only to the user who creates it. </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====
<p>
<p>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. </p>
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. </p>
<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>
For a discussion of GTBL space requirements, see [[Large request considerations#GTBL (global variable table)|GTBL (global variable table)]].</p>
[[File:Storage_of_global_vars_in_GTBL.jpg]]
<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>
<p class="caption" style="width:450px">Storage of global variables and global objects in GTBL </p>
<p class="figure">[[File:Storage_of_global_vars_in_GTBL.png|450px]] </p>


<b>Storage of global variables and global objects in GTBL</b>
==Global string variables==
 
<p>
====Global string variables====
You can use global string variables to: </p>
<p>You can use global string variables to: </p>
<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>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. </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>. See "GTBLHASH: Number of bucket for global string variables" in the Rocket <var class="product">Model&nbsp;204</var> Parameter and Command Reference Manual.</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 <var>GTBLHASH</var> parameter specifies the number of buckets allocated in the global string variable section of GTBL.
<p>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=0, a nonzero setting for GTBLPCT has no effect. </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>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. See "GTBLPCT: Initial percentage of GTBL to allocate for global string variables" in the Rocket <var class="product">Model&nbsp;204</var> Parameter and Command Reference Manual. </p>
<p>
<b>Rearranging GTBL and tracking the rearrangements</b>
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>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: </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 <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>
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>
====Rearranging GTBL and tracking the rearrangements====
<p>
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: </p>
<table>
<table>
<tr class="head">
<tr class="head">
Line 39: 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 48: Line 69:
</tr>
</tr>
</table>
</table>
<p>After reviewing the GTBLRU and GTBLRS statistics, you can consider taking the following actions: </p>
<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====
<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>
===Global found sets and lists===
<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>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>
<p>
<b>Faster global variable processing option</b>
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>
<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>
<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>
====Faster global variable processing option====
<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 FASTGLOB default to 0 or explicitly set FASTGLOB=0. See "FASTGLOB: Processing global lists and found sets" in the Rocket <var class="product">Model&nbsp;204</var> Parameter and Command Reference Manual.</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>
====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>
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>
====Global images and screens====
<p>
<p>You can use global images and screens to:</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>
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>
===Global positions===
<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===
<p>
You can use global images and screens to:</p>
<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====
<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>
===Global string variable names and values===
<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====
<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>
===Clearing global string variables===
<p>If you define a large number of global string variables, <var class="product">Model&nbsp;204</var> performance can be adversely affected. </p>
<p>
<p>For details and examples of clearing global string variables, see [[#Clearing the GTBL work area|Clearing the GTBL work area]].</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>
====Global variable functions and commands====
<p>
<p>The following functions, statements, commands, and facilities manipulate entries in the global variable table:</p>
If you define a large number of global string variables, <var class="product">Model&nbsp;204</var> performance can be adversely affected. </p>
<p>
For details and examples of clearing global string variables, see [[#Clearing the GTBL work area|Clearing the GTBL work area]].</p>
===Global variable functions and commands===
<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====
 
<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>
===Using global string variables in application subsystems===
<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>
===Passing string values from one request to another===
<p>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. </p>
==Passing string values from one request to another==
<b>Example 1</b>
<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>
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. </p>
<p>At the beginning of the terminal session, you enter:</p>
====Example 1====
<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>
At the beginning of the terminal session, you enter:</p>
<p class="code">BEGIN
<p class="code">BEGIN
     %DATE = $DATE
     %DATE = $DATE
Line 136: Line 181:
           STOP
           STOP
     END IF
     END IF
END  
END
</p>
</p>
<p>Later in the terminal session, you can use the specially formatted date:</p>
<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 148: Line 194:
             .
             .
             .
             .
     END STORE  
     END STORE
</p>
</p>
<b>Example 2</b>
<p>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.  </p>
====Example 2====
<p>For example:</p>
<p>
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.  </p>
<p>
For example:</p>
<p class="code">BEGIN
<p class="code">BEGIN
           .
           .
Line 165: Line 214:
           STOP
           STOP
       END IF
       END IF
 
END
END
 
BEGIN
BEGIN
           .
           .
Line 181: Line 230:
       END IF
       END IF
END
END
 
BEGIN
BEGIN
       %HOURLY = $GETG('HOURLY TOTAL')
       %HOURLY = $GETG('HOURLY TOTAL')
Line 192: Line 241:
           .
           .
           .
           .
END  
END
</p>
</p>
===Using global string variables with a conditional INCLUDE command===
<p>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. </p>
==Using global string variables with a conditional INCLUDE command==
<p>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.</p>
<p>
====Differences between commands and User Language statements====
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. </p>
<p>Commands and User Language statements have different effects and are used in different ways: </p>
<p>
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.</p>
===Differences between commands and User Language statements===
<p>
Commands and User Language statements have different effects and are used in different ways: </p>
<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>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>IF has two formats:
<ul>
<ul>
<li>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 <var class="product">Model&nbsp;204</var> receives an END statement.    </li>
<li>Conditional INCLUDE command</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>User Language statement </li>
</li>
</ul></li>
<li>IF has two formats:</li>
</li>
</ul>
</ul>
<p>Conditional INCLUDE command</p>
<p>User Language statement </p>
===Conditional and unconditional INCLUDEs===
====Conditional and unconditional INCLUDEs====
<p>
<p>A conditional include can be coded within an IF statement using the INCLUDE statement or with an INCLUDE command.</p>
A conditional include can be coded within an IF statement using the INCLUDE statement or with an INCLUDE command.</p>
<p>An unconditional include can be coded with a standalone INCLUDE statement or command.</p>
<p>
<p>This section describes conditional INCLUDE commands by providing examples and discussing how each example is processed.</p>
An unconditional include can be coded with a standalone INCLUDE statement or command.</p>
<b>Example 1</b>
<p>
<p>The following request illustrates the conditional INCLUDE command:</p>
This section describes conditional INCLUDE commands by providing examples and discussing how each example is processed.</p>
====Example 1====
<p>
The following request illustrates the conditional INCLUDE command:</p>
<p class="code">BEGIN
<p class="code">BEGIN
ALL: FIND ALL RECORDS
ALL: FIND ALL RECORDS
Line 227: Line 288:
     END FOR
     END FOR
END
END
IF AGE = YES, COUNT  
IF AGE = YES, COUNT
</p>
</p>
<b>How Example 1 is processed</b>
<p>The statements between the BEGIN and END are compiled and evaluated. If the AGE condition is true, a global string variable is set. <var class="product">Model&nbsp;204</var> 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.</p>
====How Example 1 is processed====
<b>Example 2</b>
<p>
<p>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.</p>
The statements between the BEGIN and END are compiled and evaluated. If the AGE condition is true, a global string variable is set. <var class="product">Model&nbsp;204</var> 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.</p>
<p>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. </p>
====Example 2====
<p>
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.</p>
<p>
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. </p>
<p class="code">PROCEDURE A
<p class="code">PROCEDURE A
BEGIN
BEGIN
Line 239: Line 305:
               ??SELECT.RECORDS
               ??SELECT.RECORDS
           END FIND
           END FIND
           IF $SETG('REPORTNUM', $READ('ENTER REPORT NO'))  
           IF $SETG('REPORTNUM', $READ('ENTER REPORT NO'))
               THEN PRINT '*** REQUEST TOO LONG - GTBL'
               THEN PRINT '*** REQUEST TOO LONG - GTBL'
               STOP
               STOP
Line 247: Line 313:
IF REPORTNUM = 2, C
IF REPORTNUM = 2, C
IF REPORTNUM = 3, D
IF REPORTNUM = 3, D
END PROCEDURE  
END PROCEDURE
</p>
</p>
<p>Procedures B, C, and D have the same basic format, but variations in processing are applied to each record.</p>
<p>
Procedures B, C, and D have the same basic format, but variations in processing are applied to each record.</p>
<p class="code">PROCEDURE B
<p class="code">PROCEDURE B
MORE
MORE
Line 262: Line 329:
         END FOR PROCESS
         END FOR PROCESS
END
END
END PROCEDURE  
END PROCEDURE
</p>
</p>
<b>How Example 2 is processed</b>
<p>The dialog produced by these procedures is shown below, with user input in boldface:</p>
====How Example 2 is processed====
<p class="code">INCLUDE A
<p>
The dialog produced by these procedures is shown below, with user input in boldface: </p>
<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>
<b>Keep IF commands at as high a nesting level as possible</b>
 
<p>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.</p>
====Keep IF commands at as high a nesting level as possible====
===Using global string variables to tailor a request===
<p>
<p>Global string variables can be used in conjunction with the FILE$ condition (see [[Record retrievals#FILE$ condition|FILE$ condition]]) to access a set of files in a group. </p>
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.</p>
<b>Example</b>
<p>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.  </p>
==Using global string variables to tailor a request==
<p>
Global string variables can be used in conjunction with the FILE$ condition (see [[Record retrievals#FILE$ condition|FILE$ condition]]) to access a set of files in a group. </p>
====Example====
<p>
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 &mdash; BEGIN through END MORE &mdash; sets the global string variable during the execution phase; the second &mdash; MORE through END &mdash; is then compiled with the correct value.  </p>
<p class="code">BEGIN
<p class="code">BEGIN
               .
               .
Line 285: 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 298: Line 373:
               PRINT ALL INFORMATION
               PRINT ALL INFORMATION
           END FOR
           END FOR
END  
END
</p>
</p>
===Global objects===
<p>Global objects include found sets, images, lists, menus, positions, screens, and sorted sets. </p>
==Global objects==
====General rules for declarations====
<p>
Global objects include found sets, images, lists, menus, positions, screens, and sorted sets. </p>
===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====
<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>
===Incompatibility===
====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>
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>
===Using global found sets and lists===
<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>
===Clearing global objects from GTBL===
<b>Creating a global found set or sorted set</b>
<p>
<p>You can create a global found set using this syntax:</p>
For syntax, details and examples of clearing global objects, see [[#Clearing the GTBL work area|Clearing the GTBL work area]]. </p>
<b>Syntax</b>
<p class="code"><var>[</var>DECLARE<var>]</var> LABEL labelname [GLOBAL | COMMON]
</p>
<p>Where labelname is a unique global object name.</p>
<b>Creating a global list</b>
<p>You can declare a global list using the following syntax:</p>
<b>Syntax</b>
<p class="code"><var>[</var>DECLARE<var>]</var> LIST listname


   [IN [FILE [PERM | TEMP] GROUP] name]
==Using global found sets and lists==
 
<p>
   [GLOBAL | COMMON]
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>
</p>
<p>In both cases, the keyword GLOBAL implies COMMON. These two keywords are mutually exclusive in the declaration statement. </p>
====Creating a global found set or sorted set====
<p>
You can create a global found set using this syntax: </p>
====Syntax====
<p class="syntax">[Declare] Label <span class="term">labelname</span> [Global | Common] </p>
<p>
Where <var class="term">labelname</var> is a unique global object name.</p>
====Creating a global list====
<p>
You can declare a global list using the following syntax:</p>
<p class="code">[Declare] List <span class="term">listname</span>
   [In [File [Perm | Temp] Group] <span class="term">name</span>]
   [Global | Common] </p>
<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>
<b>Usage rules</b>
<p>The following rules apply to global found sets and lists:</p>
====Usage rules====
<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>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>
<p>
</li>
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>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====
<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>
===Example 1: Referencing a global found set===
<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>
<b>Procedure 1</b>
<b>Procedure 1</b>
<p class="code">BEGIN
<p class="code">BEGIN
Line 366: Line 456:
END
END
</p>
</p>
<b>Procedure 2</b>
<b>Procedure 2</b>
<p class="code">BEGIN
<p class="code">BEGIN
Line 374: Line 465:
END
END
</p>
</p>
====Example 2: Maintaining file context====
<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: Maintaining file context===
<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>
<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>
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>
<b>Procedure 1</b>
<b>Procedure 1</b>
<p class="code">BEGIN
<p class="code">BEGIN
Line 387: Line 482:
END
END
</p>
</p>
<b>Procedure 2</b>
<b>Procedure 2</b>
<p class="code">BEGIN
<p class="code">BEGIN
Line 397: Line 493:
END
END
</p>
</p>
<b>Procedure 3</b>
<b>Procedure 3</b>
<p class="code">BEGIN
<p class="code">BEGIN
Line 405: Line 502:
END
END
</p>
</p>
===Using global sorted sets===
<p>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. </p>
==Using global sorted sets==
====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>
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. </p>
<b>Procedure 1</b>
===Limiting subsequent references===
<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====
<p class="code">BEGIN
<p class="code">BEGIN
DECLARE LABEL S1 GLOBAL
DECLARE LABEL S1 GLOBAL
Line 420: Line 522:
END
END
</p>
</p>
<b>Procedure 2</b>
====Procedure 2====
<p class="code">BEGIN
<p class="code">BEGIN
DECLARE LABEL S1 GLOBAL
DECLARE LABEL S1 GLOBAL
Line 428: Line 531:
END
END
</p>
</p>
====Keeping all fields accessible for subsequent references====
<p>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.</p>
===Keeping all fields accessible for subsequent references===
<p>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.</p>
<p>
<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>
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.</p>
===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>
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.</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>
<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==
<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>
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===
<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====
{{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>
<li><var class="term">position_name</var> is a unique object name you assign to the <var>Remember</var> position. </li>
<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>
<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>


====REMEMBER statement====
<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>
<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>
</ul></li>
<b>Syntax</b>
<p class="code">REMEMBER <var>[</var>GLOBAL<var>]</var> position_name
 
  [IN foundsortset_name | ON list_name]
</p>
<b>Where</b>
<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>
<li>position_name is a unique object name you assign to the REMEMBER position.</li>
</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====
<b>Usage notes</b>
<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====
<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>
<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>
<b>Syntax</b>
<p class="code">POSITION {FOUNDSET foundsortset_name


  | LIST list_name} [AT] position_name
===Position statement===
<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>
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====
<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>
</p>
</p>
<b>Where</b>
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>
<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>
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>
 
<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>
</ul>
</ul>
<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>
<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>
====Usage notes====
<p>
The following rules apply:</p>
<ul>
<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>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 <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>The <var>Position</var> statement is incompatible with <var>For Each Record In Order By</var> clauses. </li>
</ul>
</ul>
<b>Usage notes</b>
<p>The following rules apply:</p>
==Global images and screens==
<ul>
<p>
<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>
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>
</li>
<p>
<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>
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>
</li>
<li>The POSITION statement is incompatible with FOR EACH RECORD IN ORDER BY clauses. </li>
===Declaring global images and screens===
</li>
<p>
</ul>
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>
===Global images and screens===
<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>
===How images and screens are processed===
<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>
<p>
====Declaring global images and screens====
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>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>
<p>
====How images and screens are processed====
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>
<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>
<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>
===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>


<b>Processing of nonglobal objects</b>
====Processing of nonglobal objects====
<p>The <b>Nonglobal object processing</b> figure illustrates the process in the following steps:</p>
<p class="figure">[[File:Nonglobal_object_processing.png|550px]] </p>
<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>
<b>GLOBAL object processing</b>
<p>&nbsp;</p>


[[File:Global_object_processing.gif]]
====Processing of global objects====
<p class="figure">[[File:Global_object_processing.png|550px]] </p>
<p>
The <b>Global object processing</b> figure illustrates the process in the following steps: </p>
<ol>
<li>The compiler loads a compiled version of the screen or image into FSCB in the user's server. </li>


<b>Processing of global objects</b>
<li>A copy of the compiled object is stored in the buffer pool. This copy is called 'VIRGIN', as it is never updated. </li>
<p>The <b>Global object processing</b> figure illustrates the process in the following steps:</p>
 
<ol>
<li>A <var>Prepare</var> statement acts on the compiled object in the buffer pool and copies it into GTBL. </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>Update statements act on the copy in GTBL. </li>
<li>A PREPARE 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>To help you decide how to use the PREPARE and IDENTIFY statements review the following:</p>
<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>Also when using the IDENTIFY statement, see [[#Consistency checks performed|Consistency checks performed]].</p>
<p>
</li>
Also when using the <var>Identify</var> statement, see [[#Consistency checks performed|Consistency checks performed]]. </p></li>
</ul>
</ul>
====Performance and efficiency benefits====
<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>
===Performance and efficiency benefits===
<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====
<p>You achieve the greatest benefit by declaring as GLOBAL the most frequently used images and screens in an application.</p>
===When to use global images and screens===
<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>
<p>
====Consistency checks performed====
You achieve the greatest benefit by declaring as <var>Global</var> the most frequently used images and screens in an application. </p>
<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>
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>
<p>If the object is present, two consistency checks are performed:</p>
===Consistency checks performed===
<p>
When a global image or screen is first referred to in a request, GTBL is searched for the object. </p>
<p>
If the object is<var> not</var> already present in GTBL, the object is written into GTBL. </p>
<p>
If the object is present, two consistency checks are performed:</p>
<ul>
<ul>
<li>Persistence--PERMANENT or TEMPORARY status--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--PERMANENT or TEMPORARY--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>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 following message is generated: </p>
<p>
<p class="code">M204.2158: GLOBAL object-type DEFINITION DOESN'T MATCH DEFINITION IN GTBL error-description, NAME HASH=hash-code
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">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===
 
<p>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:</p>
==Using global images and screens==
<p>
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:</p>
<ul>
<ul>
<li>SCREENDEF defines a global screen.</li>
<li>SCREENDEF defines a global screen.</li>
Line 588: Line 735:
   END SCREEN
   END SCREEN
END PROCEDURE
END PROCEDURE
 
PROCEDURE IMAGEDEF
PROCEDURE IMAGEDEF
   * KEEP GLOBAL SCREENS AND IMAGES IN SEPARATE PROCEDURES
   * KEEP GLOBAL SCREENS AND IMAGES IN SEPARATE PROCEDURES
Line 596: Line 743:
   END IMAGE
   END IMAGE
END PROCEDURE
END PROCEDURE
 
PROCEDURE PROCA
PROCEDURE PROCA
   BEGIN
   BEGIN
Line 609: Line 756:
   END
   END
END PROCEDURE
END PROCEDURE
 
PROCEDURE PROCB
PROCEDURE PROCB
   BEGIN
   BEGIN
Line 624: Line 771:
</p>
</p>
<p class="note"><b>Note:</b> 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.</p>
<p class="note"><b>Note:</b> 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.</p>
====System administration issues====
<p>To review the implications of the global images and screens feature for system administrators, see the Rocket <var class="product">Model&nbsp;204</var> System Manager's Guide on the following topics:</p>
===System administration issues===
<p>
To review the implications of the global images and screens feature for system administrators, see 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>
===Clearing the GTBL work area===
<p>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: </p>
==Clearing the GTBL work area==
<p>
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: </p>
<ul>
<ul>
<li>CLEAR statement </li>
<li>CLEAR statement </li>
Line 643: Line 793:
<li>UTABLE command that changes the size of FTBL, XTBL, or GTBL clears all global objects of any type</li>
<li>UTABLE command that changes the size of FTBL, XTBL, or GTBL clears all global objects of any type</li>
</ul>
</ul>
====Using the CLEARG and CLEARGO commands====
===Using the CLEARG and CLEARGO commands===
<table>
<table>
<tr class="head">
<tr class="head">
Line 649: Line 800:
<th>To Remove...</th>
<th>To Remove...</th>
</tr>
</tr>
<tr>
<tr>
<td>CLEARG </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>CLEARGO</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>The CLEARGO command takes no arguments. See the Rocket <var class="product">Model&nbsp;204</var> Parameter and Command Reference Manual for syntax and detailed information on the CLEARG and CLEARGO commands.</p>
<p>
====Using the $DELG function====
The <var>CLEARGO</var> command takes no arguments.
<p>You can use the $DELG function to delete global string variables created by either $SETG or $INCRG.</p>
</p>
<p>For syntax and usage of the $DELG function, see [[$DELG#$DELG|$DELG]] in the Rocket <var class="product">Model&nbsp;204</var> User Language Manual.</p>
<p>The $DELG function deletes a single or group of similar global string variables, releasing and compacting the GTBL space for reuse.</p>
===Using the $DELG function===
====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>[[$Delg]]</var> function to delete global string variables created by either <var>[[$Setg]]</var> or <var>[[$Incrg]]</var>. </p>
<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===
<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 670: 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>
<b>Syntax</b>
<p>The format for the CLEAR statement is:</p>
====Syntax====
<p class="code">CLEAR {[[ALL | TEMP | LISTFDST | POSITION] [GLOBAL]]
<p>
The format for the <var>Clear</var> statement is:</p>
{{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>
<li><var>ListFdst</var> clears all global found sets, lists, and sorted sets from GTBL. </li>
<li><var>Position</var> clears all permanent and temporary positions from GTBL. </li>
<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>
<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>
<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>


  OBJECTS
<li><var class="term">%variable</var> contains a value that specifies the global object to be cleared 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>
</ul>


  | GLOBAL {IMAGE | SCREEN | MENU | LIST | FOUNDSET
====Usage notes====
 
<p>
    | POSITION [PERM | TEMP]} {'objectname'
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
    | %variable}}
 
Clear All Objects
  | GLOBALS
Clear All Global Objects
Clear Global Objects
</p>
</p>
<b>Where</b>
===Clearing global found sets and lists===
<p>
You can clear global found sets and lists in GTBL without logging off using the following examples: </p>
<ul>
<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>Clear a specific global list or found set by issuing one of these statements:
</li>
<p class="code">Clear Global List '<i>objectname</i>'
<li>TEMP clears only global objects explicitly declared as TEMP in your request, including images, menus, and screens from GTBL.</li>
</li>
Clear Global List <i>%variable</i>
<li>LISTFDST clears all global found sets, lists, and sorted sets from GTBL.</li>
</li>
Clear Global Foundset '<i>objectname</i>'
<li>POSITION clears all permanent and temporary positions from GTBL.</li>
</li>
Clear Global Foundset <i>%variable</i>
<li>OBJECTS specifies CLEAR command is operating on the object type you specified or all types of objects.</li>
</p></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>
<b>Usage notes</b>
<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


CLEAR ALL OBJECTS
<li>Clear all global found sets and lists with the statement:
<p class="code">Clear ListFdst [Global] Objects </p>
<p>
(Global found sets and lists are among the global objects cleared by the <var>CLEARGO</var> command.) </p></li>


CLEAR ALL GLOBAL OBJECTS
<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>
 
CLEAR GLOBAL OBJECTS
<li>Issue a <var>UTABLE</var> command that changes the size of FTBL, XTBL, or GTBL. </li>
</ul>
<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>
<p class="code">M204.0301 Referenced statement label undefined
M204.0311 Unacceptable statement reference
</p>
</p>
====Clearing global found sets and lists====
<p>You can clear global found sets and lists in GTBL without logging off using the following examples:</p>
===RELEASE and COMMIT RELEASE statements with global foundsets and lists===
<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===
<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>
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>Clear a specific global list or found set 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 LIST 'objectname'
<p class="code">Clear Global Position Temp '<i>objectname</i>'
Clear Global Position Temp <i>%variable</i>
</p></li>


CLEAR GLOBAL LIST %variable
<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 <i>%variable</i>
</p></li>


CLEAR GLOBAL FOUNDSET 'objectname'
<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>


CLEAR GLOBAL FOUNDSET %variable
<li>You clear all remembered positions by issuing the statement:
<p class="code">Clear Position [Global] Objects
</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
</p>
<p>(Global found sets and lists are among the global objects cleared by the CLEARGO command.)</p>
</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>
</ul>
</ul>
<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>
<p class="code">M204.0301 REFERENCED STATEMENT LABEL UNDEFINED
====Usage notes====
 
M204.0311 UNACCEPTABLE STATEMENT REFERENCE
</p>
====RELEASE and COMMIT RELEASE statements with global foundsets and lists====
<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>
====Clearing remembered positions====
<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>
<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>When you are using the <var>Clear Global Position</var> statement, <var>Perm</var> is the default. </li>
<p class="code">CLEAR GLOBAL POSITION TEMP 'objectname'


CLEAR GLOBAL POSITION TEMP %variable
<li>The <var>CLEARGO</var> command has the effect of clearing all remembered positions.</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'


CLEAR GLOBAL POSITION PERM %variable
<li>Any <var>UTABLE</var> command that changes the size of FTBL, GTBL, or XTBL clears all remembered positions.</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
</p></li>
<li>You clear all remembered positions by issuing the statement:</li>
<p class="code">CLEAR POSITION <var>[</var>GLOBAL<var>]</var> OBJECTS
</p></li>
</ul>
</ul>
<b>Usage notes</b>
<p>When you are using the CLEAR GLOBAL POSITION statement, PERM is the default.</p>
===Timing and placement of a Clear statement===
<p>The CLEARGO command has the effect of clearing all remembered positions.</p>
<p>
<p>Any UTABLE command that changes the size of FTBL, GTBL, or XTBL clears all remembered positions.</p>
The <var>Clear Global</var> statement takes effect at evaluation time and its placement in a request can have significant consequences: </p>
====Timing and placement of a CLEAR statement====
<p>The CLEAR GLOBAL 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.