Global features

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 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=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=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=1. To maintain existing processing you can let FASTGLOB default to 0 or explicitly set FASTGLOB=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, either 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 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, null string, 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 either $SETG or $INCRG. The format of these functions is described in See User Language Functions.
• 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:

• Command line global variable
• Communication global variable
• Error global variable

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, labelname, or listname, 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 command 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 command 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 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. Non global 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 non global images and screens are processed.

Images and screen processing

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

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.

GLOBAL object processing

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:

• GTBL internal work area
• Timing and placement of a CLEAR statement
• For syntax and usage of the PREPARE statement, see PREPARE statement
• For syntax and usage of the IDENTIFY statement, see IDENTIFY statement

  Also when using the IDENTIFY statement, see Consistency checks performed.

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 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.

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 following message is generated:

M204.2158: GLOBAL object-type DEFINITION DOESN'T MATCH DEFINITION 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 Rocket Model 204 System Manager's Guide on the following topics:

• GTBL size
• VTBL usage with COMMON images and screens
• User since-last statistics

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 | GLOBAL {IMAGE | SCREEN | MENU | LIST | FOUNDSET | POSITION [PERM | TEMP]} {'objectname' | %variable}} | GLOBALS

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 CLEAR command is operating on the object type you specified or 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.