m204wiki - User contributions [en]

Global features

2026-04-23T17:47:34Z

JDamon: /* Syntax */

<div class="toclimit-3">
==Overview==

<var class="product">Model 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 204</var> internal work area or server table called the global table or GTBL. 

The global features are:
<ul>
<li>Global string variables</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>

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 [[Large request considerations#GTBL (global variable table)|GTBL (global variable table)]].

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.

Storage of global variables and global objects in GTBL 
[[File:Storage_of_global_vars_in_GTBL.png|450px]] 

==Global string variables==

You can use global string variables to: 
<ul>
<li>Pass information from one request to another request</li>

<li>Include procedures conditionally at the <var class="product">Model 204</var> command level</li>

<li>Tailor a request dynamically
</li>
</ul>

As of Version 5.1, you can increase the speed and reduce the CPU time to find and update a global string variable by setting the <var>[[GTBLHASH parameter|GTBLHASH]]</var> parameter to a nonzero value. The <var>GTBLHASH</var> parameter specifies the number of buckets allocated in the global string variable section of GTBL.
When <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. 

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 204</var>. 

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. 

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.


====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: 
<table>
<tr class="head">
<th>Statistic </th>
<th>Tracking</th>
</tr>

<tr>
<td>GTBLRU </td>
<td>Number of GTBL rearrangements required to add a string variable global.</td>
</tr>

<tr>
<td>GTBLRS </td>
<td>Number of GTBL rearrangements required to add a global object. </td>
</tr>
</table>

After reviewing the GTBLRU and GTBLRS statistics, you can consider taking the following actions: 
<ul>
<li>If both of these values are high, increase the size of GTBL by increasing <var>LGTBL</var>. </li>

<li>If GTBLRU is high but GTBLRS is not, increase <var>GTBLPCT</var> or decrease <var>GTBLHASH</var>. </li>

<li>If GTBLRS is high but GTBLRU is low, decrease <var>GTBLPCT</var>. </li>
</ul>

===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: 
<ul>
<li>Explicitly delete it</li>

<li>Issue a <var>Release</var> or <var>Commit Release</var> statement </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>Log out </li>
</ul>

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.

====Faster global variable processing option====

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. 

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


===Global positions===

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. 

===Global images and screens===

You can use global images and screens to:
<ul>
<li>Pass image and screen data from one request to another</li>

<li>Manage more than one image or screen in one request</li>

<li>Manage menus, which are a special type of screen</li>

<li>Reduce I/O by swapping modified global screens to CCASERVR instead of paging them between the buffer pool and CCATEMP </li>
</ul>

===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 <var>$Setg</var> function from within a request. 
<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 (<tt>.</tt>) cannot be used as <code>?&</code> dummy strings. </li>

<li>A value can be 0, the null string, or up to 255 characters. </li>
</ul>

===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 <var>CLEARG</var> command, execute a <var>Clear</var> statement, execute a <var>$Delg</var> function call, or you log out. 

If you define a large number of global string variables, <var class="product">Model 204</var> performance can be adversely affected. 

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

===Global variable functions and commands===

The following functions, statements, commands, and facilities manipulate entries in the global variable table: 
<ul>
<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>Use the <code>?&</code> dummy string within a request to read a variable in the GTBL. Refer to [[Procedures]] for more information about dummy strings. </li>

<li>Use the conditional <var>INCLUDE</var> command (<code>IF A=B,name</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>
</ul>

===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: 
<ul>
<li>[[Application Subsystem development#Command line global variable|Command line global variable]] </li>

<li>[[Application Subsystem development#Communication global variable|Communication global variable]] </li>

<li>[[Application Subsystem development#Error global variable|Error global variable]] </li>
</ul>

==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 <var>$Date</var> 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: 
<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 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 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>
<li>Conditional INCLUDE command</li>

<li>User Language statement </li>
</ul></li>
</ul>

===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. <var class="product">Model 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.

====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 [[Record retrievals#FILE$ condition|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===
<ul>
<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>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 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>
</ul>

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

====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 <var class="term">labelname</var> 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 <var>Global</var> implies <var>Common</var>. These two keywords are mutually exclusive in the declaration statement. 
<ul>
<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>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>
</ul>

====Usage rules====

The following rules apply to global found sets and lists: 
<ul>
<li>You must declare each global list or global found set as <code>labelname Global</code> in each procedure that uses it. </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.

The <var class="product">Model 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. 
</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>

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

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

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

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. 

===Remember statement===

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 204</var> clears non-global <var>Remember</var> positions at the end of each request.

====Syntax====
{{Template:Remember statement syntax}}
Where:
<ul>
<li>The <var>Global</var> option implies '''PERM''' and the position is retained in GTBL after the current request terminates. If <var>Global</var> is not specified, '''TEMP''' is implied and the position is cleared from GTBL after the current request terminates.</li>
NOTE: The use of GLOBAL here must be consistent with the CLEAR GLOBAL POSITION statement. If the latter is specified with PERM:
CLEAR GLOBAL POSITION PERM 'position_name',
then the REMEMBER statement must specify GLOBAL because it implies PERM.

<li><var class="term">position_name</var> is a unique object name you assign to the <var>Remember</var> position. </li>
NOTE:If the 'position_name' is mixed or lower case, be sure to enclose it here in single quotation marks. Do the same when referring to that name in other statements; e.g. CLEAR or POSITION.

<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 foundsortset_name</code> is the label of the <var>Find</var> statement that generated it. </li>

<li>If you are processing a list, <code>On list_name</code> is the name you gave to the list when you originally declared it. </li>
</ul></li>
</ul>

====Usage notes====

The following rules apply to the use of the <var>Remember</var> statement:
<ul>
<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>Is invalid in ad hoc group context, if used with the <var>Global</var> option. </li>

<li>The <var>Remember</var> statement is incompatible with <var>For Each Record In Order By</var> clauses. </li>
</ul>

===Position statement===

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.

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

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

Where:
<ul>
<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.

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. 

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.</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>
NOTE:If the 'position_name' is mixed or lower case, be sure to enclose it here in single quotation marks. Do the same when referring to that name in other statements; e.g. CLEAR or REMEMBER.
</ul>

====Usage notes====

The following rules apply:
<ul>
<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>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>

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

===How images and screens are processed===

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. 

This section provides some background information about how <var class="product">Model 204</var> 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====
[[File:Nonglobal_object_processing.png|550px]] 

The Nonglobal object processing figure illustrates the process in the following steps:
<ol>
<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 <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>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 Enter for that object, the object is loaded back from CCATEMP to the buffer pool. </li>
</ol>
 

====Processing of global objects====
[[File:Global_object_processing.png|550px]] 

The Global object processing figure illustrates the process in the following steps: 
<ol>
<li>The compiler loads a compiled version of the screen or image into FSCB in the user's server. </li>

<li>A copy of the compiled object is stored in the buffer pool. This copy is called 'VIRGIN', as it is never updated. </li>

<li>A <var>Prepare</var> statement acts on the compiled object in the buffer pool and copies it into GTBL. </li>

<li>Update statements act on the copy in GTBL. </li>
</ol>

===Using Prepare and Identify statements===

To help you decide how to use the <var>Prepare</var> and <var>Identify</var> statements, review the following:
<ul>
<li>[[#GTBL internal work area|GTBL internal work area]] </li>

<li>[[#Timing and placement of a CLEAR statement|Timing and placement of a CLEAR statement]] </li>

<li>For syntax and usage of the <var>Prepare</var> statement, see [[Full-screen feature#PREPARE statement|Prepare statement]]</li>

<li>For syntax and usage of the <var>Identify</var> statement, see [[Images#Identify statement|Identify statement]]

Also when using the <var>Identify</var> statement, see [[#Consistency checks performed|Consistency checks performed]]. </li>
</ul>

===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: 
<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 the FSCB I/O between multiple images and between images and screens. </li>

<li>Makes the declaration of global data explicit, thus traceable by using naming conventions and cross-reference tools. </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>Reduces I/O by swapping modified global screens to CCASERVR instead of paging them between the buffer pool and CCATEMP. </li>
</ul>

===When to use global images and screens===

You achieve the greatest benefit by declaring as <var>Global</var> 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<var> not</var> already present in GTBL, the object is written into GTBL. 

If the object is present, two consistency checks are performed:
<ul>
<li>Persistence — <var>Permanent</var> or <var>Temporary</var> status — of the new object must match the persistence of the object already in GTBL. </li>

<li>Definition — <var>Permanent</var> or <var>Temporary</var> — of the new object must match the definition of the object already in GTBL.
</li>
</ul>
Note: If a global image has an array that uses the <var>Depending On %variable</var> 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 <var>Temporary</var>, but the same image already exists in GTBL, declared as <var>Permanent</var> — 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:
<ul>
<li>SCREENDEF defines a global screen.</li>
<li>IMAGEDEF defines a global image.</li>
<li>PROCA sets the screen item value and an image item value.</li>
<li>PROCB displays the updated image item and the original screen item. </li>
</ul>
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:
<ul>
<li>GTBL size — [[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>VTBL usage with COMMON images and screens — [[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>User since-last statistics — [[Using system statistics#User since-last statistics|User since-last statistics]] </li>
</ul>

==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: 
<ul>
<li>CLEAR statement </li>
<li>CLEARG and/or CLEARGO commands</li>
<li>$DELG function to selectively delete global string variables</li>
<li>RESET command for the GTBLEHASH and GTBLPCT parameters</li>
<li>UTABLE command that changes the size of FTBL, XTBL, or GTBL clears all global objects of any type</li>
</ul>

===Using the CLEARG and CLEARGO commands===
<table>
<tr class="head">
<th>Use this command </th>
<th>To Remove...</th>
</tr>

<tr>
<td><var>[[CLEARG command|CLEARG]]</var> </td>
<td>Only global string variables. </td>
</tr>

<tr>
<td><var>[[CLEARGO command|CLEARGO]]</var></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>
</table>

The <var>CLEARGO</var> command takes no arguments.


===Using the $DELG function===

You can use the <var>[[$Delg]]</var> function to delete global string variables created by either <var>[[$Setg]]</var> or <var>[[$Incrg]]</var>. 

The <var>[[$Delg]]</var> 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 <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: 
<table>
<tr class="head">
<th>The statement </th>
<th>Clears...</th>
</tr>

<tr>
<td nowrap><var>Clear type-of-object 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>
</tr>

<tr>
<td><var>Clear Global</var> </td>
<td>Individual global objects from GTBL. </td>
</tr>

<tr>
<td><var>Clear Globals</var> </td>
<td>All global string variables. You cannot selectively clear individual global string variables with the <var>Clear</var> statement. </td>
</tr>
</table>

====Syntax====

The format for the <var>Clear</var> statement is:
{{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>Position [Perm | Temp]</var> The use of PERM or TEMP must be consistent with GLOBAL in the REMEMBER statement. If GLOBAL is specified in the REMEMBER statement, then PERM is implied. If GLOBAL is omitted from the REMEMBER statement, TEMP is implied.
</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>
NOTE: If the 'objectname' is mixed or lower case, be sure to enclose it here in single quotation marks. Do the same when referring to that name in other statements; e.g. REMEMBER or POSITION.

<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 not clear any global objects. </li>
</ul>

====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: 
<ul>
<li>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
</li>

<li>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 <var>CLEARGO</var> command.) </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>Issue a <var>UTABLE</var> command that changes the size of FTBL, XTBL, or GTBL. </li>
</ul>

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:

M204.0301 Referenced statement label undefined

M204.0311 Unacceptable statement reference


===RELEASE and COMMIT RELEASE statements with global foundsets and lists===

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.

===Clearing remembered positions===

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.

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:
<ul>
<li>You can clear a specific temporary position by issuing one of these statements:
Clear Global Position Temp 'objectname'

Clear Global Position Temp %variable
</li>

<li>You can clear a specific permanent position by issuing one of these statements:
Clear Global Position Perm 'objectname'

Clear Global Position Perm %variable
</li>

<li>You clear all global found sets, lists, or sorted sets with which a remembered position is associated:
Clear ListFdst [Global] Objects
</li>

<li>You clear all remembered positions by issuing the statement:
Clear Position [Global] Objects
</li>
</ul>

====Usage notes====
<ul>
<li>When you are using the <var>Clear Global Position</var> statement, <var>Perm</var> is the default. </li>

<li>The <var>CLEARGO</var> command has the effect of clearing all remembered positions.</li>

<li>Any <var>UTABLE</var> command that changes the size of FTBL, GTBL, or XTBL clears all remembered positions.</li>
</ul>

===Timing and placement of a Clear statement===

The <var>Clear Global</var> statement takes effect at evaluation time and its placement in a request can have significant consequences: 
<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>
</ul>

</div> 

[[Category:SOUL]]

Global features

2026-04-23T17:44:11Z

JDamon: /* Syntax */

<div class="toclimit-3">
==Overview==

<var class="product">Model 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 204</var> internal work area or server table called the global table or GTBL. 

The global features are:
<ul>
<li>Global string variables</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>

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 [[Large request considerations#GTBL (global variable table)|GTBL (global variable table)]].

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.

Storage of global variables and global objects in GTBL 
[[File:Storage_of_global_vars_in_GTBL.png|450px]] 

==Global string variables==

You can use global string variables to: 
<ul>
<li>Pass information from one request to another request</li>

<li>Include procedures conditionally at the <var class="product">Model 204</var> command level</li>

<li>Tailor a request dynamically
</li>
</ul>

As of Version 5.1, you can increase the speed and reduce the CPU time to find and update a global string variable by setting the <var>[[GTBLHASH parameter|GTBLHASH]]</var> parameter to a nonzero value. The <var>GTBLHASH</var> parameter specifies the number of buckets allocated in the global string variable section of GTBL.
When <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. 

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 204</var>. 

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. 

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.


====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: 
<table>
<tr class="head">
<th>Statistic </th>
<th>Tracking</th>
</tr>

<tr>
<td>GTBLRU </td>
<td>Number of GTBL rearrangements required to add a string variable global.</td>
</tr>

<tr>
<td>GTBLRS </td>
<td>Number of GTBL rearrangements required to add a global object. </td>
</tr>
</table>

After reviewing the GTBLRU and GTBLRS statistics, you can consider taking the following actions: 
<ul>
<li>If both of these values are high, increase the size of GTBL by increasing <var>LGTBL</var>. </li>

<li>If GTBLRU is high but GTBLRS is not, increase <var>GTBLPCT</var> or decrease <var>GTBLHASH</var>. </li>

<li>If GTBLRS is high but GTBLRU is low, decrease <var>GTBLPCT</var>. </li>
</ul>

===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: 
<ul>
<li>Explicitly delete it</li>

<li>Issue a <var>Release</var> or <var>Commit Release</var> statement </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>Log out </li>
</ul>

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.

====Faster global variable processing option====

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. 

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


===Global positions===

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. 

===Global images and screens===

You can use global images and screens to:
<ul>
<li>Pass image and screen data from one request to another</li>

<li>Manage more than one image or screen in one request</li>

<li>Manage menus, which are a special type of screen</li>

<li>Reduce I/O by swapping modified global screens to CCASERVR instead of paging them between the buffer pool and CCATEMP </li>
</ul>

===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 <var>$Setg</var> function from within a request. 
<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 (<tt>.</tt>) cannot be used as <code>?&</code> dummy strings. </li>

<li>A value can be 0, the null string, or up to 255 characters. </li>
</ul>

===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 <var>CLEARG</var> command, execute a <var>Clear</var> statement, execute a <var>$Delg</var> function call, or you log out. 

If you define a large number of global string variables, <var class="product">Model 204</var> performance can be adversely affected. 

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

===Global variable functions and commands===

The following functions, statements, commands, and facilities manipulate entries in the global variable table: 
<ul>
<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>Use the <code>?&</code> dummy string within a request to read a variable in the GTBL. Refer to [[Procedures]] for more information about dummy strings. </li>

<li>Use the conditional <var>INCLUDE</var> command (<code>IF A=B,name</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>
</ul>

===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: 
<ul>
<li>[[Application Subsystem development#Command line global variable|Command line global variable]] </li>

<li>[[Application Subsystem development#Communication global variable|Communication global variable]] </li>

<li>[[Application Subsystem development#Error global variable|Error global variable]] </li>
</ul>

==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 <var>$Date</var> 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: 
<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 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 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>
<li>Conditional INCLUDE command</li>

<li>User Language statement </li>
</ul></li>
</ul>

===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. <var class="product">Model 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.

====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 [[Record retrievals#FILE$ condition|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===
<ul>
<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>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 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>
</ul>

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

====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 <var class="term">labelname</var> 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 <var>Global</var> implies <var>Common</var>. These two keywords are mutually exclusive in the declaration statement. 
<ul>
<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>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>
</ul>

====Usage rules====

The following rules apply to global found sets and lists: 
<ul>
<li>You must declare each global list or global found set as <code>labelname Global</code> in each procedure that uses it. </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.

The <var class="product">Model 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. 
</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>

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

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

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

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. 

===Remember statement===

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 204</var> clears non-global <var>Remember</var> positions at the end of each request.

====Syntax====
{{Template:Remember statement syntax}}
Where:
<ul>
<li>The <var>Global</var> option implies '''PERM''' and the position is retained in GTBL after the current request terminates. If <var>Global</var> is not specified, '''TEMP''' is implied and the position is cleared from GTBL after the current request terminates.</li>
NOTE: The use of GLOBAL here must be consistent with the CLEAR GLOBAL POSITION statement. If the latter is specified with PERM:
CLEAR GLOBAL POSITION PERM 'position_name',
then the REMEMBER statement must specify GLOBAL because it implies PERM.

<li><var class="term">position_name</var> is a unique object name you assign to the <var>Remember</var> position. </li>
NOTE:If the 'position_name' is mixed or lower case, be sure to enclose it here in single quotation marks. Do the same when referring to that name in other statements; e.g. CLEAR or POSITION.

<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 foundsortset_name</code> is the label of the <var>Find</var> statement that generated it. </li>

<li>If you are processing a list, <code>On list_name</code> is the name you gave to the list when you originally declared it. </li>
</ul></li>
</ul>

====Usage notes====

The following rules apply to the use of the <var>Remember</var> statement:
<ul>
<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>Is invalid in ad hoc group context, if used with the <var>Global</var> option. </li>

<li>The <var>Remember</var> statement is incompatible with <var>For Each Record In Order By</var> clauses. </li>
</ul>

===Position statement===

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.

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

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

Where:
<ul>
<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.

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. 

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.</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>
NOTE:If the 'position_name' is mixed or lower case, be sure to enclose it here in single quotes. Do the same when referring to that name in other statements; e.g. CLEAR or REMEMBER.
</ul>

====Usage notes====

The following rules apply:
<ul>
<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>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>

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

===How images and screens are processed===

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. 

This section provides some background information about how <var class="product">Model 204</var> 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====
[[File:Nonglobal_object_processing.png|550px]] 

The Nonglobal object processing figure illustrates the process in the following steps:
<ol>
<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 <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>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 Enter for that object, the object is loaded back from CCATEMP to the buffer pool. </li>
</ol>
 

====Processing of global objects====
[[File:Global_object_processing.png|550px]] 

The Global object processing figure illustrates the process in the following steps: 
<ol>
<li>The compiler loads a compiled version of the screen or image into FSCB in the user's server. </li>

<li>A copy of the compiled object is stored in the buffer pool. This copy is called 'VIRGIN', as it is never updated. </li>

<li>A <var>Prepare</var> statement acts on the compiled object in the buffer pool and copies it into GTBL. </li>

<li>Update statements act on the copy in GTBL. </li>
</ol>

===Using Prepare and Identify statements===

To help you decide how to use the <var>Prepare</var> and <var>Identify</var> statements, review the following:
<ul>
<li>[[#GTBL internal work area|GTBL internal work area]] </li>

<li>[[#Timing and placement of a CLEAR statement|Timing and placement of a CLEAR statement]] </li>

<li>For syntax and usage of the <var>Prepare</var> statement, see [[Full-screen feature#PREPARE statement|Prepare statement]]</li>

<li>For syntax and usage of the <var>Identify</var> statement, see [[Images#Identify statement|Identify statement]]

Also when using the <var>Identify</var> statement, see [[#Consistency checks performed|Consistency checks performed]]. </li>
</ul>

===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: 
<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 the FSCB I/O between multiple images and between images and screens. </li>

<li>Makes the declaration of global data explicit, thus traceable by using naming conventions and cross-reference tools. </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>Reduces I/O by swapping modified global screens to CCASERVR instead of paging them between the buffer pool and CCATEMP. </li>
</ul>

===When to use global images and screens===

You achieve the greatest benefit by declaring as <var>Global</var> 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<var> not</var> already present in GTBL, the object is written into GTBL. 

If the object is present, two consistency checks are performed:
<ul>
<li>Persistence — <var>Permanent</var> or <var>Temporary</var> status — of the new object must match the persistence of the object already in GTBL. </li>

<li>Definition — <var>Permanent</var> or <var>Temporary</var> — of the new object must match the definition of the object already in GTBL.
</li>
</ul>
Note: If a global image has an array that uses the <var>Depending On %variable</var> 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 <var>Temporary</var>, but the same image already exists in GTBL, declared as <var>Permanent</var> — 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:
<ul>
<li>SCREENDEF defines a global screen.</li>
<li>IMAGEDEF defines a global image.</li>
<li>PROCA sets the screen item value and an image item value.</li>
<li>PROCB displays the updated image item and the original screen item. </li>
</ul>
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:
<ul>
<li>GTBL size — [[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>VTBL usage with COMMON images and screens — [[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>User since-last statistics — [[Using system statistics#User since-last statistics|User since-last statistics]] </li>
</ul>

==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: 
<ul>
<li>CLEAR statement </li>
<li>CLEARG and/or CLEARGO commands</li>
<li>$DELG function to selectively delete global string variables</li>
<li>RESET command for the GTBLEHASH and GTBLPCT parameters</li>
<li>UTABLE command that changes the size of FTBL, XTBL, or GTBL clears all global objects of any type</li>
</ul>

===Using the CLEARG and CLEARGO commands===
<table>
<tr class="head">
<th>Use this command </th>
<th>To Remove...</th>
</tr>

<tr>
<td><var>[[CLEARG command|CLEARG]]</var> </td>
<td>Only global string variables. </td>
</tr>

<tr>
<td><var>[[CLEARGO command|CLEARGO]]</var></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>
</table>

The <var>CLEARGO</var> command takes no arguments.


===Using the $DELG function===

You can use the <var>[[$Delg]]</var> function to delete global string variables created by either <var>[[$Setg]]</var> or <var>[[$Incrg]]</var>. 

The <var>[[$Delg]]</var> 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 <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: 
<table>
<tr class="head">
<th>The statement </th>
<th>Clears...</th>
</tr>

<tr>
<td nowrap><var>Clear type-of-object 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>
</tr>

<tr>
<td><var>Clear Global</var> </td>
<td>Individual global objects from GTBL. </td>
</tr>

<tr>
<td><var>Clear Globals</var> </td>
<td>All global string variables. You cannot selectively clear individual global string variables with the <var>Clear</var> statement. </td>
</tr>
</table>

====Syntax====

The format for the <var>Clear</var> statement is:
{{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>Position [Perm | Temp]</var> The use of PERM or TEMP must be consistent with GLOBAL in the REMEMBER statement. If GLOBAL is specified in the REMEMBER statement, then PERM is implied. If GLOBAL is omitted from the REMEMBER statement, TEMP is implied.
</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>
NOTE: If the 'objectname' is mixed or lower case, be sure to enclose it here in single quotation marks. Do the same when referring to that name in other statements; e.g. REMEMBER or POSITION.

<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 not clear any global objects. </li>
</ul>

====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: 
<ul>
<li>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
</li>

<li>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 <var>CLEARGO</var> command.) </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>Issue a <var>UTABLE</var> command that changes the size of FTBL, XTBL, or GTBL. </li>
</ul>

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:

M204.0301 Referenced statement label undefined

M204.0311 Unacceptable statement reference


===RELEASE and COMMIT RELEASE statements with global foundsets and lists===

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.

===Clearing remembered positions===

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.

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:
<ul>
<li>You can clear a specific temporary position by issuing one of these statements:
Clear Global Position Temp 'objectname'

Clear Global Position Temp %variable
</li>

<li>You can clear a specific permanent position by issuing one of these statements:
Clear Global Position Perm 'objectname'

Clear Global Position Perm %variable
</li>

<li>You clear all global found sets, lists, or sorted sets with which a remembered position is associated:
Clear ListFdst [Global] Objects
</li>

<li>You clear all remembered positions by issuing the statement:
Clear Position [Global] Objects
</li>
</ul>

====Usage notes====
<ul>
<li>When you are using the <var>Clear Global Position</var> statement, <var>Perm</var> is the default. </li>

<li>The <var>CLEARGO</var> command has the effect of clearing all remembered positions.</li>

<li>Any <var>UTABLE</var> command that changes the size of FTBL, GTBL, or XTBL clears all remembered positions.</li>
</ul>

===Timing and placement of a Clear statement===

The <var>Clear Global</var> statement takes effect at evaluation time and its placement in a request can have significant consequences: 
<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>
</ul>

</div> 

[[Category:SOUL]]

Global features

2026-04-23T17:41:12Z

JDamon: /* Remember statement */

<div class="toclimit-3">
==Overview==

<var class="product">Model 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 204</var> internal work area or server table called the global table or GTBL. 

The global features are:
<ul>
<li>Global string variables</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>

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 [[Large request considerations#GTBL (global variable table)|GTBL (global variable table)]].

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.

Storage of global variables and global objects in GTBL 
[[File:Storage_of_global_vars_in_GTBL.png|450px]] 

==Global string variables==

You can use global string variables to: 
<ul>
<li>Pass information from one request to another request</li>

<li>Include procedures conditionally at the <var class="product">Model 204</var> command level</li>

<li>Tailor a request dynamically
</li>
</ul>

As of Version 5.1, you can increase the speed and reduce the CPU time to find and update a global string variable by setting the <var>[[GTBLHASH parameter|GTBLHASH]]</var> parameter to a nonzero value. The <var>GTBLHASH</var> parameter specifies the number of buckets allocated in the global string variable section of GTBL.
When <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. 

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 204</var>. 

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. 

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.


====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: 
<table>
<tr class="head">
<th>Statistic </th>
<th>Tracking</th>
</tr>

<tr>
<td>GTBLRU </td>
<td>Number of GTBL rearrangements required to add a string variable global.</td>
</tr>

<tr>
<td>GTBLRS </td>
<td>Number of GTBL rearrangements required to add a global object. </td>
</tr>
</table>

After reviewing the GTBLRU and GTBLRS statistics, you can consider taking the following actions: 
<ul>
<li>If both of these values are high, increase the size of GTBL by increasing <var>LGTBL</var>. </li>

<li>If GTBLRU is high but GTBLRS is not, increase <var>GTBLPCT</var> or decrease <var>GTBLHASH</var>. </li>

<li>If GTBLRS is high but GTBLRU is low, decrease <var>GTBLPCT</var>. </li>
</ul>

===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: 
<ul>
<li>Explicitly delete it</li>

<li>Issue a <var>Release</var> or <var>Commit Release</var> statement </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>Log out </li>
</ul>

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.

====Faster global variable processing option====

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. 

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


===Global positions===

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. 

===Global images and screens===

You can use global images and screens to:
<ul>
<li>Pass image and screen data from one request to another</li>

<li>Manage more than one image or screen in one request</li>

<li>Manage menus, which are a special type of screen</li>

<li>Reduce I/O by swapping modified global screens to CCASERVR instead of paging them between the buffer pool and CCATEMP </li>
</ul>

===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 <var>$Setg</var> function from within a request. 
<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 (<tt>.</tt>) cannot be used as <code>?&</code> dummy strings. </li>

<li>A value can be 0, the null string, or up to 255 characters. </li>
</ul>

===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 <var>CLEARG</var> command, execute a <var>Clear</var> statement, execute a <var>$Delg</var> function call, or you log out. 

If you define a large number of global string variables, <var class="product">Model 204</var> performance can be adversely affected. 

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

===Global variable functions and commands===

The following functions, statements, commands, and facilities manipulate entries in the global variable table: 
<ul>
<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>Use the <code>?&</code> dummy string within a request to read a variable in the GTBL. Refer to [[Procedures]] for more information about dummy strings. </li>

<li>Use the conditional <var>INCLUDE</var> command (<code>IF A=B,name</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>
</ul>

===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: 
<ul>
<li>[[Application Subsystem development#Command line global variable|Command line global variable]] </li>

<li>[[Application Subsystem development#Communication global variable|Communication global variable]] </li>

<li>[[Application Subsystem development#Error global variable|Error global variable]] </li>
</ul>

==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 <var>$Date</var> 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: 
<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 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 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>
<li>Conditional INCLUDE command</li>

<li>User Language statement </li>
</ul></li>
</ul>

===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. <var class="product">Model 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.

====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 [[Record retrievals#FILE$ condition|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===
<ul>
<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>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 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>
</ul>

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

====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 <var class="term">labelname</var> 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 <var>Global</var> implies <var>Common</var>. These two keywords are mutually exclusive in the declaration statement. 
<ul>
<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>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>
</ul>

====Usage rules====

The following rules apply to global found sets and lists: 
<ul>
<li>You must declare each global list or global found set as <code>labelname Global</code> in each procedure that uses it. </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.

The <var class="product">Model 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. 
</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>

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

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

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

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. 

===Remember statement===

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 204</var> clears non-global <var>Remember</var> positions at the end of each request.

====Syntax====
{{Template:Remember statement syntax}}
Where:
<ul>
<li>The <var>Global</var> option implies '''PERM''' and the position is retained in GTBL after the current request terminates. If <var>Global</var> is not specified, '''TEMP''' is implied and the position is cleared from GTBL after the current request terminates.</li>
NOTE: The use of GLOBAL here must be consistent with the CLEAR GLOBAL POSITION statement. If the latter is specified with PERM:
CLEAR GLOBAL POSITION PERM 'position_name',
then the REMEMBER statement must specify GLOBAL because it implies PERM.

<li><var class="term">position_name</var> is a unique object name you assign to the <var>Remember</var> position. </li>
NOTE:If the 'position_name' is mixed or lower case, be sure to enclose it here in single quotation marks. Do the same when referring to that name in other statements; e.g. CLEAR or POSITION.

<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 foundsortset_name</code> is the label of the <var>Find</var> statement that generated it. </li>

<li>If you are processing a list, <code>On list_name</code> is the name you gave to the list when you originally declared it. </li>
</ul></li>
</ul>

====Usage notes====

The following rules apply to the use of the <var>Remember</var> statement:
<ul>
<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>Is invalid in ad hoc group context, if used with the <var>Global</var> option. </li>

<li>The <var>Remember</var> statement is incompatible with <var>For Each Record In Order By</var> clauses. </li>
</ul>

===Position statement===

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.

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

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

Where:
<ul>
<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.

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. 

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.</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>
NOTE:If the 'position_name' is mixed or lower case, be sure to enclose it here in single quotes. Do the same when referring to that name in other statements; e.g. CLEAR or REMEMBER.
</ul>

====Usage notes====

The following rules apply:
<ul>
<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>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>

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

===How images and screens are processed===

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. 

This section provides some background information about how <var class="product">Model 204</var> 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====
[[File:Nonglobal_object_processing.png|550px]] 

The Nonglobal object processing figure illustrates the process in the following steps:
<ol>
<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 <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>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 Enter for that object, the object is loaded back from CCATEMP to the buffer pool. </li>
</ol>
 

====Processing of global objects====
[[File:Global_object_processing.png|550px]] 

The Global object processing figure illustrates the process in the following steps: 
<ol>
<li>The compiler loads a compiled version of the screen or image into FSCB in the user's server. </li>

<li>A copy of the compiled object is stored in the buffer pool. This copy is called 'VIRGIN', as it is never updated. </li>

<li>A <var>Prepare</var> statement acts on the compiled object in the buffer pool and copies it into GTBL. </li>

<li>Update statements act on the copy in GTBL. </li>
</ol>

===Using Prepare and Identify statements===

To help you decide how to use the <var>Prepare</var> and <var>Identify</var> statements, review the following:
<ul>
<li>[[#GTBL internal work area|GTBL internal work area]] </li>

<li>[[#Timing and placement of a CLEAR statement|Timing and placement of a CLEAR statement]] </li>

<li>For syntax and usage of the <var>Prepare</var> statement, see [[Full-screen feature#PREPARE statement|Prepare statement]]</li>

<li>For syntax and usage of the <var>Identify</var> statement, see [[Images#Identify statement|Identify statement]]

Also when using the <var>Identify</var> statement, see [[#Consistency checks performed|Consistency checks performed]]. </li>
</ul>

===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: 
<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 the FSCB I/O between multiple images and between images and screens. </li>

<li>Makes the declaration of global data explicit, thus traceable by using naming conventions and cross-reference tools. </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>Reduces I/O by swapping modified global screens to CCASERVR instead of paging them between the buffer pool and CCATEMP. </li>
</ul>

===When to use global images and screens===

You achieve the greatest benefit by declaring as <var>Global</var> 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<var> not</var> already present in GTBL, the object is written into GTBL. 

If the object is present, two consistency checks are performed:
<ul>
<li>Persistence — <var>Permanent</var> or <var>Temporary</var> status — of the new object must match the persistence of the object already in GTBL. </li>

<li>Definition — <var>Permanent</var> or <var>Temporary</var> — of the new object must match the definition of the object already in GTBL.
</li>
</ul>
Note: If a global image has an array that uses the <var>Depending On %variable</var> 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 <var>Temporary</var>, but the same image already exists in GTBL, declared as <var>Permanent</var> — 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:
<ul>
<li>SCREENDEF defines a global screen.</li>
<li>IMAGEDEF defines a global image.</li>
<li>PROCA sets the screen item value and an image item value.</li>
<li>PROCB displays the updated image item and the original screen item. </li>
</ul>
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:
<ul>
<li>GTBL size — [[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>VTBL usage with COMMON images and screens — [[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>User since-last statistics — [[Using system statistics#User since-last statistics|User since-last statistics]] </li>
</ul>

==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: 
<ul>
<li>CLEAR statement </li>
<li>CLEARG and/or CLEARGO commands</li>
<li>$DELG function to selectively delete global string variables</li>
<li>RESET command for the GTBLEHASH and GTBLPCT parameters</li>
<li>UTABLE command that changes the size of FTBL, XTBL, or GTBL clears all global objects of any type</li>
</ul>

===Using the CLEARG and CLEARGO commands===
<table>
<tr class="head">
<th>Use this command </th>
<th>To Remove...</th>
</tr>

<tr>
<td><var>[[CLEARG command|CLEARG]]</var> </td>
<td>Only global string variables. </td>
</tr>

<tr>
<td><var>[[CLEARGO command|CLEARGO]]</var></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>
</table>

The <var>CLEARGO</var> command takes no arguments.


===Using the $DELG function===

You can use the <var>[[$Delg]]</var> function to delete global string variables created by either <var>[[$Setg]]</var> or <var>[[$Incrg]]</var>. 

The <var>[[$Delg]]</var> 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 <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: 
<table>
<tr class="head">
<th>The statement </th>
<th>Clears...</th>
</tr>

<tr>
<td nowrap><var>Clear type-of-object 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>
</tr>

<tr>
<td><var>Clear Global</var> </td>
<td>Individual global objects from GTBL. </td>
</tr>

<tr>
<td><var>Clear Globals</var> </td>
<td>All global string variables. You cannot selectively clear individual global string variables with the <var>Clear</var> statement. </td>
</tr>
</table>

====Syntax====

The format for the <var>Clear</var> statement is:
{{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>Position [Perm | Temp]</var> The use of PERM or TEMP must be consistent with GLOBAL in the REMEMBER statement. If GLOBAL is specified in the REMEMBER statement, then PERM is implied. If GLOBAL is omitted from the REMEMBER statement, TEMP is implied.
</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>
NOTE: If the objectname is mixed case, be sure to use the same name, in single quotation marks, when referring to that name in other statements; e.g. REMEMBER or POSITION.

<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 not clear any global objects. </li>
</ul>

====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: 
<ul>
<li>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
</li>

<li>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 <var>CLEARGO</var> command.) </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>Issue a <var>UTABLE</var> command that changes the size of FTBL, XTBL, or GTBL. </li>
</ul>

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:

M204.0301 Referenced statement label undefined

M204.0311 Unacceptable statement reference


===RELEASE and COMMIT RELEASE statements with global foundsets and lists===

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.

===Clearing remembered positions===

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.

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:
<ul>
<li>You can clear a specific temporary position by issuing one of these statements:
Clear Global Position Temp 'objectname'

Clear Global Position Temp %variable
</li>

<li>You can clear a specific permanent position by issuing one of these statements:
Clear Global Position Perm 'objectname'

Clear Global Position Perm %variable
</li>

<li>You clear all global found sets, lists, or sorted sets with which a remembered position is associated:
Clear ListFdst [Global] Objects
</li>

<li>You clear all remembered positions by issuing the statement:
Clear Position [Global] Objects
</li>
</ul>

====Usage notes====
<ul>
<li>When you are using the <var>Clear Global Position</var> statement, <var>Perm</var> is the default. </li>

<li>The <var>CLEARGO</var> command has the effect of clearing all remembered positions.</li>

<li>Any <var>UTABLE</var> command that changes the size of FTBL, GTBL, or XTBL clears all remembered positions.</li>
</ul>

===Timing and placement of a Clear statement===

The <var>Clear Global</var> statement takes effect at evaluation time and its placement in a request can have significant consequences: 
<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>
</ul>

</div> 

[[Category:SOUL]]

Global features

2026-04-23T17:38:03Z

JDamon: /* Syntax */

<div class="toclimit-3">
==Overview==

<var class="product">Model 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 204</var> internal work area or server table called the global table or GTBL. 

The global features are:
<ul>
<li>Global string variables</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>

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 [[Large request considerations#GTBL (global variable table)|GTBL (global variable table)]].

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.

Storage of global variables and global objects in GTBL 
[[File:Storage_of_global_vars_in_GTBL.png|450px]] 

==Global string variables==

You can use global string variables to: 
<ul>
<li>Pass information from one request to another request</li>

<li>Include procedures conditionally at the <var class="product">Model 204</var> command level</li>

<li>Tailor a request dynamically
</li>
</ul>

As of Version 5.1, you can increase the speed and reduce the CPU time to find and update a global string variable by setting the <var>[[GTBLHASH parameter|GTBLHASH]]</var> parameter to a nonzero value. The <var>GTBLHASH</var> parameter specifies the number of buckets allocated in the global string variable section of GTBL.
When <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. 

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 204</var>. 

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. 

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.


====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: 
<table>
<tr class="head">
<th>Statistic </th>
<th>Tracking</th>
</tr>

<tr>
<td>GTBLRU </td>
<td>Number of GTBL rearrangements required to add a string variable global.</td>
</tr>

<tr>
<td>GTBLRS </td>
<td>Number of GTBL rearrangements required to add a global object. </td>
</tr>
</table>

After reviewing the GTBLRU and GTBLRS statistics, you can consider taking the following actions: 
<ul>
<li>If both of these values are high, increase the size of GTBL by increasing <var>LGTBL</var>. </li>

<li>If GTBLRU is high but GTBLRS is not, increase <var>GTBLPCT</var> or decrease <var>GTBLHASH</var>. </li>

<li>If GTBLRS is high but GTBLRU is low, decrease <var>GTBLPCT</var>. </li>
</ul>

===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: 
<ul>
<li>Explicitly delete it</li>

<li>Issue a <var>Release</var> or <var>Commit Release</var> statement </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>Log out </li>
</ul>

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.

====Faster global variable processing option====

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. 

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


===Global positions===

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. 

===Global images and screens===

You can use global images and screens to:
<ul>
<li>Pass image and screen data from one request to another</li>

<li>Manage more than one image or screen in one request</li>

<li>Manage menus, which are a special type of screen</li>

<li>Reduce I/O by swapping modified global screens to CCASERVR instead of paging them between the buffer pool and CCATEMP </li>
</ul>

===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 <var>$Setg</var> function from within a request. 
<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 (<tt>.</tt>) cannot be used as <code>?&</code> dummy strings. </li>

<li>A value can be 0, the null string, or up to 255 characters. </li>
</ul>

===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 <var>CLEARG</var> command, execute a <var>Clear</var> statement, execute a <var>$Delg</var> function call, or you log out. 

If you define a large number of global string variables, <var class="product">Model 204</var> performance can be adversely affected. 

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

===Global variable functions and commands===

The following functions, statements, commands, and facilities manipulate entries in the global variable table: 
<ul>
<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>Use the <code>?&</code> dummy string within a request to read a variable in the GTBL. Refer to [[Procedures]] for more information about dummy strings. </li>

<li>Use the conditional <var>INCLUDE</var> command (<code>IF A=B,name</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>
</ul>

===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: 
<ul>
<li>[[Application Subsystem development#Command line global variable|Command line global variable]] </li>

<li>[[Application Subsystem development#Communication global variable|Communication global variable]] </li>

<li>[[Application Subsystem development#Error global variable|Error global variable]] </li>
</ul>

==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 <var>$Date</var> 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: 
<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 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 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>
<li>Conditional INCLUDE command</li>

<li>User Language statement </li>
</ul></li>
</ul>

===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. <var class="product">Model 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.

====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 [[Record retrievals#FILE$ condition|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===
<ul>
<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>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 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>
</ul>

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

====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 <var class="term">labelname</var> 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 <var>Global</var> implies <var>Common</var>. These two keywords are mutually exclusive in the declaration statement. 
<ul>
<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>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>
</ul>

====Usage rules====

The following rules apply to global found sets and lists: 
<ul>
<li>You must declare each global list or global found set as <code>labelname Global</code> in each procedure that uses it. </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.

The <var class="product">Model 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. 
</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>

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

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

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

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. 

===Remember statement===

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 204</var> clears non-global <var>Remember</var> positions at the end of each request.

====Syntax====
{{Template:Remember statement syntax}}
Where:
<ul>
<li>The <var>Global</var> option implies '''PERM''' and the position is retained in GTBL after the current request terminates. If <var>Global</var> is not specified, '''TEMP''' is implied and the position is cleared from GTBL after the current request terminates.</li>
NOTE: The use of GLOBAL here must be consistent with the CLEAR GLOBAL POSITION statement. If the latter is specified with PERM:
CLEAR GLOBAL POSITION PERM 'position_name',
then the REMEMBER statement must specify GLOBAL because it implies PERM.

<li><var class="term">position_name</var> is a unique object name you assign to the <var>Remember</var> position. </li>
NOTE:If the 'position_name' is mixed or lower case, be sure to use the same name, in single quotation marks, when referring to that name in other statements; e.g. CLEAR or POSITION.

<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 foundsortset_name</code> is the label of the <var>Find</var> statement that generated it. </li>

<li>If you are processing a list, <code>On list_name</code> is the name you gave to the list when you originally declared it. </li>
</ul></li>
</ul>

====Usage notes====

The following rules apply to the use of the <var>Remember</var> statement:
<ul>
<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>Is invalid in ad hoc group context, if used with the <var>Global</var> option. </li>

<li>The <var>Remember</var> statement is incompatible with <var>For Each Record In Order By</var> clauses. </li>
</ul>

===Position statement===

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.

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

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

Where:
<ul>
<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.

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. 

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.</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>
NOTE:If the 'position_name' is mixed or lower case, be sure to enclose it here in single quotes. Do the same when referring to that name in other statements; e.g. CLEAR or REMEMBER.
</ul>

====Usage notes====

The following rules apply:
<ul>
<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>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>

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

===How images and screens are processed===

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. 

This section provides some background information about how <var class="product">Model 204</var> 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====
[[File:Nonglobal_object_processing.png|550px]] 

The Nonglobal object processing figure illustrates the process in the following steps:
<ol>
<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 <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>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 Enter for that object, the object is loaded back from CCATEMP to the buffer pool. </li>
</ol>
 

====Processing of global objects====
[[File:Global_object_processing.png|550px]] 

The Global object processing figure illustrates the process in the following steps: 
<ol>
<li>The compiler loads a compiled version of the screen or image into FSCB in the user's server. </li>

<li>A copy of the compiled object is stored in the buffer pool. This copy is called 'VIRGIN', as it is never updated. </li>

<li>A <var>Prepare</var> statement acts on the compiled object in the buffer pool and copies it into GTBL. </li>

<li>Update statements act on the copy in GTBL. </li>
</ol>

===Using Prepare and Identify statements===

To help you decide how to use the <var>Prepare</var> and <var>Identify</var> statements, review the following:
<ul>
<li>[[#GTBL internal work area|GTBL internal work area]] </li>

<li>[[#Timing and placement of a CLEAR statement|Timing and placement of a CLEAR statement]] </li>

<li>For syntax and usage of the <var>Prepare</var> statement, see [[Full-screen feature#PREPARE statement|Prepare statement]]</li>

<li>For syntax and usage of the <var>Identify</var> statement, see [[Images#Identify statement|Identify statement]]

Also when using the <var>Identify</var> statement, see [[#Consistency checks performed|Consistency checks performed]]. </li>
</ul>

===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: 
<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 the FSCB I/O between multiple images and between images and screens. </li>

<li>Makes the declaration of global data explicit, thus traceable by using naming conventions and cross-reference tools. </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>Reduces I/O by swapping modified global screens to CCASERVR instead of paging them between the buffer pool and CCATEMP. </li>
</ul>

===When to use global images and screens===

You achieve the greatest benefit by declaring as <var>Global</var> 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<var> not</var> already present in GTBL, the object is written into GTBL. 

If the object is present, two consistency checks are performed:
<ul>
<li>Persistence — <var>Permanent</var> or <var>Temporary</var> status — of the new object must match the persistence of the object already in GTBL. </li>

<li>Definition — <var>Permanent</var> or <var>Temporary</var> — of the new object must match the definition of the object already in GTBL.
</li>
</ul>
Note: If a global image has an array that uses the <var>Depending On %variable</var> 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 <var>Temporary</var>, but the same image already exists in GTBL, declared as <var>Permanent</var> — 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:
<ul>
<li>SCREENDEF defines a global screen.</li>
<li>IMAGEDEF defines a global image.</li>
<li>PROCA sets the screen item value and an image item value.</li>
<li>PROCB displays the updated image item and the original screen item. </li>
</ul>
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:
<ul>
<li>GTBL size — [[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>VTBL usage with COMMON images and screens — [[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>User since-last statistics — [[Using system statistics#User since-last statistics|User since-last statistics]] </li>
</ul>

==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: 
<ul>
<li>CLEAR statement </li>
<li>CLEARG and/or CLEARGO commands</li>
<li>$DELG function to selectively delete global string variables</li>
<li>RESET command for the GTBLEHASH and GTBLPCT parameters</li>
<li>UTABLE command that changes the size of FTBL, XTBL, or GTBL clears all global objects of any type</li>
</ul>

===Using the CLEARG and CLEARGO commands===
<table>
<tr class="head">
<th>Use this command </th>
<th>To Remove...</th>
</tr>

<tr>
<td><var>[[CLEARG command|CLEARG]]</var> </td>
<td>Only global string variables. </td>
</tr>

<tr>
<td><var>[[CLEARGO command|CLEARGO]]</var></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>
</table>

The <var>CLEARGO</var> command takes no arguments.


===Using the $DELG function===

You can use the <var>[[$Delg]]</var> function to delete global string variables created by either <var>[[$Setg]]</var> or <var>[[$Incrg]]</var>. 

The <var>[[$Delg]]</var> 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 <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: 
<table>
<tr class="head">
<th>The statement </th>
<th>Clears...</th>
</tr>

<tr>
<td nowrap><var>Clear type-of-object 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>
</tr>

<tr>
<td><var>Clear Global</var> </td>
<td>Individual global objects from GTBL. </td>
</tr>

<tr>
<td><var>Clear Globals</var> </td>
<td>All global string variables. You cannot selectively clear individual global string variables with the <var>Clear</var> statement. </td>
</tr>
</table>

====Syntax====

The format for the <var>Clear</var> statement is:
{{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>Position [Perm | Temp]</var> The use of PERM or TEMP must be consistent with GLOBAL in the REMEMBER statement. If GLOBAL is specified in the REMEMBER statement, then PERM is implied. If GLOBAL is omitted from the REMEMBER statement, TEMP is implied.
</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>
NOTE: If the objectname is mixed case, be sure to use the same name, in single quotation marks, when referring to that name in other statements; e.g. REMEMBER or POSITION.

<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 not clear any global objects. </li>
</ul>

====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: 
<ul>
<li>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
</li>

<li>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 <var>CLEARGO</var> command.) </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>Issue a <var>UTABLE</var> command that changes the size of FTBL, XTBL, or GTBL. </li>
</ul>

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:

M204.0301 Referenced statement label undefined

M204.0311 Unacceptable statement reference


===RELEASE and COMMIT RELEASE statements with global foundsets and lists===

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.

===Clearing remembered positions===

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.

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:
<ul>
<li>You can clear a specific temporary position by issuing one of these statements:
Clear Global Position Temp 'objectname'

Clear Global Position Temp %variable
</li>

<li>You can clear a specific permanent position by issuing one of these statements:
Clear Global Position Perm 'objectname'

Clear Global Position Perm %variable
</li>

<li>You clear all global found sets, lists, or sorted sets with which a remembered position is associated:
Clear ListFdst [Global] Objects
</li>

<li>You clear all remembered positions by issuing the statement:
Clear Position [Global] Objects
</li>
</ul>

====Usage notes====
<ul>
<li>When you are using the <var>Clear Global Position</var> statement, <var>Perm</var> is the default. </li>

<li>The <var>CLEARGO</var> command has the effect of clearing all remembered positions.</li>

<li>Any <var>UTABLE</var> command that changes the size of FTBL, GTBL, or XTBL clears all remembered positions.</li>
</ul>

===Timing and placement of a Clear statement===

The <var>Clear Global</var> statement takes effect at evaluation time and its placement in a request can have significant consequences: 
<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>
</ul>

</div> 

[[Category:SOUL]]

Global features

2026-04-23T17:31:03Z

JDamon: /* Syntax */

<div class="toclimit-3">
==Overview==

<var class="product">Model 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 204</var> internal work area or server table called the global table or GTBL. 

The global features are:
<ul>
<li>Global string variables</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>

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 [[Large request considerations#GTBL (global variable table)|GTBL (global variable table)]].

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.

Storage of global variables and global objects in GTBL 
[[File:Storage_of_global_vars_in_GTBL.png|450px]] 

==Global string variables==

You can use global string variables to: 
<ul>
<li>Pass information from one request to another request</li>

<li>Include procedures conditionally at the <var class="product">Model 204</var> command level</li>

<li>Tailor a request dynamically
</li>
</ul>

As of Version 5.1, you can increase the speed and reduce the CPU time to find and update a global string variable by setting the <var>[[GTBLHASH parameter|GTBLHASH]]</var> parameter to a nonzero value. The <var>GTBLHASH</var> parameter specifies the number of buckets allocated in the global string variable section of GTBL.
When <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. 

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 204</var>. 

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. 

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.


====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: 
<table>
<tr class="head">
<th>Statistic </th>
<th>Tracking</th>
</tr>

<tr>
<td>GTBLRU </td>
<td>Number of GTBL rearrangements required to add a string variable global.</td>
</tr>

<tr>
<td>GTBLRS </td>
<td>Number of GTBL rearrangements required to add a global object. </td>
</tr>
</table>

After reviewing the GTBLRU and GTBLRS statistics, you can consider taking the following actions: 
<ul>
<li>If both of these values are high, increase the size of GTBL by increasing <var>LGTBL</var>. </li>

<li>If GTBLRU is high but GTBLRS is not, increase <var>GTBLPCT</var> or decrease <var>GTBLHASH</var>. </li>

<li>If GTBLRS is high but GTBLRU is low, decrease <var>GTBLPCT</var>. </li>
</ul>

===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: 
<ul>
<li>Explicitly delete it</li>

<li>Issue a <var>Release</var> or <var>Commit Release</var> statement </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>Log out </li>
</ul>

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.

====Faster global variable processing option====

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. 

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


===Global positions===

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. 

===Global images and screens===

You can use global images and screens to:
<ul>
<li>Pass image and screen data from one request to another</li>

<li>Manage more than one image or screen in one request</li>

<li>Manage menus, which are a special type of screen</li>

<li>Reduce I/O by swapping modified global screens to CCASERVR instead of paging them between the buffer pool and CCATEMP </li>
</ul>

===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 <var>$Setg</var> function from within a request. 
<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 (<tt>.</tt>) cannot be used as <code>?&</code> dummy strings. </li>

<li>A value can be 0, the null string, or up to 255 characters. </li>
</ul>

===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 <var>CLEARG</var> command, execute a <var>Clear</var> statement, execute a <var>$Delg</var> function call, or you log out. 

If you define a large number of global string variables, <var class="product">Model 204</var> performance can be adversely affected. 

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

===Global variable functions and commands===

The following functions, statements, commands, and facilities manipulate entries in the global variable table: 
<ul>
<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>Use the <code>?&</code> dummy string within a request to read a variable in the GTBL. Refer to [[Procedures]] for more information about dummy strings. </li>

<li>Use the conditional <var>INCLUDE</var> command (<code>IF A=B,name</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>
</ul>

===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: 
<ul>
<li>[[Application Subsystem development#Command line global variable|Command line global variable]] </li>

<li>[[Application Subsystem development#Communication global variable|Communication global variable]] </li>

<li>[[Application Subsystem development#Error global variable|Error global variable]] </li>
</ul>

==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 <var>$Date</var> 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: 
<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 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 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>
<li>Conditional INCLUDE command</li>

<li>User Language statement </li>
</ul></li>
</ul>

===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. <var class="product">Model 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.

====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 [[Record retrievals#FILE$ condition|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===
<ul>
<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>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 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>
</ul>

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

====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 <var class="term">labelname</var> 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 <var>Global</var> implies <var>Common</var>. These two keywords are mutually exclusive in the declaration statement. 
<ul>
<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>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>
</ul>

====Usage rules====

The following rules apply to global found sets and lists: 
<ul>
<li>You must declare each global list or global found set as <code>labelname Global</code> in each procedure that uses it. </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.

The <var class="product">Model 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. 
</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>

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

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

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

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. 

===Remember statement===

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 204</var> clears non-global <var>Remember</var> positions at the end of each request.

====Syntax====
{{Template:Remember statement syntax}}
Where:
<ul>
<li>The <var>Global</var> option implies '''PERM''' and the position is retained in GTBL after the current request terminates. If <var>Global</var> is not specified, '''TEMP''' is implied and the position is cleared from GTBL after the current request terminates.</li>
NOTE: The use of GLOBAL here must be consistent with the CLEAR GLOBAL POSITION statement. If the latter is specified with PERM:
CLEAR GLOBAL POSITION PERM 'position_name',
then the REMEMBER statement must specify GLOBAL because it implies PERM.

<li><var class="term">position_name</var> is a unique object name you assign to the <var>Remember</var> position. </li>
NOTE:If the 'position_name' is mixed or lower case, be sure to use the same name, in single quotation marks, when referring to that name in other statements; e.g. CLEAR or POSITION.

<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 foundsortset_name</code> is the label of the <var>Find</var> statement that generated it. </li>

<li>If you are processing a list, <code>On list_name</code> is the name you gave to the list when you originally declared it. </li>
</ul></li>
</ul>

====Usage notes====

The following rules apply to the use of the <var>Remember</var> statement:
<ul>
<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>Is invalid in ad hoc group context, if used with the <var>Global</var> option. </li>

<li>The <var>Remember</var> statement is incompatible with <var>For Each Record In Order By</var> clauses. </li>
</ul>

===Position statement===

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.

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

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

Where:
<ul>
<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.

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. 

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

====Usage notes====

The following rules apply:
<ul>
<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>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>

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

===How images and screens are processed===

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. 

This section provides some background information about how <var class="product">Model 204</var> 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====
[[File:Nonglobal_object_processing.png|550px]] 

The Nonglobal object processing figure illustrates the process in the following steps:
<ol>
<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 <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>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 Enter for that object, the object is loaded back from CCATEMP to the buffer pool. </li>
</ol>
 

====Processing of global objects====
[[File:Global_object_processing.png|550px]] 

The Global object processing figure illustrates the process in the following steps: 
<ol>
<li>The compiler loads a compiled version of the screen or image into FSCB in the user's server. </li>

<li>A copy of the compiled object is stored in the buffer pool. This copy is called 'VIRGIN', as it is never updated. </li>

<li>A <var>Prepare</var> statement acts on the compiled object in the buffer pool and copies it into GTBL. </li>

<li>Update statements act on the copy in GTBL. </li>
</ol>

===Using Prepare and Identify statements===

To help you decide how to use the <var>Prepare</var> and <var>Identify</var> statements, review the following:
<ul>
<li>[[#GTBL internal work area|GTBL internal work area]] </li>

<li>[[#Timing and placement of a CLEAR statement|Timing and placement of a CLEAR statement]] </li>

<li>For syntax and usage of the <var>Prepare</var> statement, see [[Full-screen feature#PREPARE statement|Prepare statement]]</li>

<li>For syntax and usage of the <var>Identify</var> statement, see [[Images#Identify statement|Identify statement]]

Also when using the <var>Identify</var> statement, see [[#Consistency checks performed|Consistency checks performed]]. </li>
</ul>

===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: 
<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 the FSCB I/O between multiple images and between images and screens. </li>

<li>Makes the declaration of global data explicit, thus traceable by using naming conventions and cross-reference tools. </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>Reduces I/O by swapping modified global screens to CCASERVR instead of paging them between the buffer pool and CCATEMP. </li>
</ul>

===When to use global images and screens===

You achieve the greatest benefit by declaring as <var>Global</var> 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<var> not</var> already present in GTBL, the object is written into GTBL. 

If the object is present, two consistency checks are performed:
<ul>
<li>Persistence — <var>Permanent</var> or <var>Temporary</var> status — of the new object must match the persistence of the object already in GTBL. </li>

<li>Definition — <var>Permanent</var> or <var>Temporary</var> — of the new object must match the definition of the object already in GTBL.
</li>
</ul>
Note: If a global image has an array that uses the <var>Depending On %variable</var> 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 <var>Temporary</var>, but the same image already exists in GTBL, declared as <var>Permanent</var> — 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:
<ul>
<li>SCREENDEF defines a global screen.</li>
<li>IMAGEDEF defines a global image.</li>
<li>PROCA sets the screen item value and an image item value.</li>
<li>PROCB displays the updated image item and the original screen item. </li>
</ul>
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:
<ul>
<li>GTBL size — [[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>VTBL usage with COMMON images and screens — [[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>User since-last statistics — [[Using system statistics#User since-last statistics|User since-last statistics]] </li>
</ul>

==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: 
<ul>
<li>CLEAR statement </li>
<li>CLEARG and/or CLEARGO commands</li>
<li>$DELG function to selectively delete global string variables</li>
<li>RESET command for the GTBLEHASH and GTBLPCT parameters</li>
<li>UTABLE command that changes the size of FTBL, XTBL, or GTBL clears all global objects of any type</li>
</ul>

===Using the CLEARG and CLEARGO commands===
<table>
<tr class="head">
<th>Use this command </th>
<th>To Remove...</th>
</tr>

<tr>
<td><var>[[CLEARG command|CLEARG]]</var> </td>
<td>Only global string variables. </td>
</tr>

<tr>
<td><var>[[CLEARGO command|CLEARGO]]</var></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>
</table>

The <var>CLEARGO</var> command takes no arguments.


===Using the $DELG function===

You can use the <var>[[$Delg]]</var> function to delete global string variables created by either <var>[[$Setg]]</var> or <var>[[$Incrg]]</var>. 

The <var>[[$Delg]]</var> 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 <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: 
<table>
<tr class="head">
<th>The statement </th>
<th>Clears...</th>
</tr>

<tr>
<td nowrap><var>Clear type-of-object 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>
</tr>

<tr>
<td><var>Clear Global</var> </td>
<td>Individual global objects from GTBL. </td>
</tr>

<tr>
<td><var>Clear Globals</var> </td>
<td>All global string variables. You cannot selectively clear individual global string variables with the <var>Clear</var> statement. </td>
</tr>
</table>

====Syntax====

The format for the <var>Clear</var> statement is:
{{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>Position [Perm | Temp]</var> The use of PERM or TEMP must be consistent with GLOBAL in the REMEMBER statement. If GLOBAL is specified in the REMEMBER statement, then PERM is implied. If GLOBAL is omitted from the REMEMBER statement, TEMP is implied.
</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>
NOTE: If the objectname is mixed case, be sure to use the same name, in single quotation marks, when referring to that name in other statements; e.g. REMEMBER or POSITION.

<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 not clear any global objects. </li>
</ul>

====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: 
<ul>
<li>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
</li>

<li>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 <var>CLEARGO</var> command.) </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>Issue a <var>UTABLE</var> command that changes the size of FTBL, XTBL, or GTBL. </li>
</ul>

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:

M204.0301 Referenced statement label undefined

M204.0311 Unacceptable statement reference


===RELEASE and COMMIT RELEASE statements with global foundsets and lists===

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.

===Clearing remembered positions===

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.

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:
<ul>
<li>You can clear a specific temporary position by issuing one of these statements:
Clear Global Position Temp 'objectname'

Clear Global Position Temp %variable
</li>

<li>You can clear a specific permanent position by issuing one of these statements:
Clear Global Position Perm 'objectname'

Clear Global Position Perm %variable
</li>

<li>You clear all global found sets, lists, or sorted sets with which a remembered position is associated:
Clear ListFdst [Global] Objects
</li>

<li>You clear all remembered positions by issuing the statement:
Clear Position [Global] Objects
</li>
</ul>

====Usage notes====
<ul>
<li>When you are using the <var>Clear Global Position</var> statement, <var>Perm</var> is the default. </li>

<li>The <var>CLEARGO</var> command has the effect of clearing all remembered positions.</li>

<li>Any <var>UTABLE</var> command that changes the size of FTBL, GTBL, or XTBL clears all remembered positions.</li>
</ul>

===Timing and placement of a Clear statement===

The <var>Clear Global</var> statement takes effect at evaluation time and its placement in a request can have significant consequences: 
<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>
</ul>

</div> 

[[Category:SOUL]]

Global features

2026-04-23T17:07:37Z

JDamon: /* Remember statement */

<div class="toclimit-3">
==Overview==

<var class="product">Model 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 204</var> internal work area or server table called the global table or GTBL. 

The global features are:
<ul>
<li>Global string variables</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>

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 [[Large request considerations#GTBL (global variable table)|GTBL (global variable table)]].

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.

Storage of global variables and global objects in GTBL 
[[File:Storage_of_global_vars_in_GTBL.png|450px]] 

==Global string variables==

You can use global string variables to: 
<ul>
<li>Pass information from one request to another request</li>

<li>Include procedures conditionally at the <var class="product">Model 204</var> command level</li>

<li>Tailor a request dynamically
</li>
</ul>

As of Version 5.1, you can increase the speed and reduce the CPU time to find and update a global string variable by setting the <var>[[GTBLHASH parameter|GTBLHASH]]</var> parameter to a nonzero value. The <var>GTBLHASH</var> parameter specifies the number of buckets allocated in the global string variable section of GTBL.
When <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. 

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 204</var>. 

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. 

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.


====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: 
<table>
<tr class="head">
<th>Statistic </th>
<th>Tracking</th>
</tr>

<tr>
<td>GTBLRU </td>
<td>Number of GTBL rearrangements required to add a string variable global.</td>
</tr>

<tr>
<td>GTBLRS </td>
<td>Number of GTBL rearrangements required to add a global object. </td>
</tr>
</table>

After reviewing the GTBLRU and GTBLRS statistics, you can consider taking the following actions: 
<ul>
<li>If both of these values are high, increase the size of GTBL by increasing <var>LGTBL</var>. </li>

<li>If GTBLRU is high but GTBLRS is not, increase <var>GTBLPCT</var> or decrease <var>GTBLHASH</var>. </li>

<li>If GTBLRS is high but GTBLRU is low, decrease <var>GTBLPCT</var>. </li>
</ul>

===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: 
<ul>
<li>Explicitly delete it</li>

<li>Issue a <var>Release</var> or <var>Commit Release</var> statement </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>Log out </li>
</ul>

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.

====Faster global variable processing option====

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. 

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


===Global positions===

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. 

===Global images and screens===

You can use global images and screens to:
<ul>
<li>Pass image and screen data from one request to another</li>

<li>Manage more than one image or screen in one request</li>

<li>Manage menus, which are a special type of screen</li>

<li>Reduce I/O by swapping modified global screens to CCASERVR instead of paging them between the buffer pool and CCATEMP </li>
</ul>

===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 <var>$Setg</var> function from within a request. 
<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 (<tt>.</tt>) cannot be used as <code>?&</code> dummy strings. </li>

<li>A value can be 0, the null string, or up to 255 characters. </li>
</ul>

===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 <var>CLEARG</var> command, execute a <var>Clear</var> statement, execute a <var>$Delg</var> function call, or you log out. 

If you define a large number of global string variables, <var class="product">Model 204</var> performance can be adversely affected. 

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

===Global variable functions and commands===

The following functions, statements, commands, and facilities manipulate entries in the global variable table: 
<ul>
<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>Use the <code>?&</code> dummy string within a request to read a variable in the GTBL. Refer to [[Procedures]] for more information about dummy strings. </li>

<li>Use the conditional <var>INCLUDE</var> command (<code>IF A=B,name</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>
</ul>

===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: 
<ul>
<li>[[Application Subsystem development#Command line global variable|Command line global variable]] </li>

<li>[[Application Subsystem development#Communication global variable|Communication global variable]] </li>

<li>[[Application Subsystem development#Error global variable|Error global variable]] </li>
</ul>

==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 <var>$Date</var> 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: 
<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 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 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>
<li>Conditional INCLUDE command</li>

<li>User Language statement </li>
</ul></li>
</ul>

===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. <var class="product">Model 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.

====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 [[Record retrievals#FILE$ condition|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===
<ul>
<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>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 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>
</ul>

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

====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 <var class="term">labelname</var> 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 <var>Global</var> implies <var>Common</var>. These two keywords are mutually exclusive in the declaration statement. 
<ul>
<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>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>
</ul>

====Usage rules====

The following rules apply to global found sets and lists: 
<ul>
<li>You must declare each global list or global found set as <code>labelname Global</code> in each procedure that uses it. </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.

The <var class="product">Model 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. 
</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>

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

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

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

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. 

===Remember statement===

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 204</var> clears non-global <var>Remember</var> positions at the end of each request.

====Syntax====
{{Template:Remember statement syntax}}
Where:
<ul>
<li>The <var>Global</var> option implies Perm and the position is retained in GTBL after the current request terminates. If <var>Global</var> is not specified, TEMP is implied and the position is cleared from GTBL after the current request terminates.</li>
NOTE: The use of GLOBAL here must be consistent with the CLEAR GLOBAL POSITION statement. If the latter is specified with PERM:
CLEAR GLOBAL POSITION PERM 'position_name',
then the REMEMBER statement must specify GLOBAL because it implies PERM.

<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 foundsortset_name</code> is the label of the <var>Find</var> statement that generated it. </li>

<li>If you are processing a list, <code>On list_name</code> is the name you gave to the list when you originally declared it. </li>
</ul></li>
</ul>

====Usage notes====

The following rules apply to the use of the <var>Remember</var> statement:
<ul>
<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>Is invalid in ad hoc group context, if used with the <var>Global</var> option. </li>

<li>The <var>Remember</var> statement is incompatible with <var>For Each Record In Order By</var> clauses. </li>
</ul>

===Position statement===

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.

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

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

Where:
<ul>
<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.

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. 

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

====Usage notes====

The following rules apply:
<ul>
<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>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>

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

===How images and screens are processed===

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. 

This section provides some background information about how <var class="product">Model 204</var> 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====
[[File:Nonglobal_object_processing.png|550px]] 

The Nonglobal object processing figure illustrates the process in the following steps:
<ol>
<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 <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>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 Enter for that object, the object is loaded back from CCATEMP to the buffer pool. </li>
</ol>
 

====Processing of global objects====
[[File:Global_object_processing.png|550px]] 

The Global object processing figure illustrates the process in the following steps: 
<ol>
<li>The compiler loads a compiled version of the screen or image into FSCB in the user's server. </li>

<li>A copy of the compiled object is stored in the buffer pool. This copy is called 'VIRGIN', as it is never updated. </li>

<li>A <var>Prepare</var> statement acts on the compiled object in the buffer pool and copies it into GTBL. </li>

<li>Update statements act on the copy in GTBL. </li>
</ol>

===Using Prepare and Identify statements===

To help you decide how to use the <var>Prepare</var> and <var>Identify</var> statements, review the following:
<ul>
<li>[[#GTBL internal work area|GTBL internal work area]] </li>

<li>[[#Timing and placement of a CLEAR statement|Timing and placement of a CLEAR statement]] </li>

<li>For syntax and usage of the <var>Prepare</var> statement, see [[Full-screen feature#PREPARE statement|Prepare statement]]</li>

<li>For syntax and usage of the <var>Identify</var> statement, see [[Images#Identify statement|Identify statement]]

Also when using the <var>Identify</var> statement, see [[#Consistency checks performed|Consistency checks performed]]. </li>
</ul>

===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: 
<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 the FSCB I/O between multiple images and between images and screens. </li>

<li>Makes the declaration of global data explicit, thus traceable by using naming conventions and cross-reference tools. </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>Reduces I/O by swapping modified global screens to CCASERVR instead of paging them between the buffer pool and CCATEMP. </li>
</ul>

===When to use global images and screens===

You achieve the greatest benefit by declaring as <var>Global</var> 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<var> not</var> already present in GTBL, the object is written into GTBL. 

If the object is present, two consistency checks are performed:
<ul>
<li>Persistence — <var>Permanent</var> or <var>Temporary</var> status — of the new object must match the persistence of the object already in GTBL. </li>

<li>Definition — <var>Permanent</var> or <var>Temporary</var> — of the new object must match the definition of the object already in GTBL.
</li>
</ul>
Note: If a global image has an array that uses the <var>Depending On %variable</var> 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 <var>Temporary</var>, but the same image already exists in GTBL, declared as <var>Permanent</var> — 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:
<ul>
<li>SCREENDEF defines a global screen.</li>
<li>IMAGEDEF defines a global image.</li>
<li>PROCA sets the screen item value and an image item value.</li>
<li>PROCB displays the updated image item and the original screen item. </li>
</ul>
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:
<ul>
<li>GTBL size — [[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>VTBL usage with COMMON images and screens — [[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>User since-last statistics — [[Using system statistics#User since-last statistics|User since-last statistics]] </li>
</ul>

==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: 
<ul>
<li>CLEAR statement </li>
<li>CLEARG and/or CLEARGO commands</li>
<li>$DELG function to selectively delete global string variables</li>
<li>RESET command for the GTBLEHASH and GTBLPCT parameters</li>
<li>UTABLE command that changes the size of FTBL, XTBL, or GTBL clears all global objects of any type</li>
</ul>

===Using the CLEARG and CLEARGO commands===
<table>
<tr class="head">
<th>Use this command </th>
<th>To Remove...</th>
</tr>

<tr>
<td><var>[[CLEARG command|CLEARG]]</var> </td>
<td>Only global string variables. </td>
</tr>

<tr>
<td><var>[[CLEARGO command|CLEARGO]]</var></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>
</table>

The <var>CLEARGO</var> command takes no arguments.


===Using the $DELG function===

You can use the <var>[[$Delg]]</var> function to delete global string variables created by either <var>[[$Setg]]</var> or <var>[[$Incrg]]</var>. 

The <var>[[$Delg]]</var> 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 <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: 
<table>
<tr class="head">
<th>The statement </th>
<th>Clears...</th>
</tr>

<tr>
<td nowrap><var>Clear type-of-object 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>
</tr>

<tr>
<td><var>Clear Global</var> </td>
<td>Individual global objects from GTBL. </td>
</tr>

<tr>
<td><var>Clear Globals</var> </td>
<td>All global string variables. You cannot selectively clear individual global string variables with the <var>Clear</var> statement. </td>
</tr>
</table>

====Syntax====

The format for the <var>Clear</var> statement is:
{{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>Position [Perm | Temp]</var> The use of PERM or TEMP must be consistent with GLOBAL in the REMEMBER statement. If GLOBAL is specified in the REMEMBER statement, then PERM is implied. If GLOBAL is omitted from the REMEMBER statement, TEMP is implied.
</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>
NOTE: If the objectname is mixed case, be sure to use the same name, in single quotation marks, when referring to that name in other statements; e.g. REMEMBER or POSITION.

<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 not clear any global objects. </li>
</ul>

====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: 
<ul>
<li>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
</li>

<li>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 <var>CLEARGO</var> command.) </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>Issue a <var>UTABLE</var> command that changes the size of FTBL, XTBL, or GTBL. </li>
</ul>

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:

M204.0301 Referenced statement label undefined

M204.0311 Unacceptable statement reference


===RELEASE and COMMIT RELEASE statements with global foundsets and lists===

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.

===Clearing remembered positions===

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.

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:
<ul>
<li>You can clear a specific temporary position by issuing one of these statements:
Clear Global Position Temp 'objectname'

Clear Global Position Temp %variable
</li>

<li>You can clear a specific permanent position by issuing one of these statements:
Clear Global Position Perm 'objectname'

Clear Global Position Perm %variable
</li>

<li>You clear all global found sets, lists, or sorted sets with which a remembered position is associated:
Clear ListFdst [Global] Objects
</li>

<li>You clear all remembered positions by issuing the statement:
Clear Position [Global] Objects
</li>
</ul>

====Usage notes====
<ul>
<li>When you are using the <var>Clear Global Position</var> statement, <var>Perm</var> is the default. </li>

<li>The <var>CLEARGO</var> command has the effect of clearing all remembered positions.</li>

<li>Any <var>UTABLE</var> command that changes the size of FTBL, GTBL, or XTBL clears all remembered positions.</li>
</ul>

===Timing and placement of a Clear statement===

The <var>Clear Global</var> statement takes effect at evaluation time and its placement in a request can have significant consequences: 
<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>
</ul>

</div> 

[[Category:SOUL]]

Global features

2026-04-13T20:08:20Z

JDamon: /* Syntax */

<div class="toclimit-3">
==Overview==

<var class="product">Model 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 204</var> internal work area or server table called the global table or GTBL. 

The global features are:
<ul>
<li>Global string variables</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>

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 [[Large request considerations#GTBL (global variable table)|GTBL (global variable table)]].

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.

Storage of global variables and global objects in GTBL 
[[File:Storage_of_global_vars_in_GTBL.png|450px]] 

==Global string variables==

You can use global string variables to: 
<ul>
<li>Pass information from one request to another request</li>

<li>Include procedures conditionally at the <var class="product">Model 204</var> command level</li>

<li>Tailor a request dynamically
</li>
</ul>

As of Version 5.1, you can increase the speed and reduce the CPU time to find and update a global string variable by setting the <var>[[GTBLHASH parameter|GTBLHASH]]</var> parameter to a nonzero value. The <var>GTBLHASH</var> parameter specifies the number of buckets allocated in the global string variable section of GTBL.
When <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. 

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 204</var>. 

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. 

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.


====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: 
<table>
<tr class="head">
<th>Statistic </th>
<th>Tracking</th>
</tr>

<tr>
<td>GTBLRU </td>
<td>Number of GTBL rearrangements required to add a string variable global.</td>
</tr>

<tr>
<td>GTBLRS </td>
<td>Number of GTBL rearrangements required to add a global object. </td>
</tr>
</table>

After reviewing the GTBLRU and GTBLRS statistics, you can consider taking the following actions: 
<ul>
<li>If both of these values are high, increase the size of GTBL by increasing <var>LGTBL</var>. </li>

<li>If GTBLRU is high but GTBLRS is not, increase <var>GTBLPCT</var> or decrease <var>GTBLHASH</var>. </li>

<li>If GTBLRS is high but GTBLRU is low, decrease <var>GTBLPCT</var>. </li>
</ul>

===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: 
<ul>
<li>Explicitly delete it</li>

<li>Issue a <var>Release</var> or <var>Commit Release</var> statement </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>Log out </li>
</ul>

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.

====Faster global variable processing option====

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. 

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


===Global positions===

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. 

===Global images and screens===

You can use global images and screens to:
<ul>
<li>Pass image and screen data from one request to another</li>

<li>Manage more than one image or screen in one request</li>

<li>Manage menus, which are a special type of screen</li>

<li>Reduce I/O by swapping modified global screens to CCASERVR instead of paging them between the buffer pool and CCATEMP </li>
</ul>

===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 <var>$Setg</var> function from within a request. 
<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 (<tt>.</tt>) cannot be used as <code>?&</code> dummy strings. </li>

<li>A value can be 0, the null string, or up to 255 characters. </li>
</ul>

===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 <var>CLEARG</var> command, execute a <var>Clear</var> statement, execute a <var>$Delg</var> function call, or you log out. 

If you define a large number of global string variables, <var class="product">Model 204</var> performance can be adversely affected. 

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

===Global variable functions and commands===

The following functions, statements, commands, and facilities manipulate entries in the global variable table: 
<ul>
<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>Use the <code>?&</code> dummy string within a request to read a variable in the GTBL. Refer to [[Procedures]] for more information about dummy strings. </li>

<li>Use the conditional <var>INCLUDE</var> command (<code>IF A=B,name</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>
</ul>

===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: 
<ul>
<li>[[Application Subsystem development#Command line global variable|Command line global variable]] </li>

<li>[[Application Subsystem development#Communication global variable|Communication global variable]] </li>

<li>[[Application Subsystem development#Error global variable|Error global variable]] </li>
</ul>

==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 <var>$Date</var> 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: 
<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 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 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>
<li>Conditional INCLUDE command</li>

<li>User Language statement </li>
</ul></li>
</ul>

===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. <var class="product">Model 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.

====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 [[Record retrievals#FILE$ condition|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===
<ul>
<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>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 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>
</ul>

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

====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 <var class="term">labelname</var> 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 <var>Global</var> implies <var>Common</var>. These two keywords are mutually exclusive in the declaration statement. 
<ul>
<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>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>
</ul>

====Usage rules====

The following rules apply to global found sets and lists: 
<ul>
<li>You must declare each global list or global found set as <code>labelname Global</code> in each procedure that uses it. </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.

The <var class="product">Model 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. 
</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>

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

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

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

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. 

===Remember statement===

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 204</var> clears non-global <var>Remember</var> positions at the end of each request.

====Syntax====
{{Template:Remember statement syntax}}
Where:
<ul>
<li>The <var>Global</var> option implies Perm and the position is retained in GTBL after the current request terminates. If <var>Global</var> is not specified, TEMP is implied and the position is cleared from GTBL after the current request terminates.</li>
NOTE: The use of GLOBAL here must be consistent with the CLEAR GLOBAL POSITION statement. If the latter is specified with PERM:
CLEAR GLOBAL POSITION PERM 'objectname',
then the REMEMBER statement must specify GLOBAL because it implies PERM.

<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 foundsortset_name</code> is the label of the <var>Find</var> statement that generated it. </li>

<li>If you are processing a list, <code>On list_name</code> is the name you gave to the list when you originally declared it. </li>
</ul></li>
</ul>

====Usage notes====

The following rules apply to the use of the <var>Remember</var> statement:
<ul>
<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>Is invalid in ad hoc group context, if used with the <var>Global</var> option. </li>

<li>The <var>Remember</var> statement is incompatible with <var>For Each Record In Order By</var> clauses. </li>
</ul>

===Position statement===

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.

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

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

Where:
<ul>
<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.

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. 

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

====Usage notes====

The following rules apply:
<ul>
<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>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>

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

===How images and screens are processed===

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. 

This section provides some background information about how <var class="product">Model 204</var> 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====
[[File:Nonglobal_object_processing.png|550px]] 

The Nonglobal object processing figure illustrates the process in the following steps:
<ol>
<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 <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>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 Enter for that object, the object is loaded back from CCATEMP to the buffer pool. </li>
</ol>
 

====Processing of global objects====
[[File:Global_object_processing.png|550px]] 

The Global object processing figure illustrates the process in the following steps: 
<ol>
<li>The compiler loads a compiled version of the screen or image into FSCB in the user's server. </li>

<li>A copy of the compiled object is stored in the buffer pool. This copy is called 'VIRGIN', as it is never updated. </li>

<li>A <var>Prepare</var> statement acts on the compiled object in the buffer pool and copies it into GTBL. </li>

<li>Update statements act on the copy in GTBL. </li>
</ol>

===Using Prepare and Identify statements===

To help you decide how to use the <var>Prepare</var> and <var>Identify</var> statements, review the following:
<ul>
<li>[[#GTBL internal work area|GTBL internal work area]] </li>

<li>[[#Timing and placement of a CLEAR statement|Timing and placement of a CLEAR statement]] </li>

<li>For syntax and usage of the <var>Prepare</var> statement, see [[Full-screen feature#PREPARE statement|Prepare statement]]</li>

<li>For syntax and usage of the <var>Identify</var> statement, see [[Images#Identify statement|Identify statement]]

Also when using the <var>Identify</var> statement, see [[#Consistency checks performed|Consistency checks performed]]. </li>
</ul>

===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: 
<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 the FSCB I/O between multiple images and between images and screens. </li>

<li>Makes the declaration of global data explicit, thus traceable by using naming conventions and cross-reference tools. </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>Reduces I/O by swapping modified global screens to CCASERVR instead of paging them between the buffer pool and CCATEMP. </li>
</ul>

===When to use global images and screens===

You achieve the greatest benefit by declaring as <var>Global</var> 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<var> not</var> already present in GTBL, the object is written into GTBL. 

If the object is present, two consistency checks are performed:
<ul>
<li>Persistence — <var>Permanent</var> or <var>Temporary</var> status — of the new object must match the persistence of the object already in GTBL. </li>

<li>Definition — <var>Permanent</var> or <var>Temporary</var> — of the new object must match the definition of the object already in GTBL.
</li>
</ul>
Note: If a global image has an array that uses the <var>Depending On %variable</var> 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 <var>Temporary</var>, but the same image already exists in GTBL, declared as <var>Permanent</var> — 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:
<ul>
<li>SCREENDEF defines a global screen.</li>
<li>IMAGEDEF defines a global image.</li>
<li>PROCA sets the screen item value and an image item value.</li>
<li>PROCB displays the updated image item and the original screen item. </li>
</ul>
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:
<ul>
<li>GTBL size — [[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>VTBL usage with COMMON images and screens — [[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>User since-last statistics — [[Using system statistics#User since-last statistics|User since-last statistics]] </li>
</ul>

==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: 
<ul>
<li>CLEAR statement </li>
<li>CLEARG and/or CLEARGO commands</li>
<li>$DELG function to selectively delete global string variables</li>
<li>RESET command for the GTBLEHASH and GTBLPCT parameters</li>
<li>UTABLE command that changes the size of FTBL, XTBL, or GTBL clears all global objects of any type</li>
</ul>

===Using the CLEARG and CLEARGO commands===
<table>
<tr class="head">
<th>Use this command </th>
<th>To Remove...</th>
</tr>

<tr>
<td><var>[[CLEARG command|CLEARG]]</var> </td>
<td>Only global string variables. </td>
</tr>

<tr>
<td><var>[[CLEARGO command|CLEARGO]]</var></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>
</table>

The <var>CLEARGO</var> command takes no arguments.


===Using the $DELG function===

You can use the <var>[[$Delg]]</var> function to delete global string variables created by either <var>[[$Setg]]</var> or <var>[[$Incrg]]</var>. 

The <var>[[$Delg]]</var> 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 <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: 
<table>
<tr class="head">
<th>The statement </th>
<th>Clears...</th>
</tr>

<tr>
<td nowrap><var>Clear type-of-object 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>
</tr>

<tr>
<td><var>Clear Global</var> </td>
<td>Individual global objects from GTBL. </td>
</tr>

<tr>
<td><var>Clear Globals</var> </td>
<td>All global string variables. You cannot selectively clear individual global string variables with the <var>Clear</var> statement. </td>
</tr>
</table>

====Syntax====

The format for the <var>Clear</var> statement is:
{{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>Position [Perm | Temp]</var> The use of PERM or TEMP must be consistent with GLOBAL in the REMEMBER statement. If GLOBAL is specified in the REMEMBER statement, then PERM is implied. If GLOBAL is omitted from the REMEMBER statement, TEMP is implied.
</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>
NOTE: If the objectname is mixed case, be sure to use the same name, in single quotation marks, when referring to that name in other statements; e.g. REMEMBER or POSITION.

<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 not clear any global objects. </li>
</ul>

====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: 
<ul>
<li>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
</li>

<li>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 <var>CLEARGO</var> command.) </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>Issue a <var>UTABLE</var> command that changes the size of FTBL, XTBL, or GTBL. </li>
</ul>

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:

M204.0301 Referenced statement label undefined

M204.0311 Unacceptable statement reference


===RELEASE and COMMIT RELEASE statements with global foundsets and lists===

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.

===Clearing remembered positions===

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.

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:
<ul>
<li>You can clear a specific temporary position by issuing one of these statements:
Clear Global Position Temp 'objectname'

Clear Global Position Temp %variable
</li>

<li>You can clear a specific permanent position by issuing one of these statements:
Clear Global Position Perm 'objectname'

Clear Global Position Perm %variable
</li>

<li>You clear all global found sets, lists, or sorted sets with which a remembered position is associated:
Clear ListFdst [Global] Objects
</li>

<li>You clear all remembered positions by issuing the statement:
Clear Position [Global] Objects
</li>
</ul>

====Usage notes====
<ul>
<li>When you are using the <var>Clear Global Position</var> statement, <var>Perm</var> is the default. </li>

<li>The <var>CLEARGO</var> command has the effect of clearing all remembered positions.</li>

<li>Any <var>UTABLE</var> command that changes the size of FTBL, GTBL, or XTBL clears all remembered positions.</li>
</ul>

===Timing and placement of a Clear statement===

The <var>Clear Global</var> statement takes effect at evaluation time and its placement in a request can have significant consequences: 
<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>
</ul>

</div> 

[[Category:SOUL]]

Global features

2026-04-13T19:29:24Z

JDamon: /* Syntax */

<div class="toclimit-3">
==Overview==

<var class="product">Model 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 204</var> internal work area or server table called the global table or GTBL. 

The global features are:
<ul>
<li>Global string variables</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>

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 [[Large request considerations#GTBL (global variable table)|GTBL (global variable table)]].

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.

Storage of global variables and global objects in GTBL 
[[File:Storage_of_global_vars_in_GTBL.png|450px]] 

==Global string variables==

You can use global string variables to: 
<ul>
<li>Pass information from one request to another request</li>

<li>Include procedures conditionally at the <var class="product">Model 204</var> command level</li>

<li>Tailor a request dynamically
</li>
</ul>

As of Version 5.1, you can increase the speed and reduce the CPU time to find and update a global string variable by setting the <var>[[GTBLHASH parameter|GTBLHASH]]</var> parameter to a nonzero value. The <var>GTBLHASH</var> parameter specifies the number of buckets allocated in the global string variable section of GTBL.
When <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. 

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 204</var>. 

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. 

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.


====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: 
<table>
<tr class="head">
<th>Statistic </th>
<th>Tracking</th>
</tr>

<tr>
<td>GTBLRU </td>
<td>Number of GTBL rearrangements required to add a string variable global.</td>
</tr>

<tr>
<td>GTBLRS </td>
<td>Number of GTBL rearrangements required to add a global object. </td>
</tr>
</table>

After reviewing the GTBLRU and GTBLRS statistics, you can consider taking the following actions: 
<ul>
<li>If both of these values are high, increase the size of GTBL by increasing <var>LGTBL</var>. </li>

<li>If GTBLRU is high but GTBLRS is not, increase <var>GTBLPCT</var> or decrease <var>GTBLHASH</var>. </li>

<li>If GTBLRS is high but GTBLRU is low, decrease <var>GTBLPCT</var>. </li>
</ul>

===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: 
<ul>
<li>Explicitly delete it</li>

<li>Issue a <var>Release</var> or <var>Commit Release</var> statement </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>Log out </li>
</ul>

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.

====Faster global variable processing option====

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. 

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


===Global positions===

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. 

===Global images and screens===

You can use global images and screens to:
<ul>
<li>Pass image and screen data from one request to another</li>

<li>Manage more than one image or screen in one request</li>

<li>Manage menus, which are a special type of screen</li>

<li>Reduce I/O by swapping modified global screens to CCASERVR instead of paging them between the buffer pool and CCATEMP </li>
</ul>

===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 <var>$Setg</var> function from within a request. 
<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 (<tt>.</tt>) cannot be used as <code>?&</code> dummy strings. </li>

<li>A value can be 0, the null string, or up to 255 characters. </li>
</ul>

===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 <var>CLEARG</var> command, execute a <var>Clear</var> statement, execute a <var>$Delg</var> function call, or you log out. 

If you define a large number of global string variables, <var class="product">Model 204</var> performance can be adversely affected. 

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

===Global variable functions and commands===

The following functions, statements, commands, and facilities manipulate entries in the global variable table: 
<ul>
<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>Use the <code>?&</code> dummy string within a request to read a variable in the GTBL. Refer to [[Procedures]] for more information about dummy strings. </li>

<li>Use the conditional <var>INCLUDE</var> command (<code>IF A=B,name</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>
</ul>

===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: 
<ul>
<li>[[Application Subsystem development#Command line global variable|Command line global variable]] </li>

<li>[[Application Subsystem development#Communication global variable|Communication global variable]] </li>

<li>[[Application Subsystem development#Error global variable|Error global variable]] </li>
</ul>

==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 <var>$Date</var> 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: 
<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 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 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>
<li>Conditional INCLUDE command</li>

<li>User Language statement </li>
</ul></li>
</ul>

===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. <var class="product">Model 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.

====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 [[Record retrievals#FILE$ condition|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===
<ul>
<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>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 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>
</ul>

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

====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 <var class="term">labelname</var> 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 <var>Global</var> implies <var>Common</var>. These two keywords are mutually exclusive in the declaration statement. 
<ul>
<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>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>
</ul>

====Usage rules====

The following rules apply to global found sets and lists: 
<ul>
<li>You must declare each global list or global found set as <code>labelname Global</code> in each procedure that uses it. </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.

The <var class="product">Model 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. 
</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>

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

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

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

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. 

===Remember statement===

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 204</var> clears non-global <var>Remember</var> positions at the end of each request.

====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 foundsortset_name</code> is the label of the <var>Find</var> statement that generated it. </li>

<li>If you are processing a list, <code>On list_name</code> is the name you gave to the list when you originally declared it. </li>
</ul></li>
</ul>

====Usage notes====

The following rules apply to the use of the <var>Remember</var> statement:
<ul>
<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>Is invalid in ad hoc group context, if used with the <var>Global</var> option. </li>

<li>The <var>Remember</var> statement is incompatible with <var>For Each Record In Order By</var> clauses. </li>
</ul>

===Position statement===

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.

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

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

Where:
<ul>
<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.

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. 

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

====Usage notes====

The following rules apply:
<ul>
<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>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>

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

===How images and screens are processed===

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. 

This section provides some background information about how <var class="product">Model 204</var> 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====
[[File:Nonglobal_object_processing.png|550px]] 

The Nonglobal object processing figure illustrates the process in the following steps:
<ol>
<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 <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>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 Enter for that object, the object is loaded back from CCATEMP to the buffer pool. </li>
</ol>
 

====Processing of global objects====
[[File:Global_object_processing.png|550px]] 

The Global object processing figure illustrates the process in the following steps: 
<ol>
<li>The compiler loads a compiled version of the screen or image into FSCB in the user's server. </li>

<li>A copy of the compiled object is stored in the buffer pool. This copy is called 'VIRGIN', as it is never updated. </li>

<li>A <var>Prepare</var> statement acts on the compiled object in the buffer pool and copies it into GTBL. </li>

<li>Update statements act on the copy in GTBL. </li>
</ol>

===Using Prepare and Identify statements===

To help you decide how to use the <var>Prepare</var> and <var>Identify</var> statements, review the following:
<ul>
<li>[[#GTBL internal work area|GTBL internal work area]] </li>

<li>[[#Timing and placement of a CLEAR statement|Timing and placement of a CLEAR statement]] </li>

<li>For syntax and usage of the <var>Prepare</var> statement, see [[Full-screen feature#PREPARE statement|Prepare statement]]</li>

<li>For syntax and usage of the <var>Identify</var> statement, see [[Images#Identify statement|Identify statement]]

Also when using the <var>Identify</var> statement, see [[#Consistency checks performed|Consistency checks performed]]. </li>
</ul>

===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: 
<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 the FSCB I/O between multiple images and between images and screens. </li>

<li>Makes the declaration of global data explicit, thus traceable by using naming conventions and cross-reference tools. </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>Reduces I/O by swapping modified global screens to CCASERVR instead of paging them between the buffer pool and CCATEMP. </li>
</ul>

===When to use global images and screens===

You achieve the greatest benefit by declaring as <var>Global</var> 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<var> not</var> already present in GTBL, the object is written into GTBL. 

If the object is present, two consistency checks are performed:
<ul>
<li>Persistence — <var>Permanent</var> or <var>Temporary</var> status — of the new object must match the persistence of the object already in GTBL. </li>

<li>Definition — <var>Permanent</var> or <var>Temporary</var> — of the new object must match the definition of the object already in GTBL.
</li>
</ul>
Note: If a global image has an array that uses the <var>Depending On %variable</var> 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 <var>Temporary</var>, but the same image already exists in GTBL, declared as <var>Permanent</var> — 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:
<ul>
<li>SCREENDEF defines a global screen.</li>
<li>IMAGEDEF defines a global image.</li>
<li>PROCA sets the screen item value and an image item value.</li>
<li>PROCB displays the updated image item and the original screen item. </li>
</ul>
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:
<ul>
<li>GTBL size — [[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>VTBL usage with COMMON images and screens — [[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>User since-last statistics — [[Using system statistics#User since-last statistics|User since-last statistics]] </li>
</ul>

==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: 
<ul>
<li>CLEAR statement </li>
<li>CLEARG and/or CLEARGO commands</li>
<li>$DELG function to selectively delete global string variables</li>
<li>RESET command for the GTBLEHASH and GTBLPCT parameters</li>
<li>UTABLE command that changes the size of FTBL, XTBL, or GTBL clears all global objects of any type</li>
</ul>

===Using the CLEARG and CLEARGO commands===
<table>
<tr class="head">
<th>Use this command </th>
<th>To Remove...</th>
</tr>

<tr>
<td><var>[[CLEARG command|CLEARG]]</var> </td>
<td>Only global string variables. </td>
</tr>

<tr>
<td><var>[[CLEARGO command|CLEARGO]]</var></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>
</table>

The <var>CLEARGO</var> command takes no arguments.


===Using the $DELG function===

You can use the <var>[[$Delg]]</var> function to delete global string variables created by either <var>[[$Setg]]</var> or <var>[[$Incrg]]</var>. 

The <var>[[$Delg]]</var> 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 <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: 
<table>
<tr class="head">
<th>The statement </th>
<th>Clears...</th>
</tr>

<tr>
<td nowrap><var>Clear type-of-object 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>
</tr>

<tr>
<td><var>Clear Global</var> </td>
<td>Individual global objects from GTBL. </td>
</tr>

<tr>
<td><var>Clear Globals</var> </td>
<td>All global string variables. You cannot selectively clear individual global string variables with the <var>Clear</var> statement. </td>
</tr>
</table>

====Syntax====

The format for the <var>Clear</var> statement is:
{{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>Position [Perm | Temp]</var> The use of PERM or TEMP must be consistent with GLOBAL in the REMEMBER statement. If GLOBAL is specified in the REMEMBER statement, then PERM is implied. If GLOBAL is omitted from the REMEMBER statement, TEMP is implied.
</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>
NOTE: If the objectname is mixed case, be sure to use the same name, in single quotation marks, when referring to that name in other statements; e.g. REMEMBER or POSITION.

<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 not clear any global objects. </li>
</ul>

====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: 
<ul>
<li>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
</li>

<li>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 <var>CLEARGO</var> command.) </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>Issue a <var>UTABLE</var> command that changes the size of FTBL, XTBL, or GTBL. </li>
</ul>

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:

M204.0301 Referenced statement label undefined

M204.0311 Unacceptable statement reference


===RELEASE and COMMIT RELEASE statements with global foundsets and lists===

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.

===Clearing remembered positions===

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.

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:
<ul>
<li>You can clear a specific temporary position by issuing one of these statements:
Clear Global Position Temp 'objectname'

Clear Global Position Temp %variable
</li>

<li>You can clear a specific permanent position by issuing one of these statements:
Clear Global Position Perm 'objectname'

Clear Global Position Perm %variable
</li>

<li>You clear all global found sets, lists, or sorted sets with which a remembered position is associated:
Clear ListFdst [Global] Objects
</li>

<li>You clear all remembered positions by issuing the statement:
Clear Position [Global] Objects
</li>
</ul>

====Usage notes====
<ul>
<li>When you are using the <var>Clear Global Position</var> statement, <var>Perm</var> is the default. </li>

<li>The <var>CLEARGO</var> command has the effect of clearing all remembered positions.</li>

<li>Any <var>UTABLE</var> command that changes the size of FTBL, GTBL, or XTBL clears all remembered positions.</li>
</ul>

===Timing and placement of a Clear statement===

The <var>Clear Global</var> statement takes effect at evaluation time and its placement in a request can have significant consequences: 
<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>
</ul>

</div> 

[[Category:SOUL]]

SIRPRMPT parameter

2025-09-24T00:39:48Z

JDamon: /* Description */

{{Template:SIRPRMPT parameter subtitle}}
==Summary==
<dl>
<dt>Default value
<dd>X'00'
<dt>Parameter type
<dd>System
<dt>Where set
<dd>System manager resettable
<dt>Related products
<dd>All
<dt>Introduced
<dd>Before <var class="product">Sirius Mods</var> 6.7
</dl>

==Description==
This parameter is a bitmask parameter that affects the command mode prompt in an Online.
The meaning of the bits in <var>SIRPRMPT</var> are:
<dl>
<dt>X'01'
<dd>Add the [[JOBNM parameter|jobname]] (or the VM's user ID under CMS) to the command mode prompt.
This makes it easy to determine which Online one is connected to in command
mode, possibly averting accidents like someone typing <var>[[EOJ command|EOJ]]</var> in a production Online when she means to be terminating a test Online.

<dt>X'02'
<dd>Add the name of the [[STEPNM parameter|job step]] to the command mode prompt.
Note that if the X'01' bit is on, the X'02' bit is ignored.
The X'02' bit should not be used under CMS.

<dt>X'04'
<dd>When the <var>[[EOJ command|EOJ]]</var> command is issued from a full screen thread
<var>[[IODEV parameter|(IODEV=7,11 or 41)]]</var>, the user is prompted for the name of the Online (rather than for <code>Yes</code> or <code>No</code>) to confirm that the run is to be ended.

<var>[[CUSTOM parameter|CUSTOM=37]]</var> must also be set to use this value.


The X'04' setting was made available in version 7.5 of Model 204.
<dt>X'08'
<dd>When the <var>EOJ</var> command is issued from a line-at-a-time thread,
the user is prompted for the name of the Online (rather than for <code>Yes</code> or <code>No</code>) to confirm that the run is to be ended.

<var>[[CUSTOM parameter|CUSTOM=37]]</var> must also be set to use this value.


A line-at-a-time thread has one of the following <var>[[IODEV parameter|IODEV]]</var> values: 
<ul>
<li>29 or 39 (a [[BATCH2 (CRAM)#BATCH2|BATCH2]] thread), 37 (see Note), 45, or: </li>

<li>The value of the <var>[[SDAEMDEV parameter|SDAEMDEV]]</var> parameter (a [[Sdaemons|Daemon thread]]).</li>
</ul>

Note: The <var>[[IODEV parameter|IODEV=37]]</var> setting is no longer supported as of Model 204 version 7.6.

The X'08' setting was made available in version 7.5 of Model 204 and of the <var class="product">Sirius Mods</var>.
</dl>

[[Category:System parameters]]
[[Category:Parameters]]

SIRPRMPT parameter

2025-09-24T00:37:41Z

JDamon: /* Description */

{{Template:SIRPRMPT parameter subtitle}}
==Summary==
<dl>
<dt>Default value
<dd>X'00'
<dt>Parameter type
<dd>System
<dt>Where set
<dd>System manager resettable
<dt>Related products
<dd>All
<dt>Introduced
<dd>Before <var class="product">Sirius Mods</var> 6.7
</dl>

==Description==
This parameter is a bitmask parameter that affects the command mode prompt in an Online.
The meaning of the bits in <var>SIRPRMPT</var> are:
<dl>
<dt>X'01'
<dd>Add the [[JOBNM parameter|jobname]] (or the VM's user ID under CMS) to the command mode prompt.
This makes it easy to determine which Online one is connected to in command
mode, possibly averting accidents like someone typing <var>[[EOJ command|EOJ]]</var> in a production Online when she means to be terminating a test Online.

<dt>X'02'
<dd>Add the name of the [[STEPNM parameter|job step]] to the command mode prompt.
Note that if the X'01' bit is on, the X'02' bit is ignored.
The X'02' bit should not be used under CMS.

<dt>X'04'
<dd>When the <var>[[EOJ command|EOJ]]</var> command is issued from a full screen thread
(<var>[[IODEV parameter|IODEV=7,11 or 41]]</var>), the user is prompted for the name of the Online (rather than for <code>Yes</code> or <code>No</code>) to confirm that the run is to be ended.

<var>[[CUSTOM parameter|CUSTOM=37]]</var> must also be set to use this value.


The X'04' setting was made available in version 7.5 of Model 204.
<dt>X'08'
<dd>When the <var>EOJ</var> command is issued from a line-at-a-time thread,
the user is prompted for the name of the Online (rather than for <code>Yes</code> or <code>No</code>) to confirm that the run is to be ended.

<var>[[CUSTOM parameter|CUSTOM=37]]</var> must also be set to use this value.


A line-at-a-time thread has one of the following <var>[[IODEV parameter|IODEV]]</var> values: 
<ul>
<li>29 or 39 (a [[BATCH2 (CRAM)#BATCH2|BATCH2]] thread), 37 (see Note), 45, or: </li>

<li>The value of the <var>[[SDAEMDEV parameter|SDAEMDEV]]</var> parameter (a [[Sdaemons|Daemon thread]]).</li>
</ul>

Note: The <var>[[IODEV parameter|IODEV=37]]</var> setting is no longer supported as of Model 204 version 7.6.

The X'08' setting was made available in version 7.5 of Model 204 and of the <var class="product">Sirius Mods</var>.
</dl>

[[Category:System parameters]]
[[Category:Parameters]]

SIRPRMPT parameter

2025-09-24T00:27:52Z

JDamon: /* Description */

{{Template:SIRPRMPT parameter subtitle}}
==Summary==
<dl>
<dt>Default value
<dd>X'00'
<dt>Parameter type
<dd>System
<dt>Where set
<dd>System manager resettable
<dt>Related products
<dd>All
<dt>Introduced
<dd>Before <var class="product">Sirius Mods</var> 6.7
</dl>

==Description==
This parameter is a bitmask parameter that affects the command mode prompt in an Online.
The meaning of the bits in <var>SIRPRMPT</var> are:
<dl>
<dt>X'01'
<dd>Add the [[JOBNM parameter|jobname]] (or the VM's user ID under CMS) to the command mode prompt.
This makes it easy to determine which Online one is connected to in command
mode, possibly averting accidents like someone typing <var>[[EOJ command|EOJ]]</var> in a production Online when she means to be terminating a test Online.

<dt>X'02'
<dd>Add the name of the [[STEPNM parameter|job step]] to the command mode prompt.
Note that if the X'01' bit is on, the X'02' bit is ignored.
The X'02' bit should not be used under CMS.

<dt>X'04'
<dd>When the <var>[[EOJ command|EOJ]]</var> command is issued from a full screen thread
(<var>[[IODEV parameter|IODEV=7,11 or 41]]</var>), the user is prompted for the name of the Online (rather than for <code>Yes</code> or <code>No</code>) to confirm that the run is to be ended.

<var>[[CUSTOM parameter|CUSTOM=37]]</var> must also be set to use this value.


The X'04' setting was made available in version 7.5 of Model 204.
<dt>X'08'
<dd>When the <var>EOJ</var> command is issued from a line-at-a-time thread,
the user is prompted for the name of the Online (rather than for <code>Yes</code> or <code>No</code>) to confirm that the run is to be ended.

<var>[[CUSTOM parameter|CUSTOM=37]]</var> must also be set to use this value.


A line-at-a-time thread has one of the following <var>[[IODEV parameter|IODEV]]</var> values: 
<ul>
<li>29 or 39 (a [[BATCH2 (CRAM)#BATCH2|BATCH2]] thread), 37 (see Note), 45, or: </li>

<li>The value of the <var>[[SDAEMDEV parameter|SDAEMDEV]]</var> parameter (a [[Sdaemons|Daemon thread]]).</li>
</ul>

Note: The <code>IODEV=37</code> setting is no longer supported as of Model 204 version 7.6.

The X'08' setting was made available in version 7.5 of Model 204 and of the <var class="product">Sirius Mods</var>.
</dl>

[[Category:System parameters]]
[[Category:Parameters]]

M204.0583

2025-07-16T23:09:46Z

JDamon:

{{Template:M204.0583 skeleton}}

Example:

M204.0583: Waiting for exclusive access to file K100HILO M2Q999.ROCKET.K100HILO.M204

Where:
ENQTYPE=exclusive
VOLSER=M2Q999
DSN=ROCKET.K100HILO.M204


A batch Model 204 run is attempting to establish an exclusive enqueue on a Model 204 file, but another job already has an exclusive or share enqueue outstanding for the file. Model 204 retries the enqueue and waits for the
file to become available. This message is usually preceded by message [[M204.0582]]. Refer to that message for more information. 

Response: Notify your system manager if you suspect the run of Model 204 that had the enqueue has crashed. 

System manager response: The message indicates that a job is waiting for an enqueued file to become available, and is tying up system resources. You have the options of waiting for the enqueued file to be dequeued, closing the file in the job
which has the enqueue on the file, or holding the job until the required file is available. 

Operator response: Notify the system manager if there are multiple occurrences of this message. 
{{Template:M204.0583 footer}}

M204.0582

2025-07-11T21:43:02Z

JDamon:

{{Template:M204.0582 skeleton}}

Example:
 M204.0582: Access to file K100HILO M2Q999.ROCKET.K100HILO.M204 prevented by: QS99 EXCL PSBAT79C STEP01 25.192 11:27:47.79

Where:
VOLSER=M2Q999
DSN=ROCKET.K100HILO.M204
LPAR=QS99
enqueue type=EXCL
jobname stepname=PSBAT79C STEP01

A shared DASD enqueuing conflict occurred for the specified file. Another Model 204 run processing on a different CPU has established an enqueue against this file. This conflicts with the enqueue level you are attempting
to establish. That is, if you want a share enqueue, another run has an exclusive enqueue on the file; if you want an exclusive enqueue, another run already has either a share or an exclusive enqueue. If this message occurs in a batch Model 204 run,
Model  204 waits for five minutes and retries the enqueue. It continues to wait and retry until the enqueue succeeds. 

Model 204 maintains a Shared DASD Enqueue List for each file on the File Parameter List page, that is, on the first page of the file. Refer to [[Model 204 configurations and operating environments#Shared DASD and Global Resource Serialization|Shared DASD and Global Resource Serialization]] for more details about file enqueueing between multiple copies of Model 204. 

Response: Retry the request or command later or notify your system manager if you suspect that the job holding the enqueue has crashed. 

System manager response: There may be either a real enqueueing conflict or an obsolete shared DASD enqueue list due to a system crash. The job name specified in the message will assist you in determining the cause. Use the <var>[[ENQCTL command|ENQCTL]]</var> command to
correct obsolete shared DASD enqueue lists. This command should be used with extreme caution as its abuse can cause file integrity problems. 

Operator response: Notify the Model 204 system manager if there are multiple occurrences of this message. 

{{Template:M204.0582 footer}}

M204.0581

2025-07-11T21:40:31Z

JDamon:

{{Template:M204.0581 skeleton}}

Example:

M204.0581: Waiting for share access to file K100HILO M2Q999.ROCKET.K100HILO.M204

Where:
ENQTYPE=share
VOLSER=M2Q999
DSN=ROCKET.K100HILO.M204

A batch Model 204 run is attempting to establish a share enqueue on a Model 204 file, but another job already has an exclusive enqueue outstanding for the same file. Model 204 retries the enqueue and waits for the file to
become available. 
System manager response: The message indicates that a job is waiting for an enqueued file to become available, and is tying up system resources. You have the options of waiting for the enqueued file to be dequeued, closing the file in the job
which has the exclusive enqueue on the file, or holding the job until the required file is available. 
Operator response: Notify the system manager. 
{{Template:M204.0581 footer}}

M204.0582

2025-07-11T21:27:48Z

JDamon:

{{Template:M204.0582 skeleton}}

Example:
 M204.0582: Access to file K100HILO M2Q999.ROCKET.K100HILO.M204 prevented by: QS99 EXCL PSBAT79C STEP01 25.192 11:27:47.79

Where:
VOLSER=M2Q999
DSN=ROCKET.K100HILO.M204
LPAR=QS99
enqueue type=EXCL
jobname stepname=PSBAT79C STEP01


A shared DASD enqueuing conflict occurred for the specified file. Another Model 204 run processing on a different CPU has established an enqueue against this file. This conflicts with the enqueue level you are attempting
to establish. That is, if you want a share enqueue, another run has an exclusive enqueue on the file; if you want an exclusive enqueue, another run already has either a share or an exclusive enqueue. If this message occurs in a batch Model 204 run,
Model  204 waits for five minutes and retries the enqueue. It continues to wait and retry until the enqueue succeeds. 

Model 204 maintains a Shared DASD Enqueue List for each file on the File Parameter List page, that is, on the first page of the file. Refer to [[Model 204 configurations and operating environments#Shared DASD and Global Resource Serialization|Shared DASD and Global Resource Serialization]] for more details about file enqueueing between multiple copies of Model 204. 

Response: Retry the request or command later or notify your system manager if you suspect that the job holding the enqueue has crashed. 

System manager response: There may be either a real enqueueing conflict or an obsolete shared DASD enqueue list due to a system crash. The job name specified in the message will assist you in determining the cause. Use the <var>[[ENQCTL command|ENQCTL]]</var> command to
correct obsolete shared DASD enqueue lists. This command should be used with extreme caution as its abuse can cause file integrity problems. 

Operator response: Notify the Model 204 system manager if there are multiple occurrences of this message. 

{{Template:M204.0582 footer}}

System requirements for Application Subsystems

2025-06-06T21:15:26Z

JDamon: /* Subsystem Administration screen */

<div class="toclimit-3">
==Overview of CCASYS==

CCASYS is a system file used in conjunction with [[:Category:Dictionary/204|Dictionary/204]] and the [[Subsystem Management facility]] (SUBSYSMGMT). It contains the procedure names, file names, and parameters that create a [[Application Subsystem development|subsystem]] definition. When a subsystem is executed, <var class="product">Model 204</var> opens and reads the CCASYS file.

The CCASYS file must be open to use the Subsystem Management facility and to run any user-written subsystem.

Statistics associated with CCASYS processing are written to the CCAAUDIT system file and can be viewed from a terminal or printed to an audit trail.

This page describes CCASYS and explains how to create and maintain the file.

==Maintaining CCASYS==

===Creating CCASYS===

You can create CCASYS online as a separate file or as a part of the initial installation of Dictionary and the full-screen interface. Regardless of the approach used to create CCASYS, it must be available before Dictionary and the interface are installed. 

A user with system manager privileges can create CCASYS online (see the <var>[[CREATE command: File|CREATE]]</var> command).
The formula for calculating the size of CCASYS is given in the <var class="product">Model 204</var> installation guides.

To create CCASYS during Dictionary installation, follow the instructions given in [[Dictionary/204 installation guide]].

===Reorganizing CCASYS===

For instructions on reorganizing CCASYS and Dictionary files, refer to [[Dictionary/204 operation and file maintenance]].

==Using CCASYS==

You must be a system manager to run the Subsystem Management facility, as well as having privileges defined in the DICTIONARY to use SUBSYSMGMT. (Refer to the DICTADMIN subsystem to add privileges.)

To use the Subsystem Management facility and to run any user-written subsystem, the CCASYS file must be open. <var class="product">Model 204</var> opens CCASYS during initialization when the <var>[[SYSOPT parameter|SYSOPT]]</var> parameter setting includes the X'01' bit (see [[#JCL requirements|JCL requirements]] on this page).

CCASYS is opened and locked in share mode. During the process of defining a subsystem, the lock is changed to exclusive mode for the duration of the session. If more than one copy of <var class="product">Model 204</var> is using the same CCASYS file, the Subsystem Management facility cannot be entered. 

===Subsystems available at initialization===

If the CCASYS file is marked as full (the <var>[[FISTAT parameter|FISTAT]]</var> X'08' bit) during Online initialization, subsystems are now available and the following message is no longer issued:
M204.1457 UNABLE TO SCAN LIST OF SUBSYSTEM NAMES


===JCL requirements===

JCL requirements for CCASYS are:
<ul>
<li>Set the <var>SYSOPT</var> X'01' bit on in the JCL PARM field to enable CCASYS.

The <var>SYSOPT</var> X'01' bit automatically increments NFILES, NDCBS, and NDIR to allow use of the subsystems.

If the <var>SYSOPT</var> parameter is set to an even value, CCASYS is not opened by <var class="product">Model 204</var> and subsystems are unavailable.
You must set the <var>SYSOPT</var> X'01' bit on all nodes that the client subsystem accesses. (For Parallel Query Option/204)</li>

<li>Specify a CCASYS DD statement for running the subsystem. </li>
</ul>

===File security===

You can add additional file security to the security provided by user privileges in the CCASYS file by:
<ul>
<li>Resetting the <var>[[OPENCTL parameter|OPENCTL]]</var> parameter</li>

<li>Entering passwords for the CCASYS file entries in the password table (CCASTAT). See [[Storing security information (CCASTAT)#Using CCASTAT|Using CCASTAT]].</li>
</ul>

===Maintaining CCASYS===

Periodically back up CCASYS. Like other <var class="product">Model 204</var> files, CCASYS can participate in recovery and transaction back out processing. 

As necessary, include [[File reorganization and table compaction|reorganizations]] in the recovery scheme, such as increasing both Table A and Table C and, sometimes, to recover a file if it is not participating in other recovery options.


Set up backup and restore jobs to handle all files at once. If need be, you can set up a separate backup job for CCASYS to run with the files. See the Rocket <var class="product">Model 204</var> installation guide for your operating system.

===Recovering CCASYS===

If CCASYS is used in a run, you can recover it with a <var>[[RESTART command|RESTART]]</var> command without resetting the <var>SYSOPT</var> parameter.

Synchronize recovery of CCASYS and Dictionary files. Dictionary subsystems and the Subsystem Management facility must be stopped to perform file maintenance.

==Activating the APSY Precompiled Procedures in Storage feature==

z/OS sites can keep precompiled procedures in storage. By removing precompiled procedures from the disk buffer pool, the buffer pool pages are available for <var class="product">Model 204</var> files or non-APSY CCATEMP pages. This can reduce disk I/O for both CCATEMP and other <var class="product">Model 204</var> files. The <var>[[APSYPAGE parameter|APSYPAGE]]</var> parameter allows APSY saved compilations to be loaded without having the pages that the compilations are saved on move through the disk buffer pool. This represents a reduced load on page flushing and the HASH LOCK and reduced CPU usage.
Note: As of Model 204 7.5, it is recommended for performance reasons that customers who have been using the <var>APSYPAGE</var> parameter <var class="term">disable the APSYPAGE feature</var> by setting <var>APSYPAGE</var> to 0. Instead of <var>APSYPAGE</var>, use the <var>RESPAGE</var> parameter for [[#APSY precompiled procedures in storage above the bar|storage above the bar]]. 

To activate the APSY Precompiled Procedures in Storage feature in a job, users must set the <var>APSYPAGE</var> parameter in the User 0 CCAIN stream. The <var>APSYPAGE</var> parameter specifies the number of virtual storage pages to allocate.
Note: While <var>APSYPAGE</var> looks very much like <var>[[TEMPPAGE parameter|TEMPPAGE]]</var>, the units are somewhat different: 
<ul>
<li><var>APSYPAGE</var> refers to 4096-byte virtual storage pages</li>

<li><var>TEMPPAGE</var> refers to 6184-byte <var class="product">Model 204</var> file pages</li>
</ul>

There are several reasons to use the <var>APSYPAGE</var> parameter instead of, or in addition to, the <var>TEMPPAGE</var> parameter:
<ul>
<li><var>APSYPAGE</var> virtual storage pages do not have to be big enough to hold all of CCATEMP or even all saved compilations. The APSY Precompiled Procedures In Storage feature uses an LRU algorithm to ensure that frequently loaded APSY procedures remain in storage, while infrequently loaded procedures tend to be loaded from CCATEMP. So, if there is not sufficient real storage to back all of CCATEMP, you might set <var>APSYPAGE</var> to save frequently loaded APSY compilations in real storage. </li>

<li>The path length for retrieving a page out of storage is significantly lower than for retrieving one out of the disk buffer pool, especially in an MP/204 environment.</li>

<li>When <var>APSYPAGE</var> is set, the large <var class="product">Model 204</var> server tables are (hardware) page-aligned as are the saved compilations. This makes it possible to use the hardware MVPG (MoVe PaGe) facility to move pages into a server during an APSY load. On some processors, specialized hardware makes the facility significantly faster than byte-oriented data movement.</li>
</ul>

===Storage improvements for APSY subsystem saved precompilation===

If not otherwise set, <var>[[DSPOPT parameter|DSPOPT]]</var> defaults to X'00'. When a saved compilation page is moved to the <var>APSYPAGE</var> area, it is no longer also kept in CCATEMP, which eliminates duplicate storage. 

This is particularly useful when you keep CCATEMP in memory, using the <var>TEMPPAGE</var> parameter. This reduces in-memory CCATEMP storage requirements by approximately (<code>N/1.50</code>), where <code>N</code> is the number of 4K-byte pages of <var>APSYPAGE</var> that are used. In memory CCATEMP size is defined by the <var>TEMPPAGE</var> parameter.

Setting the <var>DSPOPT</var> X'80' bit and setting <var>TEMPPAGE</var> greater than zero causes saved compilations to be saved in both CCATEMP and <var>APSYPAGE</var>. Although this is wasteful of storage, it does not cause problems. If you set both parameters, you may see a higher use of CCATEMP in storage.

Setting <var>APSYPAGE</var> greater than zero causes APSY subsystem precompiled pages to be saved in storage. If <var>TEMPPAGE</var> is also set to 0, your CCATEMP is kept on disk and all saved compilations are stored in both locations. In-memory APSYPAGE storage can still be reduced if <var>DSPOPT</var> is set to include the X'80' bit. With both those settings, <var class="product">Model 204</var> employs the least recently used (LRU) algorithm to keep the more heavily used saved compilations in memory while the less recently used saved compilations migrate to disk.

===Storage requirements===

The CCASERVR, CCATEMP, and APSY Precompiled Procedures in Storage features may cause operating system paging. Performance degradation is likely, if real storage frames are insufficient, or expanded storage frames in hiperspaces are used to hold the data saved in this storage. The <var>[[MONITOR DATASPACE command|MONITOR DATASPACE]]</var> command can provide some information about the storage usage of these features. 

===Setting the DSPOPT parameter===

If the APSY precompiled procedures in storage feature is used, or CCASERVR In Storage is used with page-oriented data movement (<var>[[DSPOPT parameter|DSPOPT]]</var> X'01' set), then certain large server tables and servers themselves are page-aligned. This might require up to five extra hardware pages of real and virtual storage per server, although more typically it requires about three extra pages or 12K bytes per server. 

If <var>[[NSERVS parameter|NSERVS]]</var> is set to 40 and <var>APSYPAGE</var> is set to a nonzero value, or CCASERVR is kept in storage with <var>DSPOPT</var> X'01' set, enough real storage frames should be available to hold up to an extra 200 pages or 800K of server data. 

The setting of the <var>DSPOPT</var> parameter depends on your installation: 
<ul>
<li>If your site has enough expanded storage, you might use it for CCASERVR in Storage and APSY Precompiled Procedures in Storage in a cache hiperspace (<code>DSPOPT=X'43'</code>). </li>

<li>If this decision causes a large number of CCATEMP reads because z/OS steals a lot of pages from the cache hyperspace, then use <code>DSPOPT=X'23'</code> (no cache hyperspace). </li>

<li>If there is an excessive paging, eliminate one or both In Storage features. </li>

<li>If your installation is z/OS, 64-bit real-storage, do not use any hyperspaces options, but use dataspaces instead. </li>
</ul>

Users with limited resources should try and test for what feature is the most effective.

In addition, enough real storage should be available to hold the APSY precompiled procedures and/or CCASERVR data in real or expanded storage.

===APSY load statistics===

There are three system statistics associated with APSY loads. These statistics are intended to: 
<ul>
<li>Assist in the proper setting of the <var>APSYPAGE</var> and <var>RESLTHR</var> parameters.</li>

<li>Determine the ratio of requests using precompiled and non-precompiled requests, the percentage of requests which are precompiled being the ratio of APSYLD to REQ. </li>
</ul>

The APSY load statistics are:
<table>
<tr class="head">
<th>Statistic </th>
<th>Tracks the number of APSY loads...</th>
</tr>

<tr>
<td>APSYLD </td>
<td>Including internal CCASYS procedures that are run as part of APSY processing.</td>
</tr>

<tr>
<td>APSYLDD </td>
<td>From a dataspace.

This statistic is zero unless the APSYPAGE parameter is set. This parameter can be compared with APSYLD and APSYLDT to determine the percentage of eligible APSY loads that are being performed from a dataspace.</td>
</tr>

<tr>
<td>APSYLDT </td>
<td>That are tiny.

All APSY loads, even those done from dataspaces, read a certain amount of control information from CCATEMP. Immediately following this control information is data that is loaded into NTBL, QTBL, STBL, and VTBL. If this table data does not extend to an extra CCATEMP page beyond the control information, the APSY load is counted as a tiny load. 

This statistic is maintained because tiny APSY loads are not worth saving in dataspaces, so it must be considered when comparing APSYLDD with APSYLD in determining which percentage of pre-compiled procedures are being loaded from dataspaces.</td>
</tr>
</table>

===APSY precompiled procedures in storage above the bar===
You can store APSY precompiled procedures above the bar by using the <var>[[RESPAGE parameter|RESPAGE]]</var> parameter to specify a number of 4K operating system pages. See [[Defining_the_runtime_environment_(CCAIN)#ATB_storage_for_APSY_precompiled_procedures|ATB storage for APSY precompiled procedures]] for details.

==Parallel Query Option/204 and scattered subsystems==

Whenever you log in to a service subsystem, you must reset the <var>[[LGTBL parameter|LGTBL]]</var> parameter on the service thread to at least 288. This sets the size of the global variable table (GTBL). GTBL contains name/value strings for global variables and is used by procedures that are included by APSY to support subsystem processing. 

The subsystem designer will have to place the <var>UTABLE</var> command into the LOGIN procedure, if <var>LGTBL</var> is insufficient before entering the subsystem.

==Overview of the Subsystem Management facility==

The Subsystem Management facility (SUBSYSMGMT) is a full-screen <var class="product">Model 204</var> Dictionary interface. It is used as a tool to define user-written applications that run under the Application Subsystem facility (APSY). 

Subsystem characteristics and components are defined by means of a series of screens and stored in the CCASYS file. Data in the CCASYS file is used by the application subsystem to control the processing required by the subsystem. <var class="product">Model 204</var> Dictionary entries are maintained for the operational parameters, procedure specifications, and subsystem files. The Subsystem Management facility makes SOUL applications easier to use, easier to maintain, and more efficient. 

The following sections provide an overview of subsystem processing and explains how to use the SUBSYSMGMT interface to define a subsystem, establish user privileges, and migrate subsystem definitions from one <var class="product">Model 204</var> environment to another.

For more information on subsystems, requirements, and options, refer to: 
<ul>
<li>[[Dictionary/204 installation guide]] and [[Dictionary/204 operation and file maintenance]], which discuss the installation and preparation of CCASYS, D204SYS, and Dictionary files</li>

<li>[[Dictionary/204 entity type definitions#SUBSYSTEM|SUBSYSTEM]], which describes the dictionary entries relating to subsystems</li>

<li>[[PQO: Overview of Parallel Query Option/204]], which describes a <var class="product">Model 204</var> distributed processing facility</li>

<li>[[Application Subsystem development]], which gives detailed instructions for designing, developing, and debugging a subsystem</li>
</ul>

==Components of a subsystem==

A subsystem is an application consisting of a collection of procedures, files, and assigned characteristics that are defined as a subsystem to <var class="product">Model 204</var> through the <var class="product">Model 204</var> Dictionary interface, SUBSYSMGMT.

The collection of procedures that make up a subsystem perform system startup, login processing, main processing, disconnect processing, and error-handling tasks. 

Control is passed from procedure to procedure by setting a defined communications global variable in each procedure. The communications global variable contains the name of the next procedure to be executed. Detailed information about subsystem design and procedure development is given in [[Application Subsystem development]].

Assigned characteristics of a subsystem include security and system operation options, such as locking files and groups for subsystem use, automatic login and logout, automatic COMMIT for outstanding updates, message displays, and the response of the subsystem when files are unavailable.

The members of an APSY subsystem are files and permanent groups. With <var class="product">PQO</var>, members can be either automatic or manual: 
<ul>
<li>An automatic member is a subsystem group or file that is opened automatically when the subsystem is started or when a user enters the subsystem. </li>

<li>A manual member is a group or file that must be opened explicitly by the <var>OPEN</var> or <var>OPENC</var> command. </li>
</ul>

Members can also be either mandatory or optional:
<ul>
<li>A mandatory member must be open in order to access a subsystem. Mandatory members cannot be manual. </li>

<li>An optional member is not required for subsystem access (start and login processing can succeed without it). </li>
</ul>

At any given time, a member can be open or closed to a subsystem or to a user within a subsystem. The following sections explain the conditions under which the different kinds of members are accessible to APSY subsystems and their users.

==File and group availability==

===Member availability to APSY subsystems===

Automatic members of APSY subsystems are always opened by the <var>START SUBSYSTEM</var> command or by SUBSYSTEM LOGIN. At the end of <var>START</var> processing, each automatic member is open unless either the <var>START</var> or <var>OPEN</var> failed. 

Manual members of APSY subsystems are in the closed state at the completion of <var>START SUBSYSTEM</var> processing and must be explicitly opened by the user. Manual members become open to the subsystem if an OPEN operation succeeds. If <var>OPEN</var> fails due to node unavailability or for user-specific reasons (for example, if the user's line goes down), the member remains closed to the subsystem.
<ul>
<li>If a node becomes unavailable to a subsystem, all automatic subsystem members and all open manual subsystem members residing on the unavailable node are marked disabled.</li>

<li>If a <var>STOP FILE</var> (or <var>STOP GROUP</var>) command is issued for a manual member on the client subsystem's node, the member is closed to the client subsystem when the last user closes it. </li>

<li>If the member is located on the service subsystem node, the file is closed to the service subsystem when either the <var>STOP</var> is complete or the last user closes the file.</li>
</ul>

===Member availability to subsystem users===

When a user enters a subsystem, automatic subsystem members are opened.

If a user <var>LOGIN</var> or <var>OPEN</var> operation fails for an optional member, the member is left closed for the user but remains open to the subsystem. If a mandatory member cannot be opened, the user is denied access to the subsystem.

If a user <var>LOGIN</var> or <var>OPEN</var> operation fails for an already open member, the member is left disabled for the user, but remains open to the subsystem. 

If an automatic mandatory member is closed to the subsystem, new users are not allowed to enter the subsystem.

Manual members of APSY subsystems are closed for a user within a subsystem until the user issues an <var>OPEN</var> command or statement. In this case, it does not matter whether the member is open or closed to the subsystem.

If compilation and/or loading of a request fails due to a communications failure, previously opened members on the failing node become disabled to the user. A user can close optional members at any time by issuing the <var>CLOSE</var> command.

===Enabling a disabled subsystem file===

If a file is marked as disabled to the subsystem, you can use the <var>ENABLE SUBSYSTEM FILE</var> command to make the file available again. If necessary, correct any communications problem. Then enter this command:

ENABLE SUBSYSTEM subsysname [FILE | GROUP] name AT location

Where:
<ul>
<li><var class="term">subsysname </var>is the name of the client subsystem.</li>

<li><var class="term">name</var> specifies the file or group that supports <var class="term">subsysname</var>.</li>

<li><var class="term">location</var> is the value of the client CCAIN LOCATION parameter (which is also the value of the CLNT field in the <var>[[LOGWHO command|LOGWHO]]</var> command output).</li>
</ul>

You must specify the location; you cannot include local files in an <var>ENABLE SUBSYSTEM</var> command.

===Disabling a subsystem file===

You can disable a subsystem file to keep the file itself, or the subsystem to which it belongs, inaccessible for a short period of time, without shutting down the subsystem by using the <var>DISABLE SUBSYSTEM</var> command.

To disable a subsystem file, use this command:

DISABLE <var>SUBSYS</var>TEM subsysname [FILE | GROUP] name AT location

Where:
<ul>
<li><var class="term">subsysname </var>is the name of the client subsystem. </li>

<li><var class="term">name</var> specifies the file or group that supports <var class="term">subsysname</var>.</li>

<li><var class="term">location</var> is the value of the client CCAIN LOCATION parameter (which is also the value of the CLNT field in the <var>LOGWHO</var> command output).</li>
</ul>

The consequence of disabling a subsystem file depends on whether the file is an optional or mandatory group member: 
<ul>
<li>If you disable a mandatory file, you effectively disable the subsystem, because users attempting to access the disabled file cannot access the subsystem. </li>

<li>If you disable an optional file, users can log in to the subsystem, but cannot access the disabled file. </li>
</ul>

==Application subsystem processing==

Subsystem processing includes startup, login processing, locating, compiling and/or loading procedures (main or driver processing), disconnect processing, and error processing. User-written procedures are required for each processing step.

For startup and processing considerations specific to scattered subsystems, see [[PQO: Scattered APSY subsystems#Subsystem command processing|PQO subsystem command processing]]. 

===Subsystem startup===

To start the subsystem, either issue the <var>[[START command: Starting an application subsystem|START]]</var> command. Or, optionally, the first user starts the subsystem automatically, if the Auto Start option is in effect. During subsystem startup, <var class="product">Model 204</var> performs the following tasks:
<ol>
<li>Finds the subsystem definition stored in CCASYS.</li>
<li>Builds an in-core subsystem definition control block.

For z/OS operating systems, application subsystem control blocks reside above the 16-megabyte line.</li>

<li>Opens all required files and groups.</li>

<li>Scans the procedure file for locked members that have precompiled procedure prefixes (see [[#Procedure Specifications screen|Procedure Specifications screen]]).</li>

<li>Enters an entry for each precompiled procedure in the in-core procedure dictionary.
Note:
The maximum size of the in-core procedure dictionary is 16 megabytes.</li>

<li>Adds the subsystem name to the list of active subsystems, if no error occurs.</li>

<li>Performs a user-written initialization procedure (optional).</li>

<li>Closes all associated files and groups, unless the Auto Start option is in effect. </li>
</ol>

===Login processing===

Each time the subsystem is invoked, <var class="product">Model 204</var> automatically performs the following steps:
<ol>
<li>Searches CCASYS for the user's class definition that assigns user privileges.

The subsystem invocation is rejected if privileges consistent with the subsystem invoked are not found. </li>

<li>Logs the user in to <var class="product">Model 204</var> with the subsystem name as the user, account, and record security ID, if the automatic login option (see [[#Operational Parameters screen|Operational Parameters screen]]) is set in the subsystem definition.

If the automatic login option is not set, the user's <var class="product">Model 204</var> ID is retained.</li>

<li>Opens required subsystem files and groups with the found privileges.</li>

<li>Executes the commands and requests, as specified by the login procedure programmed by the user. The login procedure might consist of:
<ul>
<li>Storing current server table sizes in the global variable table for later reference</li>
<li>Issuing UTABLE commands to set compiler table sizes for subsystem use</li>
<li>Setting the communications global variable to the name of the procedure that displays the initial menu </li>
</ul></li>

<li>Begins main processing as long as the login procedure specifies the next procedure to include in the communications global variable. </li>
</ol>

===Main processing===

Main processing consists of locating subsystem eligible procedures, compiling procedures (if necessary), and loading procedures until an exit value is encountered. You can have as many main processing procedures as necessary. 

Procedure names are stored in the in-core procedure dictionary that is built during system startup. Procedures are retrieved by examining the communications global variable for the name of the procedure and then locating the procedure name in the in-core dictionary.

If the procedure name is not found, the subsystem error procedure is executed. If the procedure is not found and no error procedure is specified in the subsystem definition, the user is disconnected from the subsystem.

If the procedure name is found, <var class="product">Model 204</var> checks to see if the procedure has been precompiled:
<ul>
<li>If the procedure is not a precompilable procedure, <var class="product">Model 204</var> includes it for compilation and evaluation. Compilation and evaluation are reported in the audit trail under the CMPL and EVAL since-last statistics.</li>

<li>If the procedure is a precompilable procedure, <var class="product">Model 204</var> checks to see if the procedure was previously compiled with the set of privileges defined for the user's subsystem class.</li>

<li>If the procedure is precompiled for the user's privilege set, <var class="product">Model 204</var> loads the contents of the compiler tables from CCATEMP and evaluates the request. Loading and evaluation are reported in the audit trail as LOAD and EVAL since-last statistics.</li>

<li>If the procedure is not precompiled, <var class="product">Model 204</var> includes the procedure for compilation and evaluation. Contents of compiler tables are saved in CCATEMP, if the compile is successful and the tables are not already saved for another user class.</li>

<li>If the procedure is already precompiled for some other privilege set, <var class="product">Model 204</var> validates whether this user's privilege set is authorized to compile and validate. If successful, the request is loaded and then evaluated. If unsuccessful (for example, if the privilege set fails), the error procedure is executed.
</li>
</ul>

Main processing continues until the value of the communications global variable is set to the exit value specified in the subsystem definition. Once the exit value is set, <var class="product">Model 204</var> proceeds to disconnect processing.
Warning: Rocket advises that when using an <var>INCLUDE</var> statement in a precompiled procedure that the included procedure is the same for all users. Unpredictable results may occur if the procedure is different when compiling for different [[SCLASS]]es.

===Requirements for using temporary groups===

If a precompiled procedure includes an <var>OPEN</var> of a temporary group, an attempt to load that procedure fails (with the <code>GRP NOT OPEN</code> error) if the procedure contains an unreferenced list in the context of that group. An unreferenced list is a list that is declared but not referred to and, therefore, its declaration is not evaluated. 

To avoid an error in this situation, make sure of the following: 
<ul>
<li>Any temporary group in this situation must be open at the time of the load.</li>

<li>Such a temporary group must be a TBO group if the procedure accesses a TBO file for update.</li>
</ul>

===Disconnect processing===

Disconnect processing is invoked when one of the following conditions occurs: 
<ul>
<li>Communications global variable is set to the exit value.</li>

<li>Error occurs with no subsystem error procedure defined.</li>

<li>User is restarted by <var class="product">Model 204</var>.</li>

<li>Logout or disconnect commands are issued from a subsystem procedure. </li>
</ul>

All open subsystem files and groups are closed for the user during disconnect processing. If the subsystem definition includes the automatic logout option (Log User out of M204 on the Operational Parameters screen), the user is logged out of <var class="product">Model 204</var>.

If the subsystem definition includes the automatic login option (Log User in to M204) but not the automatic logout option (Log User out of M204), the user is exited out of the subsystem, logged in again under the original <var class="product">Model 204</var> ID (if previously logged in), and returned to <var class="product">Model 204</var> command level.

===Error processing===

Error processing, an optional procedure, is invoked when an error occurs that cannot be handled by the procedure executing at the time. 

====Recoverable errors====

A subsystem can recover from most errors when an error procedure is used. Recoverable errors include:
<ul>
<li>Compilation errors</li>

<li>Record locking or table-full errors</li>

<li>Attention interrupts and *CANCEL if no ON ATTENTION unit is specified in the application
</li>
</ul>

An error procedure must test for different error conditions. The resulting value stored in the error global variable helps the application programmer determine the type of error that occurred.

====Considerations for the communications global variable====

The communications global variable is ignored and disconnect processing completed when one of the following conditions occurs:
<ul>
<li>Error is a soft restart, a hard restart, or a phone hang-up condition.

If you attempt to set the communications global variable to the name of another procedure, the procedure is not executed.</li>

<li>No error procedure is specified in the subsystem definition. </li>
</ul>

==Subsystem operating requirements==

Meet the following requirements to define and execute a subsystem:
<ul>
<li>Install CCASYS, the <var class="product">Model 204</var> Dictionary, and the subsystem interface SUBSYSMGMT</li>

<li>Allocate sufficient space for subsystem use in the resource locking table, server tables, CCATEMP, and spare core (SPCORE) </li>
</ul>

===Required files===

Dictionary/204, with the files shown in the table below, must be installed to define a subsystem; see the [[Dictionary/204 installation guide]]. Dictionary entries pertaining to subsystems are for reference purposes only. The subsystem is executed by using the data stored in CCASYS.
<table>
<caption>Dictionary/204 files required for subsystem management</caption>
<tr class="head">
<th>File</th>
<th>Description</th>
</tr>

<tr>
<td>CCASYS</td>
<td>Subsystem definition</td>
</tr>

<tr>
<td>D204SYS</td>
<td>Migrating definitions</td>
</tr>

<tr>
<td>DATALINK</td>
<td>Dictionary file</td>
</tr>

<tr>
<td>M204PROC</td>
<td>Procedure file</td>
</tr>

<tr>
<td>M204TEMP</td>
<td>Internal work file</td>
</tr>

<tr>
<td>METADATA</td>
<td>Dictionary file</td>
</tr>
</table>

===Resource locking table space===

<var class="product">Model 204</var> locks in share mode on subsystem procedure names or permanent group names. Locking ensures that the procedures or group definitions do not change while the subsystem is running and prevents any user from issuing the <var>PROCEDURE</var>, <var>DELETE PROCEDURE</var>, or <var>RENAME PROCEDURE</var> commands. Procedures cannot be updated with the editor while the subsystem is active. 

Separate locks are not required if the subsystem definition specifies locked files during processing.

Additional space might be required in the resource-locking table for running a subsystem with groups defined or files unlocked. Use the following formula as a guide:
Number of additional resource-locking entries =
Number of groups + number of procedures (if files are unlocked)


where additional resources include:
<ul>
<li>Seven additional entries for application subsystem procedures in CCASYS</li>

<li>One additional entry for each subsystem and permanent group</li>

<li>One additional entry for each subsystem procedure if LOCK FILE (or GROUP) options are chosen </li>
</ul>

===Minimum server table sizes===

Minimum server table lengths, exclusive of any application procedures, for all users invoking subsystems are:
<ul>
<li>LGTBL = 288</li>

<li>LNTBL = 50</li>

<li>LQTBL = 120</li>

<li>LSTBL = 250</li>

<li>LVTBL = 256 </li>
</ul>

During application programming, you must determine actual table lengths for specific procedures. Make adjustments to table lengths in the login procedure to ensure successful execution.

===CCATEMP space===

CCATEMP requires additional space to accommodate the compiler tables for precompiled procedures. The data stored in CCATEMP consists of a header section and the contents of GTBL, NTBL, QTBL, STBL, and VTBL.

Use the following calculation to determine the additional CCATEMP space required for one precompiled request:
94 + (32 * VTBL HWM) + (12 * NTBL HWM) + (STBL HWM)
+ NFILES + NRMTFILE + (16 * QTBL HWM)
+ (ad hoc group FTBL space)
+ ((30 + (7 + NRMTLOCS)/8) * #groups)
+ (8 * (#fields referenced in group))
+ (the sum of the length of the names of all the fields referenced in the group)
+ #screens + #images
+ (unavailable-file space) + (XVAR space)


where: 
<ul>
<li><code>HWM</code> refers to the highwater mark found in the audit trail's since-last compilation statistic for the indicated table.</li>

<li><code>ad hoc group FTBL space</code> depends on whether ad hoc scattered groups (PQO) are included. If no ad hoc groups are scattered, ad hoc group FTBL space is:
62 * (#ad hoc groups)


If some ad hoc groups are scattered, ad hoc group FTBL space is:
(62 + (#open files in ad hoc groups)) * (#ad hoc groups)
</li>

<li><code>unavailable-file space</code> is the following quantity, not knowable in advance, which you need to estimate (PQO only):
(4 + (#unavailable group files)) * (#groups with unavailable members)
</li>

<li><code>XVAR space</code> is required for these SOUL request elements: found sets, lists, and <var>FOR</var> statements with a <var>WHERE</var> clause. The number of bytes per element depends on the file or group context, as follows:
<table>
<tr class="head">
<th>Transaction context </th>
<th>Bytes required per element</th>
</tr>

<tr>
<td>Single file</td>
<td align="right">8</td>
</tr>

<tr>
<td>Ad hoc or permanent group</td>
<td>8 * (#files in group) </td>
</tr>

<tr>
<td>Temporary group</td>
<td>4 + (8 * (#files in group))</td>
</tr>
</table>
</li>
</ul>

The number of additional CCATEMP pages required is:
The result of the above calculation / (PAGESZ - 40)


===SPCORE size===

Control blocks are allocated from spare core for use by active subsystems. Use the following calculation to determine the number of bytes required for one subsystem. The calculation includes PQO remote file subsystem members:
228 + NRMTFILE + NFILES + (40 * SCLASSes) + NRMTLOCS
+ (93 * filemembers)
+ ((36 + (7 + SCLASSes) / 8) * (procedures + 1))
+ 40 bytes for each stopped file or group


Where: 
<ul>
<li><var>NRMTFILE</var> and <var>NRMTLOCS</var> are CCAIN parameters that apply to Parallel Query Option/204.</li>

<li><code>filemembers</code> are the files that belong to the subsystem. </li>

<li><code>SCLASSes</code> is the number of subsystem user privilege classes.</li>

<li><code>procedures</code> is the number of precompiled procedures used by the subsystem.
</li>

<li><code>40 bytes for each stopped file or group</code> is the number of bytes returned to spare core if the subsystem is stopped or the file or group is started.</li>
</ul>

==Subsystem operating options==

Subsystem operating options consist of commands entered on the command line, the <var>[[AUTOSYS parameter|AUTOSYS]]</var> parameter entered on user lines in CCAIN, and values entered on screens provided by the Application Subsystem. Options can be entered on the command line only if the subsystem is already started or if the subsystem is defined with the Auto Start option. A summary of the available options is given in the following table.

More detailed information about the operating options follows the table.
Options entered through interface screens are discussed throughout this article.
<table>
<caption>Summary of subsystem operating options</caption>
<tr class="head">
<th>Option</th>
<th>Method of entry</th>
<th>Purpose</th>
</tr>

<tr>
<td>Auto Commit</td>
<td nowrap>Operational Parm screen</td>
<td>Controls automatic <var>COMMIT</var>s at the <var>END</var> of each procedure</td>
</tr>

<tr>
<td>Auto Start</td>
<td>Operational Parm screen</td>
<td>Automatically starts the subsystem when the first user logs in</td>
</tr>

<tr>
<td>Automatic Login (Log user in...) </td>
<td>Operational Parm screen</td>
<td>Logs the user in to the subsystem with an account value of the subsystem name</td>
</tr>

<tr>
<td>Automatic Logout (Log user out...)</td>
<td>Operational Parm screen</td>
<td>Controls user logout from <var class="product">Model 204</var></td>
</tr>

<tr>
<td>AUTOSYS</td>
<td>CCAIN user line</td>
<td>Invokes the specified subsystem for individual users upon <var class="product">Model 204</var> login</td>
</tr>

<tr>
<td colspan="3">Commands</td>
</tr>

<tr>
<td>DEBUG SUBSYSTEM</td>
<td>Command line</td>
<td>Allows the user issuing the command to change subsystem procedures without stopping and restarting the subsystem</td>
</tr>

<tr>
<td nowrap>DISABLE SUBSYSTEM FILE</td>
<td>Command line</td>
<td>Makes a file or subsystem temporarily inaccessible</td>
</tr>

<tr>
<td>ENABLE SUBSYSTEM FILE </td>
<td>Command line</td>
<td>Makes a file available again after being disabled</td>
</tr>

<tr>
<td>START FILE</td>
<td>Command line</td>
<td>Allows a file to be opened and removes the stop flag (if any)</td>
</tr>

<tr>
<td>START SUBSYSTEM</td>
<td>Command line</td>
<td>Activates the subsystem, opens files, and performs subsystem startup</td>
</tr>

<tr>
<td>STOP FILE</td>
<td>Command line</td>
<td>Prevents opening a specified file or permanent group</td>
</tr>

<tr>
<td>STOP SUBSYSTEM</td>
<td>Command line</td>
<td>Stops the subsystem</td>
</tr>

<tr>
<td>TEST</td>
<td>Command line</td>
<td>Creates a single user test environment</td>
</tr>

<tr>
<td>File/Group</td>
<td>Command line</td>
<td>Specifies the name and attributes of
files and groups used by the subsystem</td>
</tr>

<tr>
<td colspan="3">Global variables</td>
</tr>

<tr>
<td>Communication</td>
<td>Procedure Spec screen</td>
<td>Specifies the variable name of the next procedure to be executed</td>
</tr>

<tr>
<td>Exit Value</td>
<td>Procedure Spec screen</td>
<td>Specifies the communication variable setting for exiting the subsystem</td>
</tr>

<tr>
<td>Error Variable</td>
<td>Procedure Spec screen</td>
<td>Names the variable containing the error code</td>
</tr>

<tr>
<td>Iterations</td>
<td>Operational Parm screen</td>
<td>Specifies the maximum number of times a procedure can execute consecutively</td>
</tr>

<tr>
<td>Lock File/Groups</td>
<td>Operational Parm screen</td>
<td>Controls outside user access to subsystem files when the subsystem is active</td>
</tr>

<tr>
<td colspan="3">Message display</td>
</tr>

<tr>
<td>Disconnect</td>
<td>Operational Parm screen</td>
<td>Controls disconnect message display</td>
</tr>

<tr>
<td>Informational</td>
<td>Operational Parm screen</td>
<td>Controls the display of informational messages</td>
</tr>

<tr>
<td>Error</td>
<td>Operational Parm screen</td>
<td>Controls error message display</td>
</tr>

<tr>
<td>Numlk</td>
<td>File Use screen</td>
<td>Specifies the number of files participating in procedure locking </td>
</tr>

<tr>
<td colspan="3">Proc names </td>
</tr>

<tr>
<td>Initialization</td>
<td>Procedure Spec screen</td>
<td>Names the first procedure used upon subsystem startup</td>
</tr>

<tr>
<td>Login</td>
<td>Procedure Spec screen</td>
<td>Names the first procedure executed for each user</td>
</tr>

<tr>
<td>Error</td>
<td>Procedure Spec screen</td>
<td>Names the procedure invoked when an error occurs
</td>
</tr>

<tr>
<td colspan="3">Proc prefixes</td>
</tr>

<tr>
<td>Non-precompiled </td>
<td>Procedure Spec screen</td>
<td>Identifies the prefix used for procedures compiled each time they are invoked</td>
</tr>

<tr>
<td>Precompiled</td>
<td>Procedure Spec screen</td>
<td>Identifies the prefix used for procedures that are saved in CCATEMP for reuse</td>
</tr>

<tr>
<td>Procs</td>
<td>File Use screen</td>
<td>Names the file or group containing the subsystem procedures </td>
</tr>

<tr>
<td colspan="3">Security</td>
</tr>

<tr>
<td>Account</td>
<td>Operational Parm screen</td>
<td>Specifies an account value that overrides the login account</td>
</tr>

<tr>
<td>Account</td>
<td>Subsys Class screen</td>
<td>Specifies an account associated with a specific user class (overrides the account specified on the Operational Parameters screen)</td>
</tr>

<tr>
<td>Account</td>
<td>User Matrix screen</td>
<td>Changes an account in any subsystem user class</td>
</tr>

<tr>
<td>Command Priv.</td>
<td>Subsys Class screen </td>
<td>Specifies whether the class of users can issue the START, TEST, STOP, and DEBUG subsystem commands</td>
</tr>

<tr>
<td>File Priv.</td>
<td>Subsys Class screen </td>
<td>Specifies values for procedure, file, and field-level security parameters</td>
</tr>

<tr>
<td>Login Priv.</td>
<td>Subsys Class screen </td>
<td>Overrides privileges on entry to the subsystem and privileges specified on the Operational Parameters screen</td>
</tr>

<tr>
<td>Privileges</td>
<td>Operational Parm screen</td>
<td>Specifies user privileges independent of the <var class="product">Model 204</var> login privileges</td>
</tr>

<tr>
<td>Record Security</td>
<td>Subsys Class screen </td>
<td>Overrides the record security ID held upon entry into the subsystem</td>
</tr>

<tr>
<td>Start Login</td>
<td>Operational Parm screen</td>
<td>Controls login privileges while starting a subsystem</td>
</tr>

<tr>
<td>Status</td>
<td>Operational Parm screen</td>
<td>Specifies the level of availability of the subsystem to users</td>
</tr>

<tr>
<td>Sys Class</td>
<td>Subsys Class screen</td>
<td>Specifies the number and name of a subsystem user class that is assigned specific privileges</td>
</tr>

<tr>
<td>Subsys Class</td>
<td>Subsys Class Users screen</td>
<td>Specifies subsystem class changes for individual users</td>
</tr>

<tr>
<td>Subsys Class</td>
<td>Userdef screen</td>
<td>Identifies a group of subsystem users and specifies the command privilege level applicable to that group</td>
</tr>
</table>

===Subsystem commands===

The following list summarizes commands relating to a subsystem.

<ul>
<li><var>[[DEBUG command|DEBUG SUBSYSTEM]]</var> allows login to a specified subsystem with the <var>DEBUG</var> and <var>STATS</var> options of the <var>[[TEST command|TEST]]</var> command. Individual programmer changes to subsystem procedures can be made without stopping and restarting the subsystem. Changes are limited to the programmer issuing the <var>DEBUG SUBSYSTEM</var> command. More than one user can execute the <var>DEBUG</var> command against the same subsystem at the same time.

<var>DEBUG SUBSYSTEM</var> displays the value of the communications global variable and since-last statistics. Prompts are issued for changes to the variable.

<var>DEBUG</var> is limited to users with either <var>TEST</var> or <var>DEBUG</var> privileges. The <var>DEBUG</var> privilege does not entitle use of the <var>TEST</var> command.</li>

<li><var>[[DISABLE command|DISABLE SUBSYSTEM FILE]]</var> makes a file or the subsystem to which it belongs inaccessible for a short period of time without shutting down the subsystem by using the <var>STOP SUBSYSTEM</var> command. </li>

<li><var>[[ENABLE command|ENABLE SUBSYSTEM FILE]]</var> makes a file marked as disabled to the subsystem available again.</li>

<li><var>START FILE</var> removes the <var>OPEN</var> restriction set by the <var>STOP</var> command at the system and subsystem levels. </li>

<li><var>[[START command: Starting an application subsystem|START SUBSYSTEM]]</var> activates the subsystem and makes it available for use. <var class="product">Model 204</var> opens all the files and performs subsystem startup. </li>

<li><var>[[STOP command: Making a file or group unavailable|STOP FILE]]</var> prevents the reopening of a specified file or permanent group. Files or groups open at the time <var>STOP FILE</var> is issued are not affected until they are closed and an attempt is made to reopen them.

When the stopped file is closed by all users, all precompiled code in CCATEMP that refers to the file is discarded and pages in the temporary file are reclaimed. <var>STOP FILE</var> affects only one copy of <var class="product">Model 204</var>. Another copy of <var class="product">Model 204</var> can process the file or group. 

<var>STOP FILE</var> verifies the presence of the named file or group in any active subsystem. Files or groups not required by the subsystem become unavailable for future use.</li>

<li><var>[[STOP command: Stopping an application subsystem|STOP SUBSYSTEM]]</var> stops the subsystem and makes it unavailable for use. Files and groups are closed. Groups and procedures are released when the subsystem is completely stopped.

If <var>STOP SUBSYSTEM</var> is issued when there are active users, the system remains active until the last user disconnects (drain state).</li>

<li><var>TEST</var> creates a single user test environment. The subsystem must be stopped to enter the TEST mode and the user must have <var>TEST</var> privileges. <var>DEBUG</var> privileges are not sufficient to execute the <var>TEST</var> command.

<var>TEST</var> without the <var>DEBUG</var> option simulates execution of the subsystem. 
</li>
</ul>

===AUTOSYS parameter===

The <var>[[AUTOSYS parameter|AUTOSYS]]</var> parameter, specified on user lines in CCAIN, invokes a subsystem for individual users upon login to <var class="product">Model 204</var>. The same subsystem is generated for each subsequent user line until a different subsystem name is specified, or <var>AUTOSYS</var> is set to <code>C' '.</code> 

In the following example, all IUCV users enter the subsystem VMCFPROF whenever they log in. The AUTOSYS parameter is turned off for all other users.
IODEV=41,POLLNO=1,NOTERM=50,AUTOSYS=C'VMCFPROF'
IODEV=41,POLLNO=2
IODEV=41,POLLNO=3
.
.
.
IODEV=43,AUTOSYS=C' '
IODEV=43
IODEV=43



==Overview of the SUBSYSMGMT interface==

SUBSYSMGMT is the full-screen interface used to define user-written applications that run under the Application Subsystem facility. In addition to accessing from command line the TN3270 interface described below on this page, SUBSYSMGMT is accessible both from the [[RKTools#mainmenu|RKTools main menu]] and from the [[RKWeb#Manage|RKWeb]] browser GUI as of RKTools version 7.7. 

To issue a command from the SUBSYSMGMT screens, press the assigned PF key or enter the command on the command line (<code>===></code>). Abbreviations for commands are indicated by the uppercase portion of the command listed for PF keys. The following table describes common commands and PF keys for SUBSYSMGMT screens: 
<table>
<caption>Commands common to SUBSYSMGMT screens</caption>
<tr class="head">
<th>Command</th>
<th>PF key</th>
<th>Purpose</th>
</tr>

<tr>
<td>HELP</td>
<td>F1</td>
<td>Displays online Help text for the screen.</td>
</tr>

<tr>
<td>QUIT</td>
<td>F3</td>
<td>Terminates processing without saving screen input. QUIT returns to the previous level.</td>
</tr>

<tr>
<td>END</td>
<td>F12</td>
<td>Saves input and returns to the previous level.</td>
</tr>

<tr>
<td> </td>
<td>F11</td>
<td>Generally used to move to the next screen when adding, modifying, or browsing a subsystem. The command name depends upon the name of the screen. </td>
</tr>
</table>

Error messages are issued from all screens. Messages can be general and issued from any screen, or specific and issued from a particular screen. 

===SUBSYSMGMT facility screen summary===

The following table summarizes the SUBSYSMGMT facility screens. The screens are described in detail in the sections that follow. 
<table>
<caption>SUBSYSMGMT facility screens</caption>
<tr class="head">
<th>Screen </th>
<th>Purpose</th>
</tr>

<tr>
<td style="border-right:none">Primary screen</td>
<td style="border-left:none"> </td>
</tr>

<tr>
<td>Activity</td>
<td>Provides a menu from which to select subsystem definition activities</td>
</tr>

<tr>
<td style="border-right:none">Secondary screens</td>
<td style="border-left:none"> </td>
</tr>

<tr>
<td>Command Privileges</td>
<td>Changes the command privileges for a set of subsystems</td>
</tr>

<tr>
<td>Operational Parameters</td>
<td>Defines the subsystem operating parameters</td>
</tr>

<tr>
<td>Procedure Specifications</td>
<td>Defines subsystem procedure specifications</td>
</tr>

<tr>
<td>Subsystem File Use</td>
<td>Defines file names used by the subsystem</td>
</tr>

<tr>
<td>Subsystem Classes</td>
<td>Defines command and file privileges for each class of subsystem user</td>
</tr>

<tr>
<td>User Definitions</td>
<td>Defines the users of the subsystem when used in conjunction with the Subsystem Class User screen </td>
</tr>

<tr>
<td>Subsystem Class Users</td>
<td>Defines assignments of specific user accounts to specific user classes</td>
</tr>

<tr>
<td>User Matrix</td>
<td>Changes the definition of a single account in a user class</td>
</tr>

<tr>
<td nowrap>Subsystem Administration</td>
<td>Defines user and administrative privileges</td>
</tr>

<tr>
<td>Subsystem Trust</td>
<td>(PQO only) Views or manages trusted subsystem definitions</td>
</tr>
</table>

===Using secondary screens===

The following considerations apply to all secondary screens:
<ul>
<li>Use secondary screens in any order.</li>

<li>Use PF keys to move from screen to screen.</li>

<li>You must fill in all screens, except those for public and semi-public subsystems with only one class, to complete a subsystem definition.</li>

<li>Public and semi-public subsystems with only one class do not require the use of the User Definitions (Userdef) screen.</li>

<li>The END command (F12) stops and saves the definition when it is complete. If you use the END command with an incomplete definition, you receive a warning message. Issuing a second END command allows you to exit and you can complete the definition in another session. (Do not use an incompletely defined subsystem.) </li>
</ul>

===Sample screens and PQO===

For screens that have changed since the previous release, the sample screens shown in the following sections represent definitions for a client subsystem in a PQO application. 

PQO-specific fields are explained briefly but their use is not described in detail. Not shown here is the Subsystem Trust screen, which is specific to PQO.

For full explanations of client and server definitions in PQO applications, see [[PQO: Defining a PQO network]].

==SUBSYSMGMT Activity screen==

The Activity screen is the primary SUBSYSMGMT screen. Use it to access all SUBSYSMGMT functions.

Subsystem Activity screen
[[File:sm8-2Activity.gif|575px]] 

===Commands and options===

The F2, F4, F5, F6, F7, or F9 keys are used with Add, Modify, or Browse to specify the appropriate secondary screen. F10 invokes the PQO-specific Subsystem Trust screen. The EXPortlist option (F11) is described below in the [[#Exportlist|Exportlist]] section.

===Overview of activities===

The following options are initiated from the Activity screen and completed through the selected secondary screens:
<ul>
<li>Add a new subsystem definition</li>

<li>Modify an existing subsystem definition</li>

<li>Browse without updating an existing subsystem definition </li>
</ul>

The following options are initiated and completed from the Activity screen:
<ul>
<li>Copy an existing subsystem definition to a newly named subsystem definition</li>

<li>Rename an existing subsystem with a new, unique name</li>

<li>Delete an entire existing subsystem definition</li>

<li>Import subsystem definitions</li>

<li>Export subsystem definitions</li>

<li>Export Delete a subsystem from the D204SYS file</li>
</ul>

The ADMIN option (option 10) displays secondary screens on which the system manager can define privileges and assign and copy [[SCLASS]] membership. 

===From fields (PQO only)===

The From fields (used when defining a PQO service subsystem) specify the location of the client subsystem. If you specify a From field, you cannot leave the Subsystem Name field blank. 

The From field is prefilled on all the secondary screens and protected from input.

===Revising command privileges===

You can revise command privileges, if you have privileges to use the SUBSYSMGMT facility as well as the privileges to update the individual subsystems.

Using the main screen of the SUBSYSMGMT facility you can enter a pattern in the Subsystem Name field and select the F7 key to change the command privileges for a set of subsystems. Another screen appears where you can enter a pattern for a subsystem class along with the new command privileges for the <var>START</var>, <var>STOP</var>, <var>TEST</var>, <var>DEBUG</var>, <var>RESUME</var>, <var>SUSPEND</var>, <var>REFRESH</var> commands. You can also obtain a list of all of the subsystem classes and subsystem definitions that fit the pattern criteria.

To update the command privileges, select the 2. MODIFY option on the main menu, enter a subsystem name or pattern in the Subsystem Name field, and press F7. The COMMAND PRIVILEGES screen is displayed next. However:
<ul>
<li>If you enter a pattern in the name field, but press another function key, the pattern is treated as an individual name, not a pattern. F7 is only valid with the MODIFY option. </li>

<li>If F7 is pressed, but the MODIFY option was not specified, then the following error message is displayed:
SUMnnn: PFkey or command only valid with Modify option.
</li>

<li>If Subsystem Name is left blank, the following error message is displayed:
SUMnnn: Subsystem name or pattern is required.
</li>
</ul>

==SUBSYSMGMT Command Privileges screen==

The subsystem management command privileges screen is shown below:

Subsystem COMMAND PRIVILEGES screen
[[File:sm8-3CmdPriv.gif|532px]] 


After your screen entries are read, a list of subsystem names and subsystem classes based on the pattern criteria is displayed. The pattern criteria used for the subsystem name is the value that was specified on the main screen. The pattern criteria for the subsystem class defaults to asterisk (<tt>*</tt>) when the screen is initially read.

If any of the subsystems in the list are enqueued by other users then the command privileges for the subsystem cannot be updated. In this case, 6=DISplay appears on the screen to display the list of subsystems that are enqueued.

Choosing other classes or names

To refine the list of subsystem classes or subsystem names, enter a new pattern in the Subsystem Name or Subsystem Class field, and press F4 to view the new list.

The maximum number of subsystem classes that may be processed at one time is 1000. If the list exceeds 1000, then the following error message is displayed:
SUM096: Refine criteria: # of subsystems classes, exceeds max(1000).


===Entering changes in the COMMAND PRIVILEGES screen===

To update the command privileges for a particular subsystem class, the command privilege must be set to <code>Y</code> or <code>N</code> in one or more of the subsystem command privilege fields. In addition, the subsystem class must be selected by putting an <code>X</code> in front of the subsystem name and the class name. You can also update more than one subsystem class at a time by specifying a command privilege of one of the Change all selected columns. If the subsystem name and class are not selected, the command privileges are not updated for that particular subsystem class. 

At this point, you press F11 (UPDate priv or F12 (END) to update the command privileges for the entire set of selected subsystem classes. If a record enqueuing conflict occurs during the update process, only a partial update can be performed. If this occurs, you can press F6 (DISplay) to display the list of subsystem classes that are enqueued and cannot be updated at this time. You also can press F11 (UPDate) or F12 (END) a second time to apply the partial update, or press F3 (QUIt) to not apply the update.

Command privileges are in effect immediately after they are updated and can be changed if the subsystem is active or not.

You may also deselect particular subsystems or classes on the list by deleting the <code>X</code> that precedes the subsystem or class name. 

The following table displays the list of PF key options and commands that are alternatives that accomplish the same thing. (Commands are used with the Enter key.) Each PF key function can also be performed by adding 12 to that PF key's number and using the resulting PF key. Commands shown may be abbreviated to the first three characters, which are capitalized.

<table>
<caption>PF keys</caption>

<tr class="head">
<th>PF Key </th>
<th>Command</th>
<th>Purpose</th>
</tr>

<tr>
<td align="right">1 </td>
<td>HELp</td>
<td>Display Help information on this screen</td>
</tr>

<tr>
<td align="right">3 </td>
<td>QUIt</td>
<td>Exit from Command Privileges Screen, return to main menu for SUBSYSMGMT.</td>
</tr>

<tr>
<td align="right">4 </td>
<td>LISt</td>
<td>Displays a list of subsystems and classes based on the pattern specification in the Subsystem name and Class fields.</td>
</tr>

<tr>
<td align="right">5 </td>
<td nowrap>DESelect all 
SELect all</td>
<td>De-select all subsystem names on the list. 
Select all subsystem names on the list.

Toggles between DESelect and SELect. 
</td>
</tr>

<tr>
<td align="right">6 </td>
<td>DISplay</td>
<td>Displays a list of subsystems or classes that are enqueued by another user. The command privileges for the subsystems and classes on the list cannot be updated at this time.</td>
</tr>

<tr>
<td align="right">7 </td>
<td>BACkward</td>
<td>Scroll up on subsystem names list.</td>
</tr>

<tr>
<td align="right">8 </td>
<td>FORward</td>
<td>Scroll down on subsystem names list.</td>
</tr>

<tr>
<td align="right">11</td>
<td>UPDate</td>
<td>Update all subsystem classes with new command privilege. Only the command privileges that are changed are updated.</td>
</tr>

<tr>
<td align="right">12</td>
<td>END</td>
<td>Return to the main menu after updating the command privileges that are specified. If a particular command privilege is left blank then it is not updated.</td>
</tr>
</table>

Command privileges can be changed regardless of whether a subsystem is active or not. The new privileges are in effect immediately once they are changed.

==Operational Parameters screen==

Selecting F4 from the Activity screen brings up the Operational Parameters screen. Use it to specify the operating parameters of the subsystem. You access the [[RKWeb#Operational|RKWeb version of this screen]] by selecting <code>Manage > Subsystem Management > Operational</code>. 

On this screen, only system managers can modify Account, Privileges, and Start Login privileges fields.

Operational Parameters screen
[[File:Sm8-4OperParm.gif|561px]] 

===Commands===
<ul>
<li>F2, F6, F9 and F11 validate and save input and display other secondary screens. You must use a PF key to quit, save the input, or move to a different screen.</li>

<li>Pressing the Enter key validates screen input.</li>
</ul>

A description of each parameter follows.

===Parameter descriptions===
<ul>
<li>Status (1, 2, and 3) determines access availability:
<ul>
<li>PUBLIC (default) allows any user to access the subsystem.</li>

<li>SEMI-PUBLIC allows all users to access the subsystem, but permits different privileges for each class of users.

A semi-public subsystem generally has more than one user class. One class is designated as the default (see the [[#Subsystem Classes screen|Subsystem Classes screen]]).</li>

<li>PRIVATE requires all users to have an assigned class. No default is allowed.</li>
</ul></li>

<li>Auto Start automatically starts the subsystem when the first user enters the subsystem name. The <var>START</var> command is not required.

If <code>N</code> (the default) is specified, only a user having the appropriate privileges, as defined on the Subsystem Classes screen, can issue the <var>START</var> command to open the subsystem. 
</li>

<li>Lock File/Groups provides control for file access to users outside the subsystem.

If <code>Y</code> is specified, the subsystem files and groups are available only to users running in the subsystem after the subsystem is started.

A subsystem file can be opened by a non-subsystem user if the subsystem is not started. If any user has the file open when the subsystem is being started, the subsystem start fails.

If a group is defined, all member files of the group are locked. No explicit lock is held on the group.

If <code>N</code> (default) is specified, users outside the subsystem can open any subsystem file, but cannot <var>DELETE</var>, <var>RENAME</var>, or <var>REDEFINE</var> fields. </li>

<li>Log user into M204 controls the method of logging the user in to <var class="product">Model 204</var>.

If <code>Y</code> is specified, the user is logged out of <var class="product">Model 204</var> and then logged back in to <var class="product">Model 204</var> with the subsystem name as the user ID when entering the system.

If <code>N</code> (default) is specified, the user remains logged in under the same <var class="product">Model 204</var> account name used before subsystem processing. 
</li>

<li>Log user out of M204 controls the method of logging the user out of <var class="product">Model 204</var>.

If <code>Y</code> is specified, the user is logged out of <var class="product">Model 204</var> upon leaving the subsystem. 

If <code>N</code> (default) is specified and Log user into M204 is <code>Y</code>, the user's logon, account, and record security ID are restored to the values that were present before entering the subsystem.
</li>

<li>Auto Commit controls the issuing of <var>COMMIT</var> statements:
<ul>
<li>If <code>Y</code> (default) is specified, a SOUL <var>COMMIT</var> statement is executed by <var class="product">Model 204</var> at each procedure <var>END</var> in the subsystem during execution.</li>

<li>If <code>N</code> is specified, transactions can span request boundaries (see [[System and media recovery#Transaction boundaries|Transaction boundaries]]). The application must issue <var>COMMIT</var> statements to commit updates to the database. </li>
</ul></li>

<li>Maximum Iterations specifies the maximum number of consecutive times the subsystem allows the same procedure to be invoked before interrupting the processing. Valid values are 1 to 99999. <code>NULL</code> (default) indicates no limit. </li>

<li>Account (optional) specifies an account value other than that used at logon. As many as 10 characters can be entered. <code>NULL</code> can be used to specify the logon account value.

The original value is restored when the user exits the subsystem.</li>

<li>Privileges (in HEX) (optional) specifies a user's privileges while in the subsystem. Privileges specified before logging into the subsystem are overridden, regardless of the value of the Log user into M204 field. The original value is restored when the user exits the subsystem.

The privilege option is expressed as a hexadecimal value within the range of X'00' to X'FF', as described in [[Establishing and maintaining security#File security|File security]]. 
</li>

<li>Start Login Privileges (in HEX) specifies user login privileges for use while running the subsystem initialization procedure. If specified, Start Login Privileges in (HEX) overrides both the user's previous privileges and other privilege fields in the subsystem definition.

In the case of automatic login, the starting user's privileges are reset to those set on the Operational Parameters or Subsystem Classes screens prior to continuing execution within the subsystem. 

The privilege option is expressed as a hexadecimal value within the range of X'00' to X'FF', as described in [[Establishing and maintaining security#File security|File security]]. <code>NULL</code> indicates that other privilege specifications are not to be overridden. 
</li>

<li>Subsystem can access Remote Files pertains to PQO applications. <code>N</code> is the default. Change the value to <code>Y</code>, if you want the subsystem to access remote files. </li>
</ul>

===Message display options===

At the bottom of the screen are the message display options: 
<ul>
<li>Disconnect controls the display of subsystem disconnect messages:
<ul>
<li>If you specify <code>Y</code> (default), the subsystem disconnect message is displayed.</li>

<li>If you specify <code>N</code>, the subsystem disconnect message is suppressed.</li>
</ul></li>

<li>Informational controls the display of informational messages:
<ul>
<li>If you specify <code>Y</code> (default), <var class="product">Model 204</var> informational messages are displayed. </li>

<li>If you specify <code>N</code>, <var class="product">Model 204</var> informational messages are suppressed on the user's terminal and only subsystem messages are displayed. <var class="product">Model 204</var> messages continue to be printed on the audit trail.</li>
</ul></li>

<li>Error controls the display of error messages on the user's terminal.</li>

<li>If you specify <code>Y</code> (default), <var class="product">Model 204</var> error messages are displayed.</li>

<li>If you specify <code>N</code>, error messages are suppressed, but are still printed on the audit trail. </li>
</ul>

==Procedure Specifications screen==

Enter specifications for subsystem procedures on the Procedure Specifications screen. You access the [[RKWeb#Procedure|RKWeb version of this screen]] by selecting <code>Manage > Subsystem Management > Procedure</code>.

Procedure Specifications screen
[[File:Sm8-5Procedure.gif|564px]] 

===Commands===
<ul>
<li>F4, F6, F9, and F11 each validate, save the input, and provide the next secondary screen selection.</li>

<li>You must use a PF key to quit, save input, or move to a different screen.</li>

<li>Pressing Enter validates the screen.</li>
</ul>

===Procedure prefixes===

The PROCEDURE PREFIXES option requires each procedure used in a subsystem to have a prefix or be included in a procedure with a prefix. 

Subsystem procedures can contain <var class="product">Model 204</var> commands, requests, continued requests, or sections of SOUL code in any combination. A procedure containing commands cannot be precompiled. Procedures included in a precompiled procedure are also precompiled.
<ul>
<li>Non-precompiled specifies a prefix that identifies procedures that are compiled each time they are invoked.</li>

<li>Precompiled specifies a prefix that identifies precompiled procedures, which are included in the in-core dictionary for reuse. Precompiled procedures save CPU and elapsed time. </li>
</ul>

===Procedure names===

PROCEDURE NAMES require assigned prefixes that indicate if the procedure is or is not precompiled:
<ul>
<li>Initialization (optional) is the procedure invoked once when the subsystem is first started. </li>

<li>Login (required) is the name of the first procedure executed for every user.

<var class="product">Model 204</var> automatically includes a subsystem login procedure when a user enters a subsystem. This procedure must issue <var>UTABLE</var> commands to set compiler table sizes. 

Control must be passed to an initial main menu screen if the subsystem is an Online application. 
</li>

<li>Error (optional) is the name of the procedure invoked if an error occurs during execution of a subsystem, or if an attention interrupt occurs when no <var>ON ATTENTION</var> unit is active.

If no error procedure is supplied, <var class="product">Model 204</var> disconnects the user from the subsystem when an error occurs. </li>
</ul>

===Global variables===

GLOBAL VARIABLES enable you to pass information from one request to another and conditionally include procedures at the <var class="product">Model 204</var> command level: 
<ul>
<li>Command Line Variable specifies the name of an optional global variable containing parameter input that you can enter upon logon. The command line can contain up to 255 characters.

When a user logs in to a subsystem by entering the subsystem name followed by a number of parameters, the parameter input is placed into a global variable that is available to the subsystem procedures. If not defined, the command line is discarded.

Command line variables are not destroyed when control is transferred to another subsystem through the subsystem transfer (XFER) facility. </li>

<li>Communications variable (required) passes control from one procedure to the next. Each procedure sets the communications variable to the name of the next procedure executed in the subsystem.

You can transfer control from one procedure to another by using a user-designated global variable.

You can transfer control between subsystems by using the reserved global variable <code>XFER</code>. For more details about transferring control, see [[Application Subsystem development#Transferring control|Transferring control]].

When the application is ready to terminate, a subsystem procedure must set the communications global to the exit value.
</li>

<li>Exit Value (required) specifies the setting of the communications variable for exiting the subsystem.</li>

<li>Error Variable (required) specifies the variable in which an error code is stored. The value of the error variable, which is used by the error procedure, indicates the type of error. </li>
</ul>

==Subsystem File Use screen==

The Subsystem File Use screen defines the files, including the procedure file used by the subsystem. You access the [[RKWeb#Files|RKWeb version of this screen]] by selecting <code>Manage > Subsystem Management > Files</code>.

Subsystem File Use screen
[[File:Sm8-6FileUse.gif|537px]] 


It is useful to define a subsystem procedure file as a multiple-file procedure group. This will let you modify procedures in the group members without stopping the subsystem because of the following interactions of subsystems and procedure groups: 
<ul>
<li>All members of a procedure group are searched for subsystem procedures. The search, determined by the order in which the files were specified in the <var>[[CREATE command: Permanent group|CREATE]]</var> command that defined the group, begins with the leftmost specified member and proceeds to the right.

<li>The NUMLK parameter, on the Subsystem File Use screen, lets you determine how many and which members of a procedure group are locked (a member in which procedures cannot be modified). The locked members
are the Procs NUMLK number of consecutive members beginning with the rightmost member of the group and counting to the left. </li>

<li>You can add new procedures to any member of a procedure file group, but only procedures added to unlocked members are visible to the subsystem without restarting the subsystem.</li>
</ul>

A consequence of the above-listed factors is that you can
copy a procedure from a locked member to a (further-to-the-left) unlocked member designated for this purpose, modify that procedure copy, then let future APSY <var>INCLUDE</var> commands use that copy instead of the version in the locked member.

For example, the search for procedures in the group defined by the following <var>CREATE</var> command always starts with the leftmost file, <code>TESTPROC</code>, and proceeds to the right:
CREATE PERM GROUP PROCGRUP FROM TESTPROC, DEVPROC, QAPROC1, QAPROC2, PROD1, PRODPROC
PARAMETER PROCFILE=*
END CREATE


If the Subsystem File Use screen value of NUMLK is 3, procedures (with names starting with the pre-compiled prefix) in the three consecutive files beginning with the rightmost file, <code>PRODPROC</code>, are locked and cannot be modified
while their subsystem is active. But a procedure that is a member of <code>PROD1</code>, for example, can be copied, modified, added to <code>TESTPROC</code> and then included in the subsystem while it is still running.

For more information about the <var>PROCFILE</var> option, see its description in the <var>[[CREATE command: Temporary group#Temporary group parameters|CREATE TEMP GROUP]]</var> command.

Note: Procedures found in unlocked members are always recompiled on each include, imposing a significant performance penalty. That performance penalty can be eliminated by setting the <var>[[SIRAPSYF parameter|SIRAPSYF]]</var> parameter to X'03'. 

The in-core procedure dictionary is built during initialization by searching the locked members of a procedure file group for procedures with the precompiled prefix. If a subsystem procedure is present in more than one locked member of the procedure group, only the first procedure located in a left-to-right search of the locked members is included in the in-core procedure dictionary.


For further information, see also: 
<ul>
<li>[[Application Subsystem development#Permanent vs. temporary groups in subsystem definitions|Substituting a temporary group for the permanent group defined to the subsystem]]</li>

<li>Defining a multiple procedure file to the <var>[[$LstProc]]</var> function </li>

<li>[[Application Subsystem development#Guidelines and restrictions|Restrictions on using certain commands with multiple procedure files]] </li>
</ul>
Note: Non-system managers can add files to a subsystem if they have been assigned modify privileges (see [[#Administrative Privileges screen|Administrative Privileges screen]]).

===Commands===
<ul>
<li>F4, F5, F9, and F11 each validate, save the input, and provide the next secondary screen selection.</li>

<li>You must use a PF key to quit, save input, or move to a different screen.</li>

<li>F7 and F8 provide scrolling to and from the first to last Subsystem File Use screen when more than one is used. Input is validated before the screen scrolls.</li>

<li>Pressing Enter validates the screen.</li>

<li>You must issue the <code>TOP</code>, <code>BOTTOM</code>, and <code>MAXIMUM</code> commands on the command line. These commands have no corresponding PF keys.
<ul>
<li><code>TOP</code> scrolls to the first file.</li>

<li><code>BOTTOM</code> and <code>MAXIMUM</code> scroll to the last file.</li>

<li><code>MAXIMUM</code> used with F7 and F8 is equivalent to <code>TOP</code> and <code>BOTTOM</code>, respectively.</li>
</ul></li>
</ul>

===File specifications===
<ul>
<li>You must specify file or group names in the column labeled File/Group Name.

When using a group procedure file, the name specified must correspond to the permanent group. Note that an individual user can create or open a temporary group having the same name as the permanent group defined to the subsystem. If the temporary group is open before login to the subsystem, the subsystem uses the temporary group instead of the defined permanent group.

The following restrictions apply to the use of temporary groups as application subsystem procedure files:
<ul>
<li>TEST or DEBUG privilege is required.</li>

<li>The last files of the permanent group must correspond exactly to the last files of the temporary group. The number of files used in both groups is specified on the NUMLK parameter. </li>
</ul></li>

<li>File Location (PQO only) specifies the location of each file. If this field is omitted, the file is assumed to be local. Specify location only for client subsystems.</li>

<li>Group Y/N indicates whether or not the data file is a group. The default is <code>N</code>.</li>

<li>Auto Y/N indicates automatic members (opened automatically at subsystem startup). </li>

<li>Mandatory Y/N indicates mandatory members (which must be open to access the subsystem).</li>

<li>Procs specifies the name of the procedure file or group for the subsystem. You can use up to eight characters for each entry.

NUMLK specifies the number of files in a group that participate in procedure locking. Valid values are between 0 and 255, but must be less than the number of files in the group. 

If Group is <code>N</code>, the value of NUMLK must be <code>NULL</code>. If Group is <code>Y</code>, NUMLK must be given a value. </li>

<li>Deferred Name specifies an optional deferred update data set that can be a z/OS ddname, a z/VSE DLBL name, or a CMS FILEDEF name. If a deferred name is specified, the file is opened in deferred update mode when the subsystem is started. </li>

<li>Ordered-Index Deferred Name specifies an optional Ordered Index deferred update data set that can be a z/OS ddname, a z/VSE DLBL name, or a CMS FILEDEF name. If an ordered-index deferred name is specified, the file is opened in deferred update mode when the subsystem is started. </li>
</ul>

==Subsystem Classes screen==

Define command and file privileges for each class of subsystem users on the Subsystem Classes screen. You access the [[RKWeb#System_Classes|RKWeb version of this screen]] by selecting <code>Manage > Subsystem Management > System Classes</code>. 

Each class of user requires a separate screen. User class privileges defined to the subsystem override settings for <var>OPENCTL</var> and file privileges that reside in the password table.

Only the system manager can update the Logon Privilege, Record Security ID, and Account fields.

Subsystem Classes screen
[[File:Sm8-7SysClass.gif|559px]] 

===Commands===
<ul>
<li>F2, F4, F5, and F9 each validate, save the input, and provide the next secondary screen selection.</li>

<li>Use a PF key to quit, save input, or move to a different screen.</li>

<li>F6 displays current <var>PRIVDEF</var> parameter settings and lists options, described in [[#<Security specifications|Security specifications]], below.</li>

<li>F7 and F8 provide backward and forward scrolling when the list of files or groups exceeds one page. Input is validated before the screen scrolls.</li>

<li>F10 returns to the previous subsystem class. Input is validated and saved before moving to a different class.</li>

<li>F11 moves to the next subsystem class. Input is validated and saved before moving to a different class.</li>

<li>Pressing Enter validates the screen.</li>

<li>You must issue the TOP, BOTTOM, and MAXIMUM commands on the command line. These commands have no corresponding PF keys:
<ul>
<li><code>TOP</code> scrolls to the first file in this class.</li>

<li><code>BOTTOM</code> scrolls to the last file in this class.</li>

<li><code>MAXIMUM</code> used with F7 or F8 is equivalent to <code>TOP</code> or <code>BOTTOM</code>.</li>
</ul></li>
</ul>

===Subsystem name and class===
<ul>
<li>Subsystem Name specifies the name of the subsystem affected by the definitions entered on the screen.
</li>

<li>Subsystem Class is a system-assigned numeric identifier that specifies the user class being defined. As each new class is added, numeric identifiers are increased by an increment of 1.

In a semi-public subsystem, the first class is automatically assigned the class name <code>DEFAULT</code>, which you can change.
</li>
</ul>

===Security specifications===
<ul>
<li>Command Privileges determines if the user class (SCLASS) can issue the subsystem commands <var>START</var>, <var>TEST</var>, <var>STOP</var>, and <var>DEBUG</var>. The command fields take <code>Y</code> or <code>N</code>, and the default for all fields is <code>N</code>.

Debug specifies entering the subsystem in <var>DEBUG</var> mode. </li>

<li>Login Privilege (optional) specifies the user class login privileges for all, some, or none of the subsystem user classes.

Any individual user login privilege held at entry to the subsystem or specified on the Operational Parameters screen is overridden. The original value is restored when the user exits the subsystem.

The privilege option is expressed as a hexadecimal value within the range of X'00' to X'FF', as described in [[Establishing and maintaining security#PRIVDEF parameter settings|PRIVDEF parameter settings]]. 

<code>NULL</code> indicates default privileges from the Operational Parameters screen. </li>

<li>Record Security ID (optional) overrides any individual user record security ID held on entry to the subsystem. You can enter a maximum of eight characters.

<code>NULL</code> indicates the security activated on login.

The original value of the record security ID is restored when the user exits the subsystem. 
</li>

<li>Account (optional) specifies an account associated with specific user classes. Account can be specified for all, some, or none of the user classes. You can enter as many as ten characters.

Any individual value of Account held at entry to the subsystem or specified on the Operational Parameters screen is overridden. The original value is restored when the user exits the subsystem.

<code>NULL</code> indicates the user's login account or the value from the Operational Parameters screen.
</li>

<li>File/Group specifies files or groups that can be accessed by the defined class of users.

Define the set of files or groups belonging to the subsystem on the File Use screen and display them on this screen. </li>

<li>Location (PQO only) refers to the node where a file is located. </li>

<li>Prcldef specifies <var class="product">Model 204</var> procedure security. Values must be between 0 (default) and 255:
<ul>
<li>0 specifies no procedure security.</li>

<li>255 specifies the highest security. </li>
</ul></li>

<li>Privdef specifies file privileges. Values are hexadecimal 0 to X'BFFF' (default). </li>

<li>Sellvl, Readvl, Updtvl, and Addvl specify values for field-level security parameters. Values must be between 0 (default) and 255:
<ul>
<li>0 specifies all users can access field values.</li>

<li>255 restricts access of field values to users having certain privileges.</li>
</ul></li>

<li>PR specifies the name of the procedure file or group for the subsystem.</li>
</ul>

==User Definitions screen==

List user classes on the User Definitions (USErdef) screen for updating or browsing class definitions. You access the [[RKWeb#Operational|RKWeb version of this screen]] by selecting <code>Manage > Subsystem Management > Operational</code>. 

User Definitions screen
[[File:Sm8-8UserDef.gif|562px]] 

===Commands===
<ul>
<li>F2, F4, F5, and F6 display the next secondary screen.</li>

<li>F7 and F8 allow scrolling backward and forward for listing next or previous subsystem classes.</li>

<li>Pressing Enter displays the Subsystem Class Users screen for the class selected.</li>

<li>You must issue the TOP, BOTTOM, and MAXIMUM commands on the command line. These commands have no corresponding PF keys:
<ul>
<li><code>TOP</code> scrolls to the first class.</li>

<li><code>BOTTOM</code> scrolls to the last class.</li>

<li><code>MAXIMUM</code> used with F7 and F8, is equivalent to <code>TOP</code> and <code>BOTTOM</code>, respectively.</li>
</ul></li>
</ul>

===Screen specifications===
<ul>
<li>Subsystem Name specifies the applicable subsystem.</li>

<li>Subsystem Classes displays a listing, by class number and name, of the user classes defined on the Subsystem Classes screens.</li>

<li>ENTER SUBSYSTEM CLASS NUMBER accepts the number of the Subsystem Class whose user list is to be browsed/updated.</li>
</ul>

==Subsystem Class Users screen==

Define user accounts assigned to a specific class on the Subsystem Class Users screen. You access the [[RKWeb#classUsers|RKWeb version of this screen]] by selecting <code>Manage > Subsystem Management > Users</code>. 

A user can belong to only one class within a subsystem. If using more than one subsystem, the user can belong to a different class (different privileges) in each subsystem. 

Subsystem Class Users screen
[[File:Sm8-9SysClassUser.gif|531px]] 


Duplicate account entries result in the display of the class in which the original name resides.

Users can be added to a class, deleted, or replaced by entering, deleting, or typing over the individual <var class="product">Model 204</var> user account identification after the
prompt (<tt>></tt>). 

===Copy SCLASS option===

The Copy from Sclass options allow you to copy user IDs from an SCLASS already defined in one subsystem to the current SCLASS being defined. This option is not available in the RKWeb interface.

====PF keys====

The SCLASS copy options are represented by four PF key functions on the Subsystem Class Users screen: 
<ul>
<li>F4 (DELusers) deletes all users from a particular SCLASS selected from the User Definitions Screen. To execute this command, press F4. A warning message appears with the name of the SCLASS from which users are about to be deleted. Reenter the command if you are sure that you want to perform the Delete.</li>

<li>F5 (PREview) displays a list of all duplicate user IDs common to the copy-from SCLASS and any of the SCLASSes in the copy-to subsystem. The list is displayed on a separate screen, as shown in the [[#Sample Preview screen|Sample Preview screen]] section, below.</li>

<li>F10 (COPyusers) copies user IDs from the SCLASS specified in the copy-from field to the SCLASS selected from the User Definitions screen. This SCLASS is displayed on the current screen as a protected field.

When duplicate user IDs exist in another SCLASS in the copy-to subsystem, a warning message indicates that duplicates have not been copied. As with F4, reenter the command to perform the copy.
</li>

<li>F11 (CPReplace) copies user IDs as COPyusers does, but replaces duplicate user IDs. When duplicates exist, a warning message indicates that duplicates are moved from existing SCLASSes. Reenter the command to perform the copy with replacement.</li>

<li>Other PF keys function as in other secondary screens.</li>
</ul>

===Sample Preview screen===

The following screen is an example of the screen that appears when you execute the PREview command (F5) on the Subsystem Class Users screen:

Preview Duplicate USERIDS screen
[[File:8-10Preview.gif|493px]] 


This screen is purely informational. Press F3 to return to the Subsystem Class Users screen.

==Subsystem Import/Export options==

The Import and Export functions allow an authorized user to migrate subsystem definitions from one <var class="product">Model 204</var> environment to another via the migration file D204SYS, a <var class="product">Model 204</var> file created during Dictionary installation.

The Export Delete function deletes a specified subsystem from the D204SYS file. EXPortlist displays the list of subsystems that currently reside in D204SYS for which the user has <var>ALL</var> privileges (otherwise the user is not authorized to export them).

The four Import/Export options are all accessible from the Activity screen, shown earlier in [[#SUBSYSMGMT Activity screen|SUBSYSMGMT Activity screen]]. Import, Export, and Export Delete are options 7, 8, and 9, respectively. You can display an Exportlist by pressing F11, Export.

===Export===

The Export option allows authorized users to export subsystem definitions to another <var class="product">Model 204</var> Dictionary. To export a subsystem definition:
<ol>
<li>Select option 8 from the Activity screen.</li>

<li>Specify the subsystem to be exported.</li>

<li>To export SCLASS users, change the default value <code>N</code> to <code>Y</code> on the Export Users line.</li>

<li>Press Enter.</li>
</ol>

A message appears at the bottom of the screen indicating whether the Export has been successful. If the subsystem has already been exported by another user, then you cannot export it until it is deleted from D204SYS (see [[#Export Delete|Export Delete]]). 

===Import===

To import subsystem definitions, you must enter SUBSYSMGMT in the Dictionary to which the definition is to be imported. If the subsystem already exists, you must delete or rename it before importing. To import a subsystem definition:
<ol>
<li>Select option 7 from the primary menu.</li>
<li>Specify the subsystem to be imported</li>
<li>Press Enter.</li>
</ol>

A message appears at the bottom of the screen indicating whether the Import was successful. After an Import, the subsystem definitions remain in D204SYS until they are deleted.

===Export Delete===

To delete a subsystem from D204SYS:
<ol>
<li>Select option 9 from the primary menu</li>
<li>Specify the subsystem to be deleted from D204SYS</li>
<li>Press Enter.</li>
</ol>

===Exportlist===

To display the subsystems in D204SYS for which you have ALL privileges, press F11. The list displayed shows the name of each subsystem, the date and time of export, and the exporting user ID. 

===Exportable data: scope and limitations===

The Import/Export functions export all information in METADATA and DATALINK except for STAGED entities and user-defined links to the subsystem.

After an import, the LAST UPDATED field for a METADATA entry is changed to the date of import, and the UPDATED-BY field is changed to the importer's user ID. 

User SCLASSes can be imported (see [[#Export|Export]]); but administrative privileges cannot be imported.

==Subsystem Administration screen==

The Subsystem Administration screen appears when the system manager selects option 10 (ADMIN) on the SUBSYSMGMT primary menu. This option is available only to a system manager. 

Subsystem Administration screen
[[File:Sm8-12Admin.gif|513px]] 


Select Usage privileges by entering <code>U</code> on the space provided (<code>U</code> is the default). These privileges correspond exactly to the User Activity privileges in previous releases of <var class="product">Model 204</var>. Selecting <code>U</code> brings up the User Matrix screen described in [[#User Matrix screen|User Matrix screen]].

Select Administrative privileges for a User Account by entering <code>A</code>. The four Admin options are explained in the following section, [[#Admin options|Admin options]].

When setting privileges for specific users, remember that access to SUBSYSMGMT must be authorized via the DICTADMIN facility, as it is for every <var class="product">Model 204</var> Dictionary subsystem. However, if the [[APSYSEC parameter]]=1, that authorization is not required for users who are system managers. System managers are automatically authorized to use the SUBSYSMGMT and DICTADMIN facilities.


===Admin options===

The Subsystem Administration screen offers four options, described in the following sections.

====1. Define Privileges====

The Define Privileges option lets the system manager grant administrative privileges to specific users for specific subsystems. Selecting this option brings up the [[#Administrative Privileges screen|Administrative Privileges screen]]. To execute Define Privileges, enter <code>1</code> at the selection number prompt, specify the user ID to be assigned privileges in the User Account field, and press Enter.

====2. Copy====

The Copy option duplicates a user's administrative privileges to another user ID. To execute Copy, enter <code>2</code> at the selection number prompt, specify the user ID to be copied in the User Account field, specify the name of the user ID to be copied to in the Copy/Rename field, and press Enter. 

====3. Rename====

The Rename option changes a user ID associated with a given set of administrative privileges. To execute Rename, enter <code>3</code> at the selection number prompt, specify the user ID to be renamed in the User Account field, specify the new name in the Copy/Rename field, and press Enter. 

====4. Delete====

The Delete option takes away all administrative privileges associated with a specific user ID. To execute Delete, enter <code>4</code> at the selection number prompt, specify the user ID in the User Account field, and press Enter.

===Subsystem pattern field===

The Subsystem pattern field applies to all options in both Usage and Admin modes. You can leave it blank, enter a single subsystem name, or enter a pattern: 
<ul>
<li>If you leave this field blank, the next screen displays all subsystems. </li>

<li>If you select a pattern following the [[Record retrievals#Pattern matching|standard pattern specifications]],
the found set of subsystems are displayed on the next screen — the User Matrix screen, if in Usage mode; the Administrative Privileges screen, if in Admin mode.</li>
</ul>

==Administrative Privileges screen==

The Define Privileges option selected in Admin mode displays the Administrative Privileges screen. To create or delete privileges, type or space over <code>X</code>s in the appropriate spaces. 
Note:
Take care when granting All and Modify privileges. A user with these privileges can update subsystem file use data.

Administrative Privileges screen
[[File:Sm8-13AdminPriv.gif|535px]] 

===Hierarchy of privileges===

The ALL SUBSYS row on this screen grants the account the selected privileges for all subsystems: All, Modify, Browse, Udef.

If both ALL SUBSYS and specific subsystem privileges are granted, the higher privilege takes precedence. 

For Import, Add, and Copy privileges, a user must also be a member of the ADDPRIV SCLASS, described in [[#ADDPRIV SCLASS and Add Privileges|ADDPRIV SCLASS and Add Privileges]].

===PF keys===
<ul>
<li>F1 (HELp) displays Help text for the screen.</li>

<li>F2 (TOP) scrolls to the top of the display.</li>

<li>F3 (QUIt) returns the user to the Admin Screen without saving changes. Before exiting, warning messages are displayed indicating that changes have not been saved.</li>

<li>F5 (LOCate) locates a specified subsystem on the display list. Specify the name on the command line before pressing F5. If the subsystem name is found, it is highlighted and displayed at the top of the list. If it is not found, the display is unchanged.</li>

<li>F7 (BACkward) scrolls backward through the list of subsystems specified. A maximum of ten subsystems are displayed on the screen at once. </li>

<li>F8 (FORward) scrolls forward through the list of subsystems specified. </li>

<li>F12 (END) saves all screen changes and returns the user to the Admin Screen.</li>

<li>The Enter key has no effect on this screen.</li>
</ul>

===ADDPRIV SCLASS and Add Privileges===

To give a user Add, Copy, or Import privileges, the system manager must add the appropriate user ID to a new SCLASS called ADDPRIV. Do this as shown in [[#User Matrix screen|User Matrix screen]], or in [[#User Definitions screen|User Definitions screen]].

==Summary of subsystem privileges==

The "Summary of subsystem privileges" table shows how the system of assigned privileges relates to the ten functions displayed on the [[#SUBSYSMGMT Activity screen|Subsystem Management Facility screen]]. The columns are privileges granted, including general system manager privileges. The rows are SUBSYSMGMT functions. 
<table>
<caption>Summary of subsystem privileges</caption>
<tr class="head">
<th>Option</th>
<th colspan="6"> Assigned privilege</th>
</tr>

<tr>
<td> </td>
<td>ALL</td>
<td>Modify</td>
<td>Browse</td>
<td>Udef</td>
<td>ADDPRIV member</td>
<td>System manager</td>
</tr>

<tr>
<td>
Add
</td>
<td> </td>
<td> </td>
<td> </td>
<td> </td>
<td>X</td>
<td>X</td>
</tr>

<tr>
<td>
Modify
</td>
<td>X</td>
<td>X</td>
<td> </td>
<td>X</td>
<td> </td>
<td>X</td>
</tr>

<tr>
<td>
Browse
</td>
<td>X</td>
<td>X</td>
<td>X</td>
<td> </td>
<td> </td>
<td>X</td>
</tr>

<tr>
<td>
Copy
</td>
<td>X</td>
<td> </td>
<td> </td>
<td> </td>
<td>X</td>
<td>X</td>
</tr>

<tr>
<td>
Rename
</td>
<td>X</td>
<td> </td>
<td> </td>
<td> </td>
<td> </td>
<td>X</td>
</tr>

<tr>
<td>
Delete
</td>
<td>X</td>
<td> </td>
<td> </td>
<td> </td>
<td> </td>
<td>X</td>
</tr>

<tr>
<td>
Import
</td>
<td> </td>
<td> </td>
<td> </td>
<td> </td>
<td>X</td>
<td>X</td>
</tr>

<tr>
<td>
Export
</td>
<td>X</td>
<td> </td>
<td> </td>
<td> </td>
<td> </td>
<td>X</td>
</tr>

<tr>
<td>
Export Delete
</td>
<td>X</td>
<td> </td>
<td> </td>
<td> </td>
<td> </td>
<td>X</td>
</tr>

<tr>
<td>
Admin
</td>
<td> </td>
<td> </td>
<td> </td>
<td> </td>
<td> </td>
<td>X</td>
</tr>
</table>
Note: Copy privileges require both ALL and ADDPRIV SCLASS membership. A user assigned Udef privileges can update only the Userdef screens.

==User Matrix screen==

To change a single account in any class of a subsystem, use the User Matrix screen. Access the User Matrix screen by selecting the ADMIN option (number 10) on the Activity screen, then selection 1 under the Usage options. 

User Matrix screen
[[File:Sm8-14Matrix.gif|533px]] 

===Commands===
<ul>
<li>F7 and F8 provide scrolling to and from the first to last Subsystem Class Users screen when more than one screen is required.</li>

<li>F10 and F11 provide scrolling to the left and to the right to locate all subsystem classes for the subsystem shown in the leftmost column. </li>
</ul>

===Specifications===
<ul>
<li>Subsystem Name specifies the subsystem in which the user account is defined.</li>

<li>Account Exists In specifies the class in which the account is defined.</li>

<li>Subsystem Classes commands are entered in a one-character input field that precedes each class displayed:
<ul>
<li><code>A</code> adds the current account to the class in the subsystem shown.</li>

<li><code>C</code> changes the class in the subsystem to which the current account belongs from the Account Exists In or default class to the class at the right of the command.</li>

<li><code>D</code> deletes the current account from the class in the subsystem shown. Note that this is one way to change an account's class from a non-default to the default class in a semi-public subsystem. </li>
</ul></li>
</ul>

==Dynamic APSY support==

An application subsystem (APSY) is comprised of <var class="product">Model 204</var> procedures executed in a logical order. You define the operation of the application using the <var class="product">Model 204</var> Subsystem Management facility (SUBSYSMGMT). The <var class="product">Model 204</var> procedures determine the contents of the application. You can dynamically modify the following aspects of an APSY, without terminating the APSY and without interrupting service to your users:
<ul>
<li>A subset of application subsystem attributes.</li>

<li>Precompiled and non-precompiled procedures in files that participate in procedure locking while the subsystem is active. </li>
</ul>

You can also save compiled procedures that contain commands by saving the commands before and after the BEGIN/END. The commands are saved on a chain of CCATEMP pages in the form of a temporary procedure. The temporary procedure contains pointers to these pages. These temporary procedures are not the user-accessible temporary procedures (0, -1, and so on) and do not interfere with their operation.

===Changing APSY subsystem attributes===

Subsystem attribute modifications are saved to the permanent subsystem definition in the CCASYS file as well as to the active in-core subsystem definition without interrupting service to the subsystem user.

====Updating an active subsystem via SUBSYSMGMT====

The SUBSYSMGMT subsystem maintains all subsystem definitions. You can modify various attributes of a subsystem through a variety of screens provided by SUBSYSMGMT. Once you are satisfied with the modifications that are made, press F12 to end the updates and to save the definition to disk.
SUBSYSMGMT checks to see if the subsystem is currently active:
<ul>
<li>If the subsystem is not active, you return to Subsystem Management Facility screen. </li>

<li>If the subsystem is active, the following Active Subsystem Update screen is displayed:
<table>
<tr><td>
SUBSYSMGMT Active Subsystem Update

Subsystem: MCC1

is currently active.

Would you like to update the active subsystem definition?

PF3 to QUIT/Not update the active subsystem definition
PF12 to END/Update the active subsystem definition

===>

1=HELp 2= 3=QUIt 4= 5= 6=
7= 8= 9= 10= 11= 12=END
</td></tr>
</table>
</li>
</ul>

At this point, the permanent definition in the CCASYS file has been updated. Your response to this screen determines whether the subsystem will be dynamically updated.
<ul>
<li>To update the active subsystem definition, press F12. </li>

<li>To keep the active in-core definition unchanged, press F3. </li>
</ul>

Only the F1 (HELp), F3 (QUIt), and F12 (END) function keys are active at this time. 

====Using Active Subsystem Help====

If you press F1 while in the Active Subsystem Update screen, the following Active Subsystem Help screen is displayed: 
<table>
<tr><td>
SUBSYSMGMT Active Subsystem Help

Use this screen to update the active subsystem definition. If the subsystem
has been started and is currently active then the user has the option of
refreshing the subsystem definition that is currently running. Only the
following fields are supported for active update at this time:
. Log user into M204
. Log user out of M204
. Auto Commit
. Maximum Iterations
. Account
. Disconnect
. Informational
. Error
. Login Procedure
. Error Procedure
In order to update APSY fields that are not supported for active update,
the user must stop and restart the subsystem.
Use the PF key below to move to the next screen:
PF 3 = QUIT Does NOT UPDATE active subsystem definition.
Returns to Subsystem Management primary screen.
PF12 = END Updates active subsystem definition.
Returns to Subsystem Management primary screen.
</td>
</tr>
</table>

====Leaving the active subsystem unchanged====

If you press F3 or enter <code>QUIT</code> in the Active Subsystem Update screen, you leave the active subsystem unchanged and return to the Subsystem Management Facility screen. The changes you made go into effect the next time the subsystem is started

====Updating the active subsystem====

Press F12 or enter <code>END</code> to update the active subsystem definition. The changes to the dynamic attributes go into effect immediately. Non-dynamic changes do not take effect until the next time the subsystem is started. 
<ul>
<li>If the update is successful, you are returned to SUBSYSMGMT main menu screen without any confirmation messages displayed.</li>

<li>If the update is unsuccessful, one of the following messages is displayed on the main menu screen:
SUM014 Unable to update active definition for subsystem: name
SUM015 Unable to update active definition, name is no longer active
</li>
</ul>

====Understanding the Dictionary/204 data definition errors====

<code>SUM014</code> is displayed if an error occurs while attempting to update the active definition. The reason for the error can be found on the audit trail with one of the following errors: 
M204.1457 UNABLE TO SCAN LIST OF SUBSYSTEM names

M204.1685 SUBSYSTEM name DOES NOT EXIST

M204.2253 SUBSYSTEM name, record type - RECORD CONTAINS INVALID DATA

M204.2391 SUBSYSTEM name, record type - TRANSLATION FAILED FOR FIELD fieldname

M204.2395 SUBSYSTEM name, record type - RECORD MISSING


<code>SUM015</code> is displayed if the subsystem is stopped while attempting to update the active definition. The following error message is generated on the audit trail:
M204.2647 UNABLE TO UPDATE ACTIVE DEFINITION, <name> IS NO LONGER ACTIVE.


====Limits to dynamic subsystem attribute changes====

The following table lists the subsystem attributes that you can change. You can make changes on the Operational Parameters screen in SUBSYSMGMT: 
<table class="thJustBold">
<caption>Operational Parameters you can change</caption>

<tr class="head">
<th>Operational Parameter </th>
<th>Specifies</th>
</tr>

<tr>
<th>Log user into M204 </th>
<td>The user is logged into <var class="product">Model 204</var> with the subsystem name as the USERID</td>
</tr>

<tr>
<th>Log user out of M204 </th>
<td>The user is logged out upon leaving subsystem </td>
</tr>

<tr>
<th>Auto Commit </th>
<td> A User Language COMMIT/RELEASE statement is run at the end of each procedure</td>
</tr>

<tr>
<th>Maximum Iterations </th>
<td>Maximum number of consecutive times you can invoke the same procedure before the ERROR procedure is invoked</td>
</tr>

<tr>
<th>Account </th>
<td>The account value other than the one used at logon</td>
</tr>

<tr>
<th>Disconnect </th>
<td>Whether to display a system disconnect message</td>
</tr>

<tr>
<th>Informational </th>
<td>Whether to display <var class="product">Model 204</var> informational messages</td>
</tr>

<tr>
<th>Error </th>
<td>Whether to display <var class="product">Model 204</var> error messages</td>
</tr>
</table>

You can change the following on the Procedure Specifications screen in SUBSYSMGMT:
<table class="thJustBold">
<tr class="head"><th>Procedure </th>
<th>Description</th>
</tr>

<tr>
<th>Login </th>
<td>First procedure that is invoked for every user</td>
</tr>

<tr>
<th>Error </th>
<td>Procedure that is invoked if an error occurs when a subsystem is running</td>
</tr>
</table>

If you dynamically change the name of the Login procedure or the Error procedure, the new name must be defined in the in-core procedure dictionary. You cannot add new procedures to a subsystem procedure file that participates in procedure locking once the subsystem has been started and have those procedures included by the subsystem. Therefore, if you change the name of the login or error procedure that resides in a file that participated in procedure locking, then that procedure must have existed when the subsystem was started. 

===Dynamically refreshing procedure compilation with the REFRESH SUBSYSPROC command===

The <var>[[REFRESH SUBSYSPROC command|REFRESH SUBSYSPROC]]</var> command discards the existing precompilation and precompiles the first time through for each SYSCLASS. Once a procedure is refreshed, the subsystem includes the new version of the procedure the next time that procedure is invoked.
The newer version of the procedure is compiled and saved in CCATEMP for subsequent execution. 

The <var>REFRESH SUBSYSPROC</var> command optionally copies a procedure from an open file (or group) into another open subsystem file (or group) and updates the APSY in-core procedure dictionary with the new procedure text page. In group context, the <var>REFRESH SUBSYSPROC</var> command replaces and refreshes only procedures that participate in procedure locking, based on the <var>NUMLK</var> parameter. 

====Generating success messages====

Successful execution of the <var>REFRESH SUBSYSPROC</var> command generates the following confirmation messages:
M204.2665 procname REFRESHED IN SUBSYSTEM subsystem-name


If a <var>FROM</var> clause is specified, the following message is produced:
M204.2666 procname REPLACED IN FILE filename [IN GROUP groupname]


====Generating error messages====

The <var>REFRESH SUBSYSPROC</var> command may fail under the following circumstances:
<ul>
<li>If you do not have Refresh privileges to issue the command, the command fails, the procedure is not refreshed, and the following message is generated:
M204.0930 REQUIRES SUBSYSTEM COMMAND PRIVILEGE
</li>

<li>If the procedure is not defined in an active subsystem, the command fails, the procedure is not refreshed, and the following message is generated:
M204.2668: procname NOT FOUND IN ANY ACTIVE SUBSYSTEM
</li>

<li>If a procedure is not found in the file named in the <var>FROM</var> clause, or if the user does not have appropriate file privileges to copy procedures, the following message is generated:
M204.1158: CAN'T COPY PROCEDURE: procname
</li>

<li>If the subsystem file (or group) is out of space to copy the procedure, the command fails, the procedure is not refreshed, and the following message is generated:
M204.1483: NOT ENOUGH TABLED SPACE TO STORE PROCEDURE
</li>

<li>If another user is processing the procedure, the following message is generated:
M204.2669: PROCEDURE procname IS IN USE BY SUBSYSTEM subsys-name
</li>
</ul>

====Understanding REFRESH SUBSYSPROC command privileges====

Privileges to issue the <var>REFRESH SUBSYSPROC</var> command are set on the SUBSYSMGMT [[#Subsystem Classes screen|Subsystem Classes screen]] using the Refresh field on the Command Privileges line. The input to this field is either <code>Y</code> or <code>N</code>, where <code>N</code> is the default. To issue the <var>REFRESH SUBSYSPROC</var> command, set the Refresh value to <code>Y</code>.

====Subsystem processing====

When you refresh an active subsystem procedure, the following occurs:
<ul>
<li>Precompiled procedures are recompiled for each SCLASS.</li>

<li>While a procedure is being refreshed, the procedure is locked. While a procedure is locked, other users cannot access it. The length of time that the procedure is stopped is as short as possible.

However, if a subsystem attempts to include a procedure that is in the process of being refreshed, the APSY tries to invoke the procedure a few times before giving up. If the APSY fails to invoke the procedure, then the subsystem error procedure is invoked with the error global set to <code>RFR</code>. 

You must write an error procedure instructing your subsystem how to respond to various errors.
</li>
</ul>

====Handling a blocked refresh for a subsystem procedure====

If an APSY subsystem procedure with the subsystem precompile prefix is compiled, and the procedure is found in an unlocked subsystem procedure file, the following message is generated:
M204.0468: COMPILATION NOT SAVED - INCLUDE FROM UNLOCKED FILE


====Using the SUSPEND SUBSYSTEM command====

Rocket Software recommends that you issue the <var>[[SUSPEND SUBSYSTEM command|SUSPEND SUBSYSTEM]]</var> command and wait for the active users to exit. If you do not wait, you could have the following problem. The subsystem, which has logically related procedures, is suspended and a user invokes a procedure whose higher-level or lower-level procedure has not been updated and refreshed yet.



Privileges to issue the <var>SUSPEND SUBSYSTEM</var> command are set in the SUBSYSMGMT "Subsystem Classes" screen: 
<table>
<tr class="head">
<th>If you issue a SUSPEND SUBSYSTEM command when... </th>
<th>The subsystem is set to...</th>
</tr>

<tr>
<td>No active users are in the application subsystem </td>
<td>Suspended state.</td>
</tr>

<tr>
<td>Active users are in the subsystem </td>
<td>Suspending state. Current, active users continue to use the subsystem, but new users cannot enter it. After all users exit the subsystem, it is set to the Suspended state.</td>
</tr>
</table>

====Monitoring the subsystem====

You can issue a <var>MONITOR SUBSYSTEM</var> command to check the status — such as Drain or Suspend — of the subsystem, as well as the number of users still running. Once a subsystem is fully suspended and the number of users is zero (0), you can safely refresh a set of logical procedures.

If you suspend a subsystem that still has active users, the <var>STATUS</var> option from the <var>MONITOR SUBSYSTEM</var> command is set to <var>SUSPENDING</var>. When a subsystem is fully suspended with no active users, the <var>STATUS</var> option from the <var>MONITOR SUBSYSTEM</var> command is set to <var>SUSPENDED</var>. 

If the subsystem is in the process of suspending, the following message is generated:
M204.2659 subsys-name SET TO SUSPEND, REMAINING USERS=n


====SUSPEND SUBSYSTEM command messages====

The <var>SUSPEND SUBSYSTEM</var> command may produce the following messages:
<ul>
<li>When a subsystem is successfully suspended, the following message is generated:
M204.2661 SUBSYSTEM subsys-name SUSPENDED
</li>

<li>When there are still active users in the subsystem, the following message is generated:
M204.2659 subsys-name SET TO SUSPEND, REMAINING USERS = <n>
</li>

<li>If you issue the <var>SUSPEND SUBSYSTEM</var> command without Subsystem Suspend privileges defined for your SCLASS, the following message is generated:
M204.0930 REQUIRES SUBSYSTEM COMMAND PRIVILEGE
</li>

<li>The <var>SUSPEND SUBSYSTEM</var> command is valid against only an active subsystem. If the subsystem has not been started, the following message is generated:
M204.1126 SUBSYSTEM name MUST BE STARTED
</li>

<li>If the subsystem is in <var>TEST</var> mode, it is locked from other users, so the following message is generated:
M204.0448 SUBSYSTEM TEST IN PROGRESS, COMMAND REJECTED
</li>

<li>If a subsystem is in the process of starting, but not yet fully active, the following message is generated:
M204.2311 SUBSYSTEM subsys-name IS BEING STARTED
</li>

<li>If the subsystem was set to Stop and is waiting for all active users to quit, the following message is generated:
M204.0446 SUBSYSTEM subsys-name IS TEMPORARILY DISABLED
</li>

<li>If the subsystem requires users to log into <var class="product">Model 204</var> and you are not logged in, the following message is generated:
M204.1031 PLEASE LOGIN
</li>

<li>If an error prevents the subsystem from being suspended, the following message is generated. The preceding message states the cause of the error.
M204.2656 UNABLE TO SUSPEND SUBSYSTEM subsys-name
</li>
</ul>

<div id="resume subsystem"></div>
====Using the RESUME SUBSYSTEM command====

When you have completed refreshing a suspended subsystem, you can reactivate it with a <var>[[RESUME SUBSYSTEM command|RESUME SUBSYSTEM]]</var> command.


Privileges to issue the <var>RESUME SUBSYSTEM</var> command are set in the SUBSYSMGMT "Subsystem Classes" screen.

The <var>RESUME SUBSYSTEM</var> command may generate the following messages:
<ul>
<li>When a subsystem successfully resumes, the following message is generated:
M204.2657 SUBSYSTEM subsys-name RESUMED
</li>

<li>If you issue the <var>RESUME SUBSYSTEM</var> command without Subsystem Resume privileges defined for your SCLASS, the following message is generated:
M204.0930 REQUIRES SUBSYSTEM COMMAND PRIVILEGE
</li>

<li>The <var>RESUME SUBSYSTEM</var> command is valid against only a suspended subsystem. If the subsystem was not suspended, the following message is generated:
M204.2658 SUBSYSTEM subsys-name NOT IN SUSPEND STATE
</li>

<li>The <var>RESUME SUBSYSTEM</var> command is valid against only a suspended subsystem. If the subsystem has not been started, the following message is generated:
M204.1126 SUBSYSTEM subsys-name MUST BE STARTED
</li>

<li>If the subsystem is in Test mode, it is inactive for other users, so the following message is generated:
M204.0448 SUBSYSTEM TEST IN PROGRESS, COMMAND REJECTED
</li>

<li>If a subsystem is in the process of starting, but not yet fully active, the following message is generated:
M204.2311 SUBSYSTEM subsys-name IS BEING STARTED
</li>

<li>If the subsystem was set to stop and is waiting for active users to quit, the following message is generated:
M204.0446 SUBSYSTEM subsys-name TEMPORARILY DISABLED
</li>

<li>If the subsystem requires users to be logged in to <var class="product">Model 204</var> and you are not logged in, the following message is generated:
M204.1031 PLEASE LOGIN
</li>

<li>If an error prevents the subsystem from resuming processing, the following message is generated. The previous message states the cause of the error.
M204.2655 UNABLE TO RESUME SUBSYSTEM subsys-name
</li>
</ul>

===Using precompilable procedures with commands===

If you want to conditionally compile and save a SOUL request through the use of dummy string comments, then you must ensure that the value of the dummy string is the same for all SOUL statements for that request. Otherwise, unpredictable results occur. 

In addition, the loading user will invoke the request that was conditionally compiled by the compiling user. This behavior is simply noted as a reminder.

If a precompiled procedure issues the <var>INCLUDE</var> command to compile and run a SOUL request, the <var>INCLUDE</var> command is saved, not the compilation of the request that was included.

Dummy string substitution does not take place when saving commands that contain dummy strings. Instead, when the saved commands are loaded and executed, the current value of the dummy string is used. For example, if you include the following command in a precompiled procedure, whatever is currently in the global <code>COMMAND</code> is executed.
?&COMMAND


Procedures that include multiple <var>BEGIN</var>/<var>END</var> blocks are not eligible for precompilation.

===Handling subsystem error procedures===

If a subsystem error procedure is cancelled due to attempted terminal I/O, and the return code is one of the following — <code>CAN</code>, <code>HNG</code>, <code>HRD</code>, or <code>SFT</code> — the error procedure cannot attempt to issue any of the following SOUL statements:
<ul>
<li>PRINT</li>

<li>READ</li>

<li>READ MENU</li>

<li>SCREEN</li>

<li>SKIP</li>

<li>$$ prompts</li>

<li>$Read</li>

<li>Or any other statement that writes to the user's terminal</li>
</ul>

All other SOUL statements are permitted.

</div> 

[[Category:System management]]
[[Category:Model 204 operational issues]]

Dictionary/204 administration

2025-06-06T17:37:28Z

JDamon: /* Defining the role */

==Overview of the administrator role==
===Defining the role===

Any system manager is authorized (if the [[APSYSEC parameter]]=1) to start and use the Dictionary Administration facility (DICTADMIN) and the Subsystem Management facility (SUBSYSMGMT). Any system manager then has complete control over subsystem definitions and can authorize other users (non-system managers) to use those subsystems. 

The system manager must also define the administrator in the ADMIN class for each subsystem by using the Subsystem Management facility. 

The Subsystem Management facility is described in [[System requirements for Application Subsystems#Overview of the Subsystem Management facility|Overview of the Subsystem Management facility]]. 

===Areas of responsibility===

The responsibilities of the dictionary administrator cover six main areas: 
<ol>
<li>[[Dictionary/204 administration#Starting and stopping the Dictionary/204 subsystems|Starting, stopping, and testing the DICTIONARY subsystems]]</li>
<li>Maintaining Dictionary/204 files (such as backing up, restoring, and reorganizing dictionary files)</li>
<li>Maintaining dictionary structure through [[#Entity type maintenance|entity type maintenance]] (such as defining, deleting, and updating new entity types)
</li>
<li>Maintaining [[#Facility Administration|Dictionary/204 facilities]] (for example, setting parameters and defaults)

Several of the facilities that are part of the Dictionary/204 environment can be modified to suit the needs of your installation. Specifically, you can alter default and control parameters for File Management and Dictionary Reports.
</li>
<li>Maintaining Dictionary/204 [[#Security Administration|security]] (defining Dictionary/204 users and their privileges). See also [[Dictionary/204 logon and commands#Security considerations|Security considerations]].

The administrator controls access to the Dictionary/204 and Documentation facilities through the ACCOUNT entry in the dictionary.
</li>
<li>Populating the Dictionary (with the DDGEN and DDGENSET utilities) to define and synchronize existing Model 204 files in the dictionary

The Dictionary Administrator normally runs the DDGEN and DDGENSET utilities.
<ul>
<li>[[#Creating or updating Dictionary entries with DDGEN|DDGEN]] (a subsystem) creates dictionary entries for existing Model 204 files.</li>
<li>[[#DDGENSET utility|DDGENSET]] creates JCL (OS/DOS) and FILEDEFs (CMS) and the CCAIN input data stream for DDGEN.</li>
</ul>
The administrator can also create customized reports with the Dictionary Reports facility.
</li>
</ol>

==Installing Dictionary/204==
For information about installing Dictionary/204, see the [[Dictionary/204 installation guide]]. 

==Starting and stopping the Dictionary/204 subsystems==

Administrators of Dictionary/204 start the subsystem as follows:
<ol>
<li>Log in to the Model 204 system by using the <var>[[LOGIN or LOGON command|LOGIN or LOGON]]</var> command as the Dictionary/204 administrator, and by using the account name defined by your system manager. </li>

<li>To start Dictionary/204, enter:

START SUBSYSTEM DICTIONARY 
For more information, see [[START command: Starting an application subsystem]]. </li>

<li>To use Dictionary/204, enter:

DICTIONARY 
This command invokes the Dictionary/204 subsystem after it has been started.

Note: Starting Dictionary/204 starts only the Dictionary/204 main menu. It does not automatically start the individual subsystems (or facilities) that make up the Dictionary/204 product. 
</li>
</ol>

You must start each subsystem independently, using the word <var>SUBSYSTEM</var> and the facility name as the arguments of the <var>START</var> command. If you are accessing Dictionary/204 facilities from the [[RKWeb]] interface, all the subsystem starting commands are probably already issued as part of the [[RKTools installation#Janus Web rules for RKWeb|recommended set up for RKWeb]]. 

The facility names are:
<table>
<tr class="head">
<th>Facility</th>
<th>Facility Name</th>
</tr>

<tr>
<td>Dictionary Administration</td>
<td>DICTADMIN</td>
</tr>

<tr>
<td>Dictionary Reports</td>
<td>DICTREPORT</td>
</tr>

<tr>
<td>Documentation</td>
<td>DOCUMENT</td>
</tr>

<tr>
<td>File Management</td>
<td>FILEMGMT</td>
</tr>

<tr>
<td>Subsystem Management</td>
<td>SUBSYSMGMT</td>
</tr>

<tr>
<td>User Language Cross-Reference</td>
<td>XREF</td>
</tr>
</table>

You can start all the subsystems along with starting Dictionary/204 by adding the <var>START SUBSYSTEM</var> commands to the CCAIN file for your Model 204 Online system. Consult your system manager about adding these commands to CCAIN.

If you are having trouble with one of the Dictionary/204 subsystems, you might want to delete the corresponding START command from CCAIN before starting Dictionary/204 and its other subsystems.

Typically, you stop Dictionary/204 subsystems at the end of the day. You might also need to stop the subsystems periodically to perform utility functions. For example, it might be necessary to stop the Dictionary/204 subsystems to open and use the individual files that make up the dictionary. 

Refer to the Rocket [[Model 204 installation|Model 204 installation instructions]] for your operating system for a discussion of these utility functions. For information about more generalized Model 204 file maintenance, see [[File management overview]].

To stop Dictionary/204, issue the following command: 
STOP SUBSYSTEM DICTIONARY 

After you issue the <var>STOP</var> command for Dictionary/204 and its subsystems, users cannot invoke the main menu or any of its subsystems. If no one is currently using the subsystem, Model 204 displays:
DICTIONARY STOPPED 

If any Dictionary/204 facilities are in use when the <var>STOP SUBSYSTEM</var> command is issued, the following message is displayed on your terminal:
DICTIONARY SET TO STOP, REMAINING USERS = <var class="term">n</var>

where <var class="term">n</var> represents the current number of active users. Current users of Dictionary/204 are allowed to finish their work, but additional users cannot start a session. When all users have ended their sessions, Dictionary/204 is stopped.

This STOP command applies only to the Dictionary/204 main menu, the subsystem for which you have entered the STOP command. Each subsystem must be stopped individually, just as each must be started individually. If any other subsystems are running, users can still access them, but not through the main menu.

If you stop the Dictionary/204 (main menu) subsystem before stopping other Dictionary/204 facility subsystems, users who logged on to the other subsystems through the main menu receive an error message when logging off. The error, however, does not interfere with saving data or any other facility function.

Even though Dictionary/204 is now shut down, you as administrator are still logged on to Model 204 and can issue any of the Model 204 commands. 
For more information, see [[STOP command: Stopping an application subsystem]].

You can restart Dictionary/204 by typing the following Model 204 command: 
START SUBSYSTEM DICTIONARY 
===Sending a BROADCAST message===

You can use the Model 204 <var>[[BROADCAST command: Sending a file message|BROADCAST]]</var> command to send a message to subsystem users. After you send a message, it is displayed on a user's screen as soon as that user completes the current function and returns to a menu selection screen. The BROADCAST command can be used to alert subsystem users to end a session so that file maintenance or other utility functions can be performed.
===Diagnosing Dictionary/204 session errors===

If during a Dictionary/204 session a "DICTIONARY SESSION ERROR" occurs, you can use the TEST command to diagnose the problem. The TEST command displays all messages on your terminal. From these messages, you can determine the source of the session error and resolve the problem. To run the TEST command, you must first stop Dictionary/204. This is necessary, because the command puts Dictionary/204 in a single-user mode while the system displays all messages to the terminal.

To use the TEST command, issue the following commands:
STOP SUBSYSTEM DICTIONARY
TEST DEBUG DICTIONARY 

You can either try to duplicate the session with the TEST command or consult the audit trail for a listing of the messages.

==Dictionary/204 file maintenance==

See [[Dictionary/204 operation and file maintenance]] for details.

==Creating or updating Dictionary entries with DDGEN==

You can use the DDGEN utility (a Dictionary/204 subsystem) to create or update dictionary entries that describe the characteristics and contents of existing Model 204 files. The DDGEN utility enables you to populate your dictionary with entries for physical files, fields, field groups, records, and procedures.
Following the completion of DDGEN, you can use Dictionary/204 to add any desired attributes or values to these entries.
===DDGENSET utility===
DDGENSET is a supplementary utility for DDGEN that creates a file of file names from existing dictionary entries, enabling you to edit the list of files to run through DDGEN. DDGENSET updates the entries. You can run DDGEN against as many as 100 files at one time.

Before you can update Dictionary/204 files with external procedures, you must have the required update privileges. 

Note: Transaction backout files must be updated without accessing non-transaction-backout files. 

===DDGEN and standard definitions===

For each file that is processed, DDGEN creates or updates the following dictionary entries:
<table>
<tr class="head">
<th>For this item...</th>
<th>One entry is added to the dictionary...</th>
</tr>
<tr>
<td>FILE</td>
<td>For file parameters and table sizes for the file</td>
</tr>
<tr>
<td>PROCEDURE</td>
<td>For each procedure in the file, along with any of its aliases</td>
</tr>
<tr>
<td>FIELD</td>
<td>For each field in the file to specify the attributes of the field</td>
</tr>
<tr>
<td>RECORD</td>
<td>If there is no record defined for the file</td>
</tr>
</table>


References from the FILE entry to each FIELD, and from the FILE entry to each PROCEDURE are also created when DDGEN is run.

When running DDGEN, you must ensure that the attributes required by DDGEN are not deleted from the entity type definitions.

Note: If any of these required attributes have been deleted from the entity type definitions, you can add the attributes again with the Dictionary Administration facility (by selecting the Entity Type Maintenance option).

When DDGEN stores an entry in the dictionary, the utility writes the entry to a report file (OUTFILE). You can optionally send the report to CCAPRINT. If the dictionary already contains an entry with the same name as the file, procedure, or field being stored, the entry is updated and a message is written to both the CCAPRINT data set and the Model 204 journal or audit trail.
<table>
<tr class="head">
<th>Item</th>
<th>Required attributes</th>
</tr>
<tr>
<td>FILE</td>
<td>DDGEN creates a FILE entry for the Model 204 file that it is processing. The values for the FILE attributes are derived from the parameters or table sizes defined for the Model 204 file.

A list of the FILE attributes can be found in [[Dictionary/204 entity type definitions#FILE|FILE]], where the FILE entity type is defined.
</td>
</tr>
<tr>
<td>FIELD</td>
<td>DDGEN creates a FIELD entry for each field defined for the Model 204 file. The values for the FIELD attributes are derived from the field definition statements for the Model 204 file.

A list of the FIELD attributes can be found in [[Dictionary/204 entity type definitions#FIELD|FIELD]], where the FIELD entity type is defined.
</td>
</tr>
<tr>
<td>PROCEDURE</td>
<td>DDGEN creates a PROCEDURE entry for each procedure defined for the file.

Each entry consists of attributes and relationships that are defined in [[Dictionary/204 entity type definitions#PROCEDURE|PROCEDURE]], where the PROCEDURE entity type is defined.

One occurrence of the ALIAS attribute is added to the PROCEDURE entry for each alias associated with the procedure.
</td>
</tr>
<tr>
<td>RECORD</td>
<td>DDGEN creates a record entry, if no record exists for that file. The record is given the UNQUALIFIED NAME <<var class="term">filename</var>>. Thus, the (unique) NAME of the entry will be <<var class="term">filename.filename</var>>.

Additionally, all preallocated fields will be cross-referenced to a RECORD entry.

See [[Dictionary/204 entity type definitions#RECORD|RECORD]] for information about the attributes of the RECORD entity type.
</td>
</tr>
</table>

===Using the Batch utility to run DDGEN===

Use the DDGEN Job and/or the DDGENSET Job (z/OS or z/VSE) or the DDGEN option of the D204 EXEC (z/VM) to run the DDGEN utility. Customize this Job or EXEC for your installation, as described in your installation guide. (Consult the relevant chapter of your installation guide.) You must specify a DD statement (z/OS); DLBL, EXTENT, and ASSIGN (z/VSE); or LINK, ACCESS, and FILEDEF (z/VM) for the multiple Model 204 files to be used. You must also specify this filename in the CCAIN (User 0) along with a password, if required.
You can specify up to 100 Model 204 files in a single DDGEN run.

The following example shows the CCAIN stream for DDGEN when run in batch mode:
<nowiki>PAGESZ=6184,SPCORE=20000,SERVSIZE=180000,LGTBL=1000,NFILES=110, X
NDCBS=110,NDIR=110,INCCC=0,MINBUF=10,LENQTBL=6000

**********************************************************************
* MAKE THE FOLLOWING MODIFICATIONS TO THIS CCAIN INPUT STREAM: *
* 1) USERID = THE PRIVILEGED ID *
* 2) PASSWORD = THE PASSWORD FOR THAT ID *
* 3) ENTER FILENAME AND FILE PASSWORDS AS SPECIFIED BELOW *
* 4) THE WORD "END" MUST FOLLOW THE LAST FILE,PASSWORD ENTERED *
* NOTE: OUTFILE REFERS TO THE REPORT FILE FOR THE RUN *
* OUTDDGN IS THE TEMPORARY WORK FILE FOR THE RUN *
**********************************************************************
LOGON USERID
PASSWORD
START SUBSYS DDGEN
DDGEN
OUTFILE
OUTDDGN
*ENTER FILENAME 001 *
*ENTER FILENAME 001 PASSWORD OR BLANK LINE *
*ENTER FILENAME ... *
*ENTER FILENAME ... PASSWORD OR BLANK LINE *
*ENTER FILENAME 100 *
*ENTER FILENAME 100 PASSWORD OR BLANK LINE *
END</nowiki>

As the CCAIN stream indicates, OUTFILE is the name of the report file for the batch run. OUTDDGN is the name of the work file that you must specified for this batch run.

The OUTDDGN record format must be FBA.

===Running DDGEN Online===

DDGEN can be run Online with certain restrictions. Each user who runs DDGEN must have an exclusive report OUTFILE and work OUTDDGN file. This is necessary to maintain the integrity of the report and of the updates. Optionally, the report can also be routed to the screen, but an exclusive work file is required in any case.

To run DDGEN Online, follow the flow of the CCAIN stream for DDGEN shown in [[#Using the Batch utility to run DDGEN|Using the Batch utility to run DDGEN]]. Although the first two lines (or the User 0 line) are not necessary to run DDGEN Online, be sure that all the relevant parameters are set to values at least equal to those given in the example. Follow these steps: 
<ol>
<li>Log in to Model 204.</li>
<li>Issue the command START SUBSYS DDGEN.</li>
<li>To run the job, type:
DDGEN
</li>
<li>
You are prompted for the report OUTFILE filename. Enter the report outfile name for spooled output, or press enter to have the report printed on the screen.</li>
<li>
You are prompted for an exclusive work OUTDDGN. Enter the name of the work OUTDDGN. For each file to run through DDGEN, you are prompted for a filename and then a password. Press Enter to receive prompts for additional files to be processed.</li>
<li>
To end the entry of filenames, enter END for the file name and press Enter. To cancel the DDGEN run, enter QUIT for the file name (instead of END) and press Enter. </li>
</ol>

You can process up to 100 files in a single run. It is recommended that you start with only a few files to determine how long it takes to run DDGEN in your environment.

===Modifying and running DDGENSET===

The DDGENSET job can be used as a front end to the DDGEN job described in [[#Running DDGEN Online|Running DDGEN Online]]. DDGENSET reads your installation's dictionary and automatically creates the CCAIN stream. For z/VSE it creates the step override statements for DDGEN JCL. For z/OS, it creates the FILEDEF statements to be included in D204FDEF EXEC. 

DDGENSET processes existing dictionary entries only. Each entry must contain valid data set and DDname attribute values. If there are more than 100 files in your dictionary (the limit for DDGEN), DDGENSET creates multiple sets of CCAIN and step override statements.

After DDGENSET has created statements, be sure to edit these statements to specify any missing data set or password information and to delete files that do not actually exist as Model 204 files. 
<table>
<tr class="head">
<th>Replace...</th>
<th>With...</th>
</tr>
<tr>
<td>USERID</td>
<td>Your installation's privileged system manager login account name.</td>
</tr>
<tr>
<td>PASSWORD</td>
<td>Password for the USERID account name.</td>
</tr>
</table>

Refer to your Model 204 installation guide for more information.

Note: Run DDGENSET in batch mode to help prepare you for a batch run of DDGEN.

===Recovering from system problems===

When a system error (for example, a system crash) causes you to exit from a Dictionary/204 facility, the protection (or lock) for the data you were using at the time of the error might not be returned. This occurs because the subsystem error routines cannot run. If this happens, the dictionary administrator must run the procedure SHRO.LOCKFREE to maintain the lock for the data.

Also, if an individual user is restarted, locks can be restored by running SHRO.LOCKFREE.

(See the appropriate sections of the Rocket [[Model 204 installation|Model 204 installation instructions]] for your operating system for more information.) 

To run SHRO.LOCKFREE:
<ol>
<li>Open M204TEMP.</li>
<li>Enter:
INCLUDE SHRO.LOCKFREE 

This utility deletes the locks for specified entries.
</li>
<li>
You are prompted to provide the entity type and entry name. Specify the entry, or, to quit the utility, press Enter in response to this prompt.</li>
<li>
If you specify the entry, press Enter. The system displays a message confirming that the lock has been freed.</li>
</ol>

Locks are maintained across sessions for files. Thus, the utility leaves the file locked to the same user ID.

==Logging on to Dictionary/204==

To log on to the Dictionary Administration facility, choose one of the following methods:
<ul>
<li>Select the number of the Dictionary Administration facility option from the Dictionary/204 main menu.

If your main menu does not display the Dictionary Administration option, you have not been authorized to use this facility.</li>

<li>Invoke the Dictionary Administration facility from the primary screens of other Dictionary/204 facilities with the INVOKE command. The syntax of the command is:
INVoke DICTADMIN </li>

<li>Call the Dictionary Administration subsystem from the Model 204 command prompt by typing the subsystem name:
DICTADMIN 

You can log on with this method only if you have started the Dictionary Administration subsystem.</li>

<li>If using the [[RKTools#mainmenu|RKTools main menu]], select the DictAdmin menu item. If using the [[RKWeb]] interface, select <code>Manage > Dictionary > Administration</code>. </li>
</ul>

==Using the Dictionary/204 Administration main menu==

Dictionary/204 displays the following main menu when you select the Dictionary Administration option:

[[File:Dictionary_fig6-1.png]]

In brief, the Dictionary Administration facility provides the following capabilities (numbered items correspond to the menu options):

<ol>
<li>Defining, modifying, or deleting an entity type. You can define the attributes and named or cross-referenced relationships of the new entity types, and obtain a report on entity types and path relationships.</li>
<li>Defining, viewing, modifying, and deleting path relationships.</li>
<li>Modifying the default and control parameters for File Management and Dictionary Reports.</li>
<li>Maintaining security by controlling access to the Dictionary/204 facilities.</li>
<li>Requesting a printed inventory of entity types and their attributes and relationships. The report is available only in hard copy and cannot be sent to the terminal. </li>
</ol>
====Input====

To select an option from this menu, type a numbered choice at the Enter Number: prompt and press the Enter key.

====Commands====

To issue commands, press the assigned PF key or type the command name at the prompt (===>) and press Enter.
<table>
<tr class="head">
<th>Key</th>
<th>Command</th>
<th>Meaning</th>
</tr>
<tr>
<td>PF1</td>
<td>HELp</td>
<td>Provides the online HELP text for this screen. You can read the HELp text and exit from the last screen by pressing Enter.</td>
</tr>
<tr>
<td>
 
</td>
<td>INVoke</td>
<td>At the command prompt, type:
INVoke <var class="term">facility_name</var>
Then press Enter to invoke another facility.
</td>
</tr>
<tr>
<td>PF3</td>
<td>QUIt</td>
<td>Terminates Dictionary Administration. You also can type QUIT at the command prompt and then press Enter. The system then returns you to the Dictionary/204 main menu, to the primary screen of the facility from which Dictionary Administration was invoked, or to Model 204 command level.</td>
</tr>
<tr>
<td>Enter</td>
<td>
 
</td>
<td>Processes your main menu selection.</td>
</tr>
</table>

==Entity type maintenance==
===Overview===

The structure of the dictionary is based on entity types, attributes, and relationships. Although there are standard entity types, each having a predefined set of attributes and relationships, the administrator can customize or "extend" the dictionary by:
<ul>
<li>Adding new entity types that have their own attributes and relationships</li>
<li>Adding attributes and relationships (also called references) to the standard entity types </li>
</ul>

The standard entity types, their attributes and relationships are defined in [[Dictionary/204 entity type definitions]], except for VIEW, COMPOSITE VIEW, VIEW FIELD, and VIEW LINK which are described in [[Dictionary/204 view management]].

The administrator should not delete or modify the system- or facility-controlled attributes and relationships of the standard entity types. The standard entity types can be modified only by adding attributes or relationships.

Attributes, relationships, and entity types added to the dictionary by the administrator are not system- or facility-controlled. Their values are entered by users, primarily through the Documentation facility.

Users can add new relationships between dictionary entries through the Documentation facility, even if the new relationship is not part of the entry's definition as set up by the administrator. Users, however, cannot add attributes to the entity type definition.
===Entity Type Maintenance screen===

Dictionary/204 displays the following screen when you select the option Entity Type Maintenance from the Dictionary Administration menu:

[[File:Dictionary_fig6-2.png]]

This menu provides the following capabilities:
<ol>
<li>
Defining the attributes and relationships of a new entity type. The administrator must define the entity type before users can define entries.</li>
<li>
Updating an entity type, when there is a need to change the attributes and/or references of that entity type.</li>
<li>
Deleting an entity type, when there is no further need for entries of that type.</li>
<li>
Obtaining an entity type and path report when you need to survey the definitions of entity types or the spectrum of relationships between entity types. You can obtain a report on a single entity type or on all entity types and optionally include information on relationship paths.</li>
</ol>

====Input====

To select a function from this menu, you must select a numbered choice from the list of functions and then specify the entity type. Use options 1, 2, and 3 for maintaining the dictionary records, and option 4 for reporting on them.
<ul>
<li>Defining, updating, and deleting entity types:

Type the number of your selection at the Enter Number: prompt.

Respond to the Entity Type: prompt by typing the name of the entity type you want to define, modify, delete, or report on.

The maximum length of an entity type name is 20 characters.
</li>
<li>Reporting on entity types:

To report on all entity types, respond by typing ALL at the Entity Type: prompt. Otherwise, enter the name of a particular entity type.

If you do not want information about path relationships, type an N over the default value of Y after the following prompt:
Path Information on Report: Y

By default, Dictionary/204 sends reports to your terminal. You can direct the output to a different destination, however, by typing Y over the default value of N at the following prompt:
Route to Output File: N 

Your output file default is specified in your ACCOUNT entry. (The output destination can be a printer or a specified file.)

To override the default Output Destination for your account, type a new value for the following prompt:
Output Destination: OUTFILE 
The Output Destination name can be from 1 to 30 characters.
The system uses this file to send output to a destination other than your terminal. 
</li>
</ul>

To process your input on the Entity Type Maintenance menu, press the Enter key. You can press PF1 to read the HELP text for this menu, or press PF3 to terminate the Entity Type Maintenance function and return to the facility main menu.

===Defining new entity type attributes===

A screen similar to the following is displayed when you select the option Define New Entity Type from the Entity Type Maintenance menu. The following screen shows a sample REPORT entity type definition. Your screen is empty, except for the name of the entity type that you have specified on the previous screen and the arrow (-->) prompts.

The attributes you define here for the entity type appear as prompts for the Dictionary/204 users when they define a particular entry for this entity type. Users define entries for nonstandard entity types (such as REPORT) through the Documentation facility.

It is not necessary to add the following standard system-supplied attributes: NAME, CREATE DATE, LAST UPDATE, UPDATED BY, KEYWORD, ALIAS, SHORT DESCRIPTION, and DESCRIPTION. When users define particular entries through the Documentation facility, Dictionary/204 either provides these values or prompts the user for the values.

[[File:Dictionary_fig6-3.png]]

====Input====

Use your tab keys to position the cursor at the next (or previous) line.

Type the names of the attributes to be associated with this entity type to the right of the prompt:
<nowiki>===> </nowiki>

Note the following restrictions:
<ul>
<li>Type only one attribute following each arrow prompt.</li>
<li>Maximum length is 20 characters.</li>
<li>Allowable characters are the same as for Model 204 [[Field names|field names]].</li>
</ul>

To change an attribute name on this screen, type over the current name. To delete an attribute on this screen, use the Erase EOF key or use blank characters.

If you need more than the available number of lines on the screen to complete the attribute set, press PF8 (the FORward command). This command provides a new blank attributes definition screen. The FORward command is described in [[#Defining new entity type references]]. You can enter as many attributes on as many screens as necessary.

===Reserved words for attributes===

Avoid the reserved words listed in the following table when creating attributes for Dictionary/204 entity types. An attribute name that contains reserved words generates an error condition.
<table>
<caption>Reserved words</caption>
<tr>
<td>ALL</td>
<td>OR</td>
<td>#</td>
</tr>
<tr>
<td>AND</td>
<td>RECORD</td>
<td>;</td>
</tr>
<tr>
<td>AT</td>
<td>RECORDS</td>
<td>,</td>
</tr>
<tr>
<td>BEFORE</td>
<td>TAB</td>
<td>EQ</td>
</tr>
<tr>
<td>BY</td>
<td>THEN</td>
<td>GE</td>
</tr>
<tr>
<td>COUNT</td>
<td>TO</td>
<td>GT</td>
</tr>
<tr>
<td>EACH</td>
<td>VALUE</td>
<td>LE</td>
</tr>
<tr>
<td>EDIT</td>
<td>WHERE</td>
<td>LT</td>
</tr>
<tr>
<td>END</td>
<td>WITH</td>
<td>NE</td>
</tr>
<tr>
<td>FROM</td>
<td>=</td>
<td>+</td>
</tr>
<tr>
<td>IN</td>
<td>$</td>
<td>- (minus sign)</td>
</tr>
<tr>
<td>IS</td>
<td>??</td>
<td>*</td>
</tr>
<tr>
<td>LIKE</td>
<td>?$</td>
<td>/</td>
</tr>
<tr>
<td>NOR</td>
<td>$&</td>
<td>...</td>
</tr>
<tr>
<td>NOT</td>
<td>(</td>
<td>^ (not equal sign)</td>
</tr>
<tr>
<td>OCC</td>
<td>)</td>
<td>̺</td>
</tr>
<tr>
<td>OCCURRENCE</td>
<td>@</td>
<td>></td>
</tr>
</table>

To move on to the definition of relationships for the new entity type, press PF11 or issue the REFERENCES command. Your input is preserved but not saved until you issue the END command (PF12). You can quit (PF3) out of the definition process at any time before ending.

====Defining new entity type references====
<table>
<tr class="head">
<th>Key</th>
<th>Command</th>
<th>Meaning</th>
</tr>
<tr>
<td>PF3</td>
<td>QUIt</td>
<td>Terminates the definition process. Dictionary/204 returns you to the Entity Type Maintenance Menu, but does not save any part of the entity type definition.</td>
</tr>
<tr>
<td>PF8</td>
<td>FORward</td>
<td>Lets you define more attributes for the new entity type. To see another "Define New Entity Type: Attributes" screen, press PF8. This command preserves your input but does not store your definition; next attributes definition screen.</td>
</tr>
<tr>
<td>PF11</td>
<td>REFs</td>
<td>Takes you from the attributes definition screen to the screen that allows you to define references (relationships between entries). Your previous input is preserved but not saved until you issue the END command.</td>
</tr>
<tr>
<td>PF12</td>
<td>END</td>
<td>Saves your definition of the new entity type's attributes and references press. This command stores your input and returns you to the Entity Type Maintenance menu.</td>
</tr>
</table>

After you have specified all the attributes for the new entity type, you can specify the new entity type relationships to other entity types by pressing PF11 on the screen shown in the preceding section.

Use the following screen to specify relationships between the new entity type and existing entity types.

[[File:Dictionary_fig6-4.png]]
This sample screen specifies a cross-referenced relationship between REPORT and FILE, and a named relationship between REPORT and USER. Two implications for users of the Documentation Facility are:
<ul>
<li>
Whenever you add or update a REPORT entry or FILE entry, Dictionary/204 prompts you to specify a particular report or file for cross-referencing. The TRAVEL SUMMARY report, for example, can be cross-referenced to the TRIPS file.</li>
<li>
Whenever you add or update a REPORT entry, Dictionary/204 prompts you to specify that the named relationship ROUTED TO applies to a particular USER. (The TRAVEL SUMMARY report, for example, can be ROUTED TO Johnson.) </li>
</ul>

Type the name of a named relationship following the tilde (~) as shown in the ROUTED TO example. Leave cross-references blank, as shown in the FILE example. See [[Dictionary/204 overview#Relationships|Relationships]] for more information.

Named references are directional and can be updated (when using the Documentation Facility) only from one of the two related entity types (in this case only from the REPORTS entity). But all references (cross-references and named references in both directions) are displayed when users query the dictionary with the Dictionary Reports facility.

From this screen, you can:
<ul>
<li>Request another screen for defining relationships by pressing PF8 (FORward).</li>
<li>Cancel the definition of the entity type by pressing PF3 (QUIt).</li>
<li>Save the entity type definition by pressing PF12 (END). </li>
</ul>

====Input====

You can enter as many related entity types (for example, FILE, FIELD, USER) as you want. Specify one entity type per line in response to the prompt:
<nowiki>===></nowiki> 

The maximum length for an entity type name is 20 characters. You can specify a named relationship by adding a reference name in the space provided following the tilde (~). The maximum length for a relationship name is 19 characters. The previous example is ROUTED TO.

Use the tab keys to position the cursor at a new prompt.

To change a value typed on this screen, type over the current value. To delete a value, use the Erase EOF key or use blank characters.

====Commands====

Commands are the same as those for the previous screen, except that there is no REFs command (PF11). You cannot return directly to the screen for defining attributes. You can, however, modify the attributes by saving the definition (using the END command) and then selecting the Update Entity Type option from the Entity Type Maintenance menu.

===Updating an entity type===

Dictionary/204 displays this screen when you select the option Update Entity Type from the Entity Type Maintenance menu. Use this screen to indicate that you want to change the definition format of an existing entity type. Specify the name of the entity type on the main menu when you select the update option.

You can add new attributes to the definition of standard entity types, but you cannot modify the standard system-controlled attributes provided by Model 204. If you have created a new entity type (such as REPORT) you can modify any of its attributes or relationships.

You might want to update an entity type:
<ul>
<li>When the attributes for an entity type have changed. For example, additional REPORT attributes might need to be specified.</li>
<li>When an entity type contains references to another entity type that has been, or that will be, deleted. </li>
</ul>

The following screen shows the REPORT entity type definition ready to be updated:

 [[File:Dictionary_fig6-5.png]]

====Input====

Dictionary/204 displays all the attributes and references defined for the specified entity type on two update screens: one for attributes (shown above), and one for relationships (shown in [[#Updating entity type references|Updating entity type references]]).

You can modify the attributes by following the directions on the previous screen:
<ul>
<li>Type over existing attributes, using the Erase EOF key or blank characters to delete extra characters.</li>
<li>Specify new attributes on a blank line. </li>
</ul>

Note: Typing over an attribute name deletes the current attribute and replaces it with a new attribute; it does not simply change the name of the existing attribute. Moreover, values entered for the deleted attribute do not apply to the new attribute.

====Commands====
The commands are the same as those described in the [[#Commands|Commands]] section.

====Updating entity type references====

Press PF11 to begin updating the entity type references. A screen similar to the following is displayed. The screen lists the relationships defined for the entity type by the administrator or by Model 204 (in the case of standard entity types). You can add references to standard entity types, but you cannot modify those provided by the system.

[[File:Dictionary_fig6-6.png]]

====Input====

Dictionary/204 displays all the references defined for the specified entity type on a screen like the previous one. You can modify the references by following the directions on the screen:
<ul>
<li>Type over existing entity type names and relationship names, using the Erase EOF key or blank characters to delete extra characters.</li>
<li>Specify a new related entity type and named or cross-referenced relationship on a blank line.</li>
<li>Maximum length for an entity type name is 20 characters. </li>
<li>Specify a named relationship by adding a reference name in the space provided following the tilde (~). The maximum length for a relationship name is 19 characters. Leave the space following the tilde blank for cross-references. </li>
</ul>

Note: Typing over an existing reference deletes the current reference; it does not simply change the name or entity type that makes up the existing reference.

The commands are the same as those described in the [[#Commands|Commands]] section. 

====Deleting an entity type====

Dictionary/204 displays this screen when you select the following option from the Entity Type Maintenance menu:
Delete Entity Type

This function enables you to delete an entity type from the dictionary. Deleting an entity type does not automatically delete the entry records for that entity type from the dictionary, but it does make the entries inaccessible. First delete the individual entries from the dictionary by using the Documentation facility. If you delete the entity type first, users cannot specify that the entries are to be deleted.

You might want to delete an entity type:
<ul>
<li>If the entity type is no longer useful.</li>
<li>If you want to make the entries for the entity type inaccessible for an indefinite period. (Redefining the entity type at a later time makes the entries accessible again.) </li>
</ul>

Before you actually delete an entity type, Dictionary/204 displays the current attributes and related entity types for the entity type to be deleted. Dictionary/204 also tells you how many entries are currently defined in the dictionary for the entity type being deleted. The following screen provides an example.

[[File:Dictionary_fig6-7.png]]

====Input====

After Dictionary/204 displays the attributes and references for the entity to be deleted, it prompts:
Press Enter to Continue:
Press the Enter key to advance to the confirmation screen.

====Confirming the deletion====

Dictionary/204 displays the following Confirmation screen when you press Enter, after viewing the attributes and relationships for the entity to be deleted. The screen tells you how many entries of the type to be deleted are stored in the dictionary.

You must either confirm the deletion by pressing PF6 (DELete), or abort the deletion by pressing PF3 (QUIt).

[[File:Dictionary_fig6-8.png]]

The previous sample screen indicates that eight REPORT entries are defined in the dictionary. When you delete the REPORT entity type from the dictionary, you delete the definition of attributes and relationships for this entity. Report entries defined by users through the Documentation facility remain in the dictionary database, but they become inaccessible. 

If you press PF6, Dictionary/204 displays the Entity Type DELETED message on the message line of the Entity Type Maintenance menu.

If you press PF3, Dictionary/204 cancels the delete operation and returns you to the Entity Type Maintenance menu.

====Displaying entity type and path report====

The Entity Type Maintenance menu enables you to display the attributes and relationships that have been assigned to the various entity types -- both system-controlled entity types and those created by the dictionary administrator. By selecting the Entity Type and Path Report option, you can:
<ul>
<li>Display the definition of a single entity type</li>
<li>Display the definitions of all entity types</li>
<li>Optionally display path information for either of the above</li>
<li>Optionally route the information to a printer or specified file </li>
</ul>

The following sample Entity Type Maintenance menu shows the input for a report on the REPORT entity type, including path information, sent to the terminal.

[[File:Dictionary_fig6-9.png]]

====Input====
To respond to this menu, type the name of the entity type or ALL in response to:
Entity Type: 
The default value is Y for:
Path Information for Report: 
Type N over the default value, if you do not want a report on the paths in which the entity type occurs.
Normally, Dictionary/204 sends reports to your terminal. You can direct the output to a different destination, however, by typing Y over the default value of N at the following prompt:
Route to Output File: 
Your Output Destination default value is specified in your ACCOUNT entry. (The output destination can be a printer or a specified file.) To change your output destination, type a new value for:
Output Destination 
You can specify a name of 1 to 30 characters.
The default value is OUTFILE. The system uses this file to send output to a destination other than your terminal.

====Output====

Dictionary/204 displays a report similar to the following when you select the option from the Entity Type Maintenance menu:
Display Entity Type and Path Report 

The sample report is based on the definition of the SUBSYSTEM entity type and a hypothetical path relationship.

A dictionary entity type definition contains a list of the attributes and relationships established for an entity type. It does not include the individual entry names and attribute values. (The Inventory Report, described in [[#Printing a dictionary inventory|Printing a dictionary inventory]], enables you to display the existing entries for each entity type, along with their attributes and relationships.)

A dictionary path definition contains a list of the entity types that comprise the relationship path, as shown on the second screen of the sample report.
[[File:Dictionary_fig6-10.png]]
[[File:Dictionary_fig6-11.png]]


If Dictionary/204 displays the > prompt at the bottom of the screen, press the Enter key to advance to the next screen, or to return to the Entity Type Maintenance menu. (The prompt (>) does not appear in the sample above, because the report was sent to a printer rather than to a terminal.)

==Path maintenance==

The previous sections explained how to use the functions available from the Entity Type Maintenance menu. This section shows you how to use a function available from the [[#Using the Dictionary/204 Administration main menu|Dictionary Administration main menu]].

Dictionary/204 displays this screen when you select the following option from the Dictionary Administration main menu:
Path Maintenance 

Path relationships are defined in [[Dictionary/204 overview#Path relationships|Path relationships]] and are described further in [[#Displaying a path definition|Displaying a path definition]]. 

[[File:Dictionary_fig6-12.png]]
This menu provides the following capabilities (numbered items correspond to menu options):

<ol>
<li>Displaying all path relationships along with their assigned path numbers</li>
<li>Defining a maximum of eight entity types as a path</li>
<li>Updating the definition of existing path relationships</li>
<li>Deleting the definition of a path relationship </li>
</ol>

====Input====

You can select an option from this menu by typing a numbered choice at the Enter Number: prompt, and then pressing Enter.

If you want to update or delete a path, you must type its number at the prompt:
Path Number: 

This prompt applies only to updating and deleting. Path numbers are assigned automatically and sequentially by the system. To determine the number of a path, use the Display Path Definition option from the Path Maintenance menu.

====Commands====

To issue a command, press the assigned PF key or type the command name at the prompt (===>) and press Enter.
<table>
<tr class="head">
<th>Key</th>
<th>Command</th>
<th>Meaning</th>
</tr>
<tr>
<td>PF1</td>
<td>HELp</td>
<td>Provides the online HELP text for this screen. You can read the HELp text and exit from the last screen by pressing Enter.</td>
</tr>
<tr>
<td>PF3</td>
<td>QUIt</td>
<td>Terminates the Path Maintenance function. The system returns you to the Dictionary Administration main menu.</td>
</tr>
<tr>
<td>Enter</td>
<td> </td>
<td>Processes your menu selection.</td>
</tr>
</table>
====Defining paths: in theory====

Before examining the interface for defining paths, it is important to examine why paths are defined and how to ensure their usefulness.

As defined in [[Dictionary/204 overview#Path relationships|Path relationships]], a path relationship is one that is derived from other relationships. Paths increase the reporting capabilities of the dictionary by enabling it to show indirect relationships among as many as eight entity types and their entries.

Paths can be based on cross-references, as shown in the following figure.

Path relationship - Example 1
[[File:Dictionary_fig6-13.png]]


This relationship allows users to obtain reports on relationships between PROCEDURE and FIELD entries, even though there is no direct relationship defined between these two entity types.

Paths can also be based on named references, as shown in the following figure. 

Path relationship - Example 2

[[File:Dictionary_fig6-14.png]]


This relationship allows reports on existing references between FILE and USER entries. (See [[Dictionary/204 reports#Selecting a report option|Selecting a report option]] for an example of how to request such reports.)

In defining path relationships, the dictionary administrator must anticipate the users needs, because the defined paths must support the users' reporting requirements. But keep in mind the following guidelines:
<ul>
<li>
Paths can be defined between any valid entity types, even if no existing relationship exists at all between certain entity types in the path. However, such a "bogus" path does not enhance the users' reporting capabilities. Paths, therefore, must be derived from existing relationships defined for the relevant entity type definitions.</li>
</ul>

If no relationship exists between two consecutive entries, the report path is broken. The report does not "wrap around" from the last entity type in the path to the first.

See [[#Adding a path definition|Adding a path definition]] for instructions on defining paths.
<ul>
<li>When named relationships are part of a path, users can obtain reports that entity type B is related to entity type C even if the unidirectional, named relationship flows from C to B. Consider this example:</li>
</ul>
A <---> B <--- C ---> D 

If a user asks (using Dictionary Reports) which entities are related to B, the report yields A, C, and D. A Dictionary Reports query asks only if a relationship exists along a path, but not what type it is or what direction is implied by the relationship. 

====Displaying a path definition====

The following screen is displayed when you select the following option from the Path Maintenance menu:
Display Path Definitions

This screen displays a list of all the paths currently defined in the dictionary, along with their identifying path numbers. These numbers are used on the Path Maintenance menu to specify the particular path to be changed or deleted. Paths are numbered sequentially; when paths are deleted, the next defined path takes the number of a previously deleted path.

Always display a path and its number before updating or deleting it; do not assume that you know the correct and current number of a path without checking.

[[File:Dictionary_fig6-15.png|468px]]

====Input====

If Dictionary/204 displays the > prompt, press the Enter key to advance to the next screen. After all the paths have been displayed, press Enter to return to the Path Maintenance menu.

====Adding a path definition====

Dictionary/204 displays the following screen when you select the following option from the Path Maintenance menu:
Add Path Definition

Use this screen to specify a new path for the entities in your dictionary.

[[File:Dictionary_fig6-16.png|468px]]

====Input====

Dictionary/204 prompts you to describe the path by specifying up to eight entity types that comprise it. Enter the entity types, one per line, in response to the
--> prompts. Use the tab keys to position the cursor at the next or preceding prompt.

You must list the entity types in the order in which Dictionary/204 is to proceed in following the path. If no relationship exists between two sequential entries, the reporting path is broken, as explained in [[#Defining paths: in theory|Defining paths: in theory]].

To indicate that the path is complete, press PF12 or issue the END command.

Dictionary/204 checks the entity types that you have specified to ensure that definitions for these entity types exist.

If an entity type is not valid, an angle bracket tag (<) is displayed in column 80 of the line containing the invalid entry. An error message is displayed on the message line (the line below the command prompt). Correct the entity type, using the ERASE EOF key to delete the entered value.

Dictionary/204 also displays an error message if you define a path that is already defined in the dictionary.

If no errors are found, Dictionary/204 adds the path to the Dictionary/204 and displays the Path Maintenance menu with the message:
The reference path has been defined. 

To cancel the add operation, press PF3, or issue the QUIT command at the command prompt (===>).

====Changing a reference path====

Dictionary/204 displays the following screen when you specify the number of the path on the Path Maintenance menu, and select the following option from the Path Maintenance menu:
Update Path Definition 

Use this screen to change a reference path by replacing one or more of the entity types that make up the path.

Dictionary/204 displays the entity types that comprise the path, as shown in the following sample screen.

[[File:Dictionary_fig6-17.png|468px]]

====Input====

To modify a path, type over the display of the existing entity types, or use the ERASE EOF key to delete the display.

If you specify an entity type that is not defined in the Dictionary/204, an angle bracket tag (<) is displayed in column 80 on the line containing the erroneous entry. An error message is displayed on the message line (the line below the command line). You can then either correct the entry or cancel the operation by pressing PF3.

Dictionary/204 also displays an error message if you attempt to define a path already defined in the dictionary.

To indicate that the path is updated to your satisfaction, press PF12 or issue the END command. The update is stored, and the system returns you to the Path Maintenance menu.
To cancel the update, press PF3. Dictionary/204 returns you to the Path Maintenance menu. 

====Deleting a reference path====

Dictionary/204 displays the following screen when you specify the number of the path on the Path Maintenance menu and select the following option from the Path Maintenance menu:
Delete Path Definition 

To determine the correct path number, use the Display Path Definition option from the Path Maintenance menu.

Before Dictionary/204 permits you to delete the path from the dictionary, it displays the entity types that comprise the path, as shown on the sample screen.

[[File:Dictionary_fig6-18.png|468px]]

====Input====

Press PF6 to delete the path, or cancel the deletion by pressing PF3. Once you have deleted the path, it cannot be recovered. All path numbers are resequenced after a deletion. 

==Facility administration==

The previous sections described functions available from the Path Maintenance menu. This section describes the Facility Administration function available from the Dictionary Administration main menu (described in [[#Using the Dictionary/204 Administration main menu|Using the Dictionary/204 Administration main menu]]). This function enables data administrators to control various options and parameters that affect the operation of their respective facilities.

Dictionary/204 displays the following screen when you select the following option from the Dictionary Administration main menu:
Facility Administration 

[[File:Dictionary_fig6-19.png|468px]]

The Facility Administration menu displays the options for the administration of those facilities installed at your site.

This menu provides the following options (numbered items correspond to menu choices):

<ol>
<li>Adding, deleting, or renaming procedure names on a list of user-written procedures that produce reports</li>
<li>Determining command options and setting defaults for the File Management facility</li>
</ol>

====Input====

To select an option from this menu, type the number of your choice after the Enter Number: prompt and then press the Enter key.

To terminate the Facility Administration function and return to the Dictionary Administration main menu, press PF3 or issue the QUIT command. You can read the HELP text for this screen by pressing PF1 or by issuing the HELP command. Press Enter to read the HELP text and to exit from the last help screen.

====Dictionary Reports administration====

Two distinct tasks comprise the administration of Dictionary Reports:
<ul>
<li>Maintaining a list of customized (also called "user-written") reports through the Facility Administration facility</li>
<li>Creating customized reports, which can be accomplished only from the Model 204 command prompt </li>
</ul>

This section describes both tasks.

The following screen is displayed when you select the following option from the Facility Administration menu:
Dictionary Reports Administration 

Use this screen to add, rename, or delete a procedure name from the list of user-written procedures in the Dictionary Reports facility (DICTREPORT).

[[File:Dictionary_fig6-20.png|468px]]

====Input====

The Facility Administration facility prompts you to add, rename, or delete the procedure names for user-written reports. When you use this function, the names on the list displayed by the Dictionary Reports facility change. However, the names of Model 204 procedures for those reports are not affected. To change the name of the actual procedures, you must modify the procedure stored in TABLE D of the D204RPT file.

To add a procedure name:

<ol>
<li>Type an X in the prefix area for the Add Procedure Name prompt.</li>
<li>Use the tab or cursor keys to advance the cursor to the Enter Procedure Name: prompt. </li>
<li>Type the name of the procedure you want to add. </li>
<li>Press PF6 or issue the EXECUTE command.</li>
</ol>

To rename a procedure:
<ol>
<li>Type an X in the prefix area for the Rename Procedure prompt. </li>
<li>Use the tab or cursor keys to advance the cursor. </li>
<li>Respond to the Enter Procedure Name: prompt by typing the name of the procedure you want to rename. </li>
<li>Advance the cursor to the prompt Rename Procedure to:, and type in the new name of the procedure. </li>
<li>Press PF6 or issue the EXECUTE command to process the rename.</li>
</ol>
To delete a procedure name:

<ol>
<li>Type an X in the prefix area for the "Delete procedure name" prompt.</li>
<li>Respond to the Enter Procedure Name prompt. </li>
<li>Press PF6 or issue the EXEcute command to proceed to the following confirmation screen.
[[File:Dictionary_fig6-21.png|468px]]
</li>
<li>
The name of the procedure is supplied by the system. Press PF6 or issue the DELETE command to complete the deletion, or press PF3 to cancel the deletion.</li>
</ol>

If you confirm the deletion, the procedure name no longer appears on the list of user-written procedures that the Dictionary Reports facility displays. However, the procedure remains in the D204RPT file, though it is no longer available to users. If you want to delete the procedure, you must remove it from the D204RPT file using Model 204 commands.

====Creating customized reports====

The administrator can create customized reports to control the selection of dictionary records and to organize the reports according to the needs of your installation. For example, you might want a report that shows duplicate data records in your dictionary. No standard report shows that information. This section demonstrates how the dictionary administrator can write and name a customized (or user-written) report. Further on in this section there is an example of a procedure that produces a customized report.

====Dictionary internal structure====

Two types of records are stored in METADATA. Control records (identified by REC=X field=value) are the template for each entity type; and entry records (identified by REC=D field=value) are the actual entity occurrences with data. The following example shows a METADATA control record for an ACCOUNT entity type:

REC =X
ENTITY =ACCOUNT
REQ =NAME
REQ =CREATE DATE
REQ =LAST UPDATED
REQ =UPDATED-BY
REQ =DES
SYS.ATTRIB =OUTPUT FILE
SYS.XREF =FACILITY
SYS.REFTYPE =~USES
ATTRIB =KEYWORD
ATTRIB =ALIAS
ATTRIB =PROC FILE NAME
XREF =VIEW
REFTYPE =~OWNS
XREF =VIEW
REFTYPE =~UPDATES 

The REQ values specify required attributes. SYS.ATTRIB values specify attributes controlled by Dictionary/204 facilities and ATTRIB values specify other attributes maintained through the DOCUMENT facility.

Within the dictionary system, the values of REQ, SYS.ATTRIB, and ATTRIB become field names in METADATA. Entry occurrences are stored using the value of the attribute as the field name. The value with that field name becomes the character string the user supplies during an "add entry" or "change entry" operation.
XREF and REFTYPE and SYS.XREF and SYS.REFTYPE occur in pairs. XREF contains the values of entity types (one per XREF) and REFTYPE contains the name of the reference type to the entity type in the corresponding XREF field. A tilde (~) by itself indicates a cross-reference. The tilde must also prefix any reference name.
Values from XREF and REFTYPE are displayed on the screen to prompt the user for references to other entries. SYS.ATTRIB, SYS.XREF and SYS.REFTYPE values are maintained through specific Dictionary/204 facilities.

====Sample Customized Report====
<nowiki>*****************************************************************
* *
* PROCEDURE NAME..........: USRN.DUPREPT *
* VERSION.................: 1 *
* PROCESSING SUMMARY......: SAMPLE USER WRITTEN REPORT, IT WILL *
* READ METADATA AND LOOK FOR DUPLICATE DATA RECORDS AND *
* DISPLAY RESULTS, IT THEN RETURNS TO USER WRITTEN REPORT *
* MENU IN THE DICTREPORT FACILITY *
* WRITTEN BY..............: RICK WAHLBERG *
* modifying authors *
* CALLED FROM.............: DIRN.USERREPT *
* CALLS TO................: N/A *
* INCLUDES................: N/A *
* INCLUDED BY.............: N/A *
* GLOBAL VARIABLES READ...: N/A *
* GLOBAL VARIABLES SET....: N/A *
* LOCAL VARIABLES READ....: N/A (used for subroutine procs *
* LOCAL VARIABLES SET.....: N/A (to describe arguments *
*****************************************************************

IF PAPR=Y,DIRO.DDRPTS

*
BEGIN
*
VARIABLE.DECLARATIONS:
*
%ENTITY IS STRING LEN 20
%NAME IS STRING LEN 255
%CURREC IS FLOAT
%DUP.FOUND IS FLOAT
%RETRY IS FLOAT
%CHOICE IS STRING LEN 70
%INDEX IS FLOAT

ERROR.MESSAGES:
%GFMSG IS STRING LEN 50
%GFMSG = 'GLOBAL VARIABLE TABLE IS FULL.'
%USR001 IS STRING LEN 60
%USR001 = 'USR001 PA1 ENTERED ON SCREEN, REPORT IS CANCELLED'
%USR002 IS STRING LEN 60
%USR002 = 'USR002 UNRESOLVED ENQUEUE CONFLICT, REPORT HALTED.'

***********************************************************************
* ON UNIT DECLARATIONS
***********************************************************************
ON.ATTN:
ON ATTN
PRINT %USR001
JUMP TO RETURN.TO.MENU
END ON
ON.FIND.CONFLICT:
ON FIND CONFLICT
%RETRY = %RETRY + 1
IF %RETRY > 10 THEN
PRINT %USR002
AUDIT %USR002
JUMP TO RETURN.TO.MENU
ELSE RETRY
END IF
END ON

MAIN.LOGIC:

IN METADATA CLEAR LIST XRECS

FD.XREC: IN METADATA FD REC = X
END FIND
PLACE RECORDS IN FD.XREC ON LIST XRECS
RELEASE RECORDS IN FD.XREC

FR.FD.XREC: FOR EACH RECORD ON LIST XRECS
%ENTITY = ENTITY
FD.DREC: IN METADATA FD REC = D AND ENTITY = %ENTITY
END FIND

IN METADATA CLEAR LIST DRECS
PLACE RECORDS IN FD.DREC ON LIST DRECS
RELEASE RECORDS IN FD.DREC
FR.FD.DREC: FOR EACH RECORD ON LIST DRECS

%NAME = NAME
FD.DUP.DREC: IN METADATA FD REC=D
ENTITY=%ENTITY
NAME=%NAME
END FIND
CT.FD.DUP.DREC: CT FD.DUP.DREC
IF COUNT IN CT.FD.DUP.DREC > 1 THEN
%DUP.FOUND = %DUP.FOUND + 1
SKIP 2 LINES
PRINT ' DUPLICATE RECORDS ON METADATA FOUND ' AT 10
PRINT 'ENTITY TYPE IS: ' AND %ENTITY AND ' NAME IS: ' AND -
%NAME
FR FD.DUP.DREC
%CURREC = $CURREC
SKIP 1 LINE
PRINT 'RECORD NUMBER: ' AND %CURREC
PRINT ' CREATE DATE IS' AND CREATE DATE
PRINT ' LAST UPDATED ' AND LAST UPDATED
PRINT ' UPDATED BY ' AND U'PDATED-BY'
END FOR
REMOVE RECORD FROM LIST DRECS
END IF
RELEASE RECORDS IN FD.DUP.DREC
END FOR
END FOR
NUMBER.DUPS:
SKIP 2 LINES
PRINT 'NUMBER OF DUPLICATES FOUND IS: ' AND %DUP.FOUND
RETURN.TO.MENU:
** NEXT STATEMENT WILL CAUSE RETURN TO USER WRITTEN REPORTS MENU

%CHOICE = 'DIRN.USERREPT'
IF $SETG('COMM',%CHOICE) THEN PRINT %GFMSG
END IF

END </nowiki> 

====File Management options====

The following screen is displayed when you select the following option from the Facility Administration menu:
File Management Options 

Use this screen to set command options and defaults for the File Management facility.

[[File:Dictionary_fig6-22.png|468px]]

====Input====

This screen enables you to determine the File Management command options supported at your site and to define the defaults for these options.

Type an X in the left column, to select the options that you want to make available at your site. Type an X in the column to the right of the option that you want to be the default. The default must be one of the options selected. (The previous screen shows the system default values.) 
<table>
<tr class="head">
<th>Option</th>
<th>If you choose this option...</th>
</tr>
<tr>
<td>Active-Immediate Execution</td>
<td>Dictionary/204 and Model 204 are synchronized and any change you make in the dictionary files is also made in the Model 204 database at the same time.</td>
</tr>
<tr>
<td>Active-Delayed Execution</td>
<td>File management facility updates the command's status as "pending." These pending commands are implemented later while running the batch version of File Management (DDFIMCMD).</td>
</tr>
<tr>
<td>Inactive: Generate Commands Only</td>
<td>Dictionary/204 generates commands, but you must run them independently.

If you choose this option, you must supply either the name of a directed output file (called a USE file, such as OUTFILE), or you must indicate that you want the commands stored in a procedure file. Select a procedure file by entering a file name at the Proc filename: prompt. 
</td>
</tr>
</table>

The system manager can prevent users from issuing commands against files from outside of Dictionary/204 by setting the <var>[[SYSOPT parameter|SYSOPT]]</var> parameter to the appropriate value.

Setting the parameter to prevent command execution outside of Dictionary/204 precludes selecting the Inactive execution mode. 

==Security administration==

The dictionary administrator uses the Security Administration function on the Dictionary Administration menu to specify the privileges of Dictionary/204 users. The administrator defines the privileges through the user's ACCOUNT entry in the dictionary. (The Dictionary/204 installation procedure gives the dictionary administrator user privileges for all the Dictionary/204 facilities.)

A user's privileges are authorized by facility. No distinction is made between update privileges and read-only privileges. Access to a facility implies the privileges to do whatever that facility allows. Dictionary/204 users, however, are limited by their Model 204 privileges, which override their ability to use certain features of the Dictionary/204 facilities. (For specific examples, see [[Dictionary/204 logon and commands#Security considerations|Security considerations]].)

====PUBLIC account====

During installation, an ACCOUNT entry named PUBLIC is defined by Dictionary/204. The PUBLIC account, as its name implies, shares its "user" privileges with all Dictionary/204 users. For example, if the administrator gives PUBLIC privileges to use Dictionary Reports, then all accounts become Dictionary Reports users.

The ACCOUNT entity type has an OUTPUT FILE attribute, indicating the device (usually a printer) to which output is sent when the user does not want it sent to the terminal. The default value for this attribute is the same as the default value of the PUBLIC account, which is set at installation. The value can be modified by the dictionary administrator by updating the PUBLIC account through the Security Administration screen. Users can also override the default value when using the Dictionary/204 facilities.

The administrator assigns user privileges for the PUBLIC account prior to assigning privileges for the accounts of individual users. This means PUBLIC facilities are assigned to each user automatically on the "Facility Profile" for each individual account (see the screen in [[#Defining, updating, and deleting ACCOUNT privileges|Defining, updating, and deleting ACCOUNT privileges]]).

====Selecting security administration====

Dictionary/204 displays the following screen shown when the dictionary administrator selects the Security Administration function from the Dictionary Administration menu:

[[File:Dictionary_fig6-23.png]] 

This menu enables the administrator to define (add) a new account, update the privileges of an existing account, or delete an existing account.

The previous menu shows a sample selection: updating the privileges of the user whose account name is JLSMITH. This function works by providing an interface (see the following screen) that updates the ACCOUNT entry with the name JLSMITH.

====Input====

To make a selection from the menu, enter the number of your choice at the Enter Number: prompt and type the name of the account to be defined, updated, or deleted at the following prompt: Account: 

If the administrator is assigning privileges to the PUBLIC account, for example, the name PUBLIC appears following the Account: prompt.

You can process your menu selection by pressing Enter, which causes the following Security Administration screen to be displayed. You can also quit this facility by pressing PF3 or request HELP text by pressing PF1 (or issuing the HELP command). 

====Defining, updating, and deleting ACCOUNT privileges====

Dictionary/204 displays a screen similar to the following when you select one of the options from the preceding menu.

[[File:Dictionary_fig6-24.png]] 

The sample screen shows 12 facilities for which the account JLSMITH might be assigned privileges. You can scroll forward to display more facilities by pressing PF8.

JLSMITH is the name that was entered at the Account: prompt on the previous menu. The heading on the screen shows that the update function was selected. When the delete function is selected, the screen heading reads "Deleting Security Profile for <<var class="term">ACCOUNT name</var>>." When the add function is selected, the screen heading reads "Security Profile for <<var class="term">ACCOUNT name</var>>."

In the prefix area, an X marks those facilities and products for which the ACCOUNT has user privileges. Facilities designated as PUBLIC can be used by all accounts. A "Not Installed" message (as shown in column two of the screen) indicates that the corresponding facility has not been installed with your Dictionary/204 product.

====Input====

To indicate that an ACCOUNT has user privileges for a facility, type an X in the prefix area:
X DICTREPORT 

To revoke facility privileges from the ACCOUNT, erase the X by blanking it out with the space bar or the Erase EOF key. Use the tab keys to move the cursor from one prefix line to the next.

If a facility is available to all Dictionary/204 users, the following word appears in column three, as shown in the sample screen, and an X appears in the prefix area for that facility:
PUBLIC 

As noted earlier, if the administrator has given the PUBLIC account user privileges for a facility, that privilege extends to all Dictionary/204 users and the word PUBLIC appears to the right of the facility (as shown on the screen).

To specify an alternative output destination (other than the user's terminal), type the device or file name at the prompt: 
Default Output Destination: 

The alternative output destination is an option for the Dictionary/204 user when output to the terminal is not desired. This value is the default. (The system sets the default destination to the value of the OUTPUT FILE attribute specified for the PUBLIC account.) Normally, the user can change the output destination when using a facility. The Output Destination name must be from 1 to 30 characters. 

After filling in the screen, you can implement your selection by pressing PF12 (or issuing the END command), or cancel the request by pressing PF3 (or issuing the QUIT command).

When the function you have selected on the menu has been processed, Dictionary/204 returns you to the Security Administration menu and displays the following message on the message line:
Account <<var class="term">ACCOUNT name</var>> has been <<var class="term">function</var>> 

====Commands====

To issue a command, press the assigned PF key or type the command name at the prompt (===>) and press Enter.

<table>
<tr class="head">
<th>Key</th>
<th>Command</th>
<th>Meaning</th>
</tr>
<tr>
<td>PF1</td>
<td>HELp</td>
<td>Provides online HELP text for this screen. You can read through a series of HELP screens, or exit from the last screen in the series, by pressing any key.</td>
</tr>
<tr>
<td>PF3</td>
<td>QUIt</td>
<td>Terminates this function. You return to the Security Administration menu.</td>
</tr>
<tr>
<td>PF6</td>
<td>DELete</td>
<td>Deletes an account entry. This option is displayed only if the delete function is selected from the Security Administration menu.</td>
</tr>
<tr>
<td>PF7</td>
<td>BACKward</td>
<td>Scrolls backward through the list of facilities. This option appears at the bottom of the screen only if you have scrolled forward.</td>
</tr>
<tr>
<td>PF8</td>
<td>FORward</td>
<td>Scrolls forward through the list of facilities. This option appears at the bottom of the screen if there are more facilities to be displayed.</td>
</tr>
<tr>
<td>PF12</td>
<td>END</td>
<td>Implements the selection on the screen. You return to the Security Administration menu.</td>
</tr>
</table>

==Printing a dictionary inventory==

You can request a formatted, printed report of the entire contents of the dictionary. This facility reports on the attributes and references of all entries of each entity type. 
Note: The processing time required to format and print the dictionary inventory can be quite long, depending upon the complexity and number of dictionary entries. 
<ol>
<li>
Select the following option from the Dictionary Administration menu:
Inventory Report 

The following screen appears:
[[File:Dictionary_fig6-25.png]]
The screen shows the default output device. The Inventory Report is always sent to a printer; it cannot be displayed on your terminal.
</li>
<li>To change the printer, type over the default value with the device name of another printer.
</li>
<li>When you are satisfied with the output device, press Enter to proceed.
<ul>
<li>To cancel before printing starts, press PF3 to return to the Dictionary Administration menu.</li>
<li>To cancel after printing starts, press PA1.</li>
</ul></li>
</ol>

Upon completion of the report, the system returns you to the Dictionary Administration menu, where the following message is displayed:
The Inventory Report has been sent to the output device


A sample entry from an Inventory Report follows.

The Dictionary Inventory Report is printed in sorted order. Each entry begins on a new page, as shown in the sample.
[[File:Dictionary_fig6-26.png]] 

[[File:Dictionary_fig6-27.png]] 

==Duplication correction utilities==

Dictionary/204 provides a set of utilities for the dictionary administrator to use for verifying data integrity. These utilities are described in detail in this section. Use the utility to [[#Correcting duplicate entries or entity types|correct duplicate entity types or entries]] if any of the following error messages are generated during the operation of Dictionary/204:
<ul>
<li>Dictionary Administration facility message:

DIA102 Duplicate entity types found, contact your
Dictionary Administrator. 
</li>
<li>Documentation facility messages:

DOC013 Duplicate entries found for the tagged name.
Contact System Administrator.
DOC015 Duplicate control records for this entity type.
</li>
<li>Dictionary Reports facility message:
DUPLICATE ENTRIES WERE FOUND FOR
ENTRY: RECORD_ONE
ENTITY: DUPRECORD
REPORT THIS TO YOUR DICTIONARY ADMINISTRATOR.
THIS REPORT HAS BEEN CANCELLED. 
</li>
</ul>

The Dictionary administrator must supply the entity type and entry name for the entry in error when taking corrective action, as described in the following section.

===Correcting duplicate entries or entity types===

Dictionary/204 provides a special routine, called DICN.CTRLDUP, which can be used to eliminate duplicate entries or entity types. This routine is distributed in the form of a Model 204 SOUL procedure that resides in the Dictionary/204 file M204PROC. 
To run DICN.CTRLDUP:
<ol>
<li>
Stop Dictionary/204 and all its facilities, as described in [[Dictionary/204 administration#Starting and stopping the Dictionary/204 subsystems|Starting and stopping the Dictionary/204 subsystems]].</li>
<li>Open the Dictionary/204 M204PROC file.</li>
<li>Run the procedure, using the Model 204 INCLUDE command (INCLUDE or I):
> OPEN M204PROC
> I DICN.CTRLDUP 
</li>
<li>Model 204 automatically opens the Dictionary/204 METADATA file. The METADATA password prompt is displayed after the file is opened. Enter the password at the prompt or press Enter.</li>
<li>The procedure prompts you for the entity type (for example, FILE) and entry name (for example, PAYROLL) of the dictionary entry for which the duplicate record was found:
<nowiki>*** FILE METADATA OPENED
??METADATA PASSWORD
$$ENTER ENTITY TYPE VALUE: > FILE
$$ENTER NAME IF FOR ENTRY RECORD: > PAYROLL </nowiki> 

Note: If a password is required, you must supply an update password. 
</li>
<li>
If you are correcting a duplicate entity type, press Enter in response to the ENTER NAME IF FOR ENTRY RECORD prompt.</li>
<li>
DICN.CTRLDUP displays the duplicate records, as shown in the following [[#DICN.CTRLDUP example|example]]. Each entry is identified with a DDSTAT number. After the display has been completed, enter the DDSTAT number of the entity or entry record that you want to preserve:
$$ENTER DDSTAT VALUE OF ENTRY YOU WISH TO KEEP: 
</li>
<li>
The procedure deletes the duplicate record and redisplays the record that is being preserved. You are prompted for the following:
$$DO YOU WISH TO CONTINUE (Y/N)? 

Enter N to return to command level; enter Y to continue.
</li>
</ol>

If the specified duplicate record cannot be found, DICN.CTRLDUP displays one of the following messages:
<nowiki>**** NO DUPLICATES WERE FOUND FOR ENTITY
**** REQUEST FINISHED

*** NO DUPLICATES WERE FOUND FOR NAME ENTITY
**** REQUEST FINISHED </nowiki>

In this case, DICN.CTRLDUP displays the existing entity type or entry.

====DICN.CTRLDUP example====
The following example uses DICN.CTRLDUP:
 STOP DICTIONARY

OPEN M204PROC
I DICN.CTRLDUP

ENTER ENTITY TYPE VALUE: > WIDGET
ENTER NAME IF FOR ENTRY RECORD: > SNX13
**** ENTRY RECORD FOLLOWS:
ENTITY=WIDGET
NAME=SNX13
CREATE DATE=19 MAR 82
DDSTAT=1

**** ENTRY RECORD FOLLOWS:
ENTITY=WIDGET
NAME=SNX13
CREATE DATE=19 MAR 82
DDSTAT=2

**** ENTRY RECORD FOLLOWS:
ENTITY=WIDGET
NAME=SNX13
CREATE DATE=19 MAR 82
LAST UPDATED=22 MAR 82
KEYWORD=WID
DDSTAT=3

$$ENTER DDSTAT VALUE OF ENTRY YOU WISH TO KEEP: >3

**** THIS IS THE CURRENT ENTRY FOR SNX13 WIDGET: ENTITY=WIDGET
NAME=SNX13
CREATE DATE=19 MAR 82
LAST UPDATED=22 MAR 82
KEYWORD=WID

*** REQUEST FINISHED ***

$$DO YOU WISH TO CONTINUE (Y/N)? > N 

Note: A sample report is provided (USRN.DUPREPT) that reports on duplicate entries in the dictionary. It is available as a customized report in Dictionary Reports (see [[Dictionary/204 reports#Selecting a user-written (customized) report|Selecting a user-written (customized) report]]). 

===Correcting duplicate relationships===

Dictionary/204 provides a special routine, called DICN.CLEANLNK, to eliminate duplicate relationships in the DATALINK file. This routine is distributed in the form of a Model 204 SOUL procedure that resides in the Dictionary/204 file, M204PROC. 
To run DICN.CLEANLNK:
<ol>
<li>Stop Dictionary/204 and all its facilities, as discussed in [[#Starting and stopping the Dictionary/204 subsystems|Starting and stopping the Dictionary/204 subsystems]].</li>
<li>Open the Dictionary/204 files DATALINK and M204PROC.</li>
<li>Run the procedure using the Model 204 INCLUDE command (INCLUDE or I):
> OPEN DATALINK
(enter update password if secured)
OPEN M204PROC
(enter password if secured)

> I DICN.CLEANLNK 
</li>
</ol>

DICN.CLEANLNK displays the current number of entries found in DATALINK:
THERE ARE # REFERENCES CURRENTLY STORED. 

The procedure then deletes any duplicate reference entries found.
At the completion of the request another count is displayed:
THERE ARE # RESULTING REFERENCES. 
====DICN.CLEANLNK example====
The following example uses DICN.CLEANLNK:
<nowiki>> O DATALINK
*** M204.0620: FILE DATALINK OPENED
> O M204PROC
*** M204.0620: FILE M204PROC OPENED
> I DICN.CLEANLNK
THERE ARE 1293 REFERENCES CURRENTLY STORED.
THERE ARE 1289 RESULTING REFERENCES.
*** M204.0172: END OF UPDATE 7 at 10:29:57.45
</nowiki>

==See also==
{{Template: Dictionary/204 topic list}}

[[Category: Dictionary/204]]

APSYSEC parameter

2025-05-09T22:10:56Z

JDamon: /* Description */

{{Template:APSYSEC parameter subtitle}}

==Summary==
<dl>
<dt>Default value
<dd>X'00'
<dt>Parameter type
<dd>System
<dt>Where set
<dd>User 0 CCAIN parameters
<dt>Related products
<dd>Prior to Version 7.5 of [[Model 204]], this parameter required the <var class="product">SirSafe</var> product.
<dt>Introduced
<dd><var class="product">[[Sirius Mods]]</var> 6.7
</dl>

==Description==
The <var>APSYSEC</var> parameter makes it possible for a system manager to enter <var>[[SUBSYSMGMT]]</var> and <var>DICTADMIN ([[Dictionary/204 administration]])</var> without
prior authorization. It also allows a system manager to <var>[[START command: Starting an application subsystem|START]]</var>, <var>[[STOP command: Stopping an application subsystem|STOP]]</var>, <var>[[DEBUG command|DEBUG]]</var>, or <var>[[TEST command|TEST]]</var> any PUBLIC or SEMI-PUBLIC subsystem (not PRIVATE), without having to
add the system manager to the [[SCLASS]] authorized to do these things.

For versions of Model 204 prior to 7.5, setting this parameter has no effect at sites not authorized for [[SirSafe]].

The <var>APSYSEC</var> parameter is a bitmask parameter where the bits mean:
<table class="thJustBold">
<tr><th>X'01'</th>

<td>System managers are allowed to enter SUBSYSMGMT and DICTADMIN without prior authorization. System managers are also allowed to <var>START</var>, <var>STOP</var>, <var>DEBUG</var>, or <var>TEST</var> any PUBLIC or SEMI-PUBLIC subsystem (not PRIVATE).

System managers cannot use SUBSYSMGMT or DICTADMIN unless another
system manager, who has privileges to use those subsystems, gives
them access through SUBSYSMGMT and DICTADMIN. When employee turnover
and retirements leave no one with those privileges, new system
managers cannot get access. This option solves that problem.

In addition to those privileges, the authority to issue START, STOP, TEST and DEBUG
commands saves the effort of adding a system manager to a privileged
SCLASS in every subsystem in an Online so that the system manager could
at least start and stop the subsystems — a common thing for system
managers to need to do.

In fact, if no users other than system managers need to start or stop
subsystems, this can eliminate the need to even have sclasses in a subsystem to allow starting or stopping of the subsystem.
In some cases, eliminating this need can reduce the subsystem definition to
a single default sclass, which has performance benefits — no sclass
lookup is required when a user enters a subsystem, and no sclass-specific
compilations are done for the procedures in the subsystem.

Because of the overhead associated with multiple sclasses in a
subsystem (not huge, but possibly measurable), some sites take the risk
of adding <var>START</var> and <var>STOP</var> privileges (and perhaps <var>TEST</var> and <var>DEBUG</var>) to the one and only sclass for a subsystem.
This, of course, means that any user can start and stop the subsystem, which might not be ideal from a control or security perspective. 

The <var>APSYSEC</var> parameter allows such a site to keep one sclass but remove the risk.
<var>START</var> and <var>STOP</var> privileges can be removed from the default/only sclass for a
subsystem, and only system managers (or users running subsystems that give them system manager privileges) can start or stop subsystems.

To continue using Model 204's traditional fine-grained control of granting access to run SUBSYSMGMT and DICTADMIN through those subsystems and granting
control of <var>START</var>, <var>STOP</var>, <var>TEST</var>, and <var>DEBUG</var> privileges, the <var>APSYSEC</var> X'01' bit should not be set.</td></tr>
</table>



[[Category:System parameters]]
[[Category:Parameters]]

APSYSEC parameter

2025-05-09T22:09:21Z

JDamon: /* Description */

{{Template:APSYSEC parameter subtitle}}

==Summary==
<dl>
<dt>Default value
<dd>X'00'
<dt>Parameter type
<dd>System
<dt>Where set
<dd>User 0 CCAIN parameters
<dt>Related products
<dd>Prior to Version 7.5 of [[Model 204]], this parameter required the <var class="product">SirSafe</var> product.
<dt>Introduced
<dd><var class="product">[[Sirius Mods]]</var> 6.7
</dl>

==Description==
The <var>APSYSEC</var> parameter makes it possible for a system manager to enter <var>[[SUBSYSMGMT]]</var> and <var>DICTADMIN ([[Dictionary/204 administration]])</var> without
prior authorization. It also allows a system manager to <var>[[START command: Starting an application subsystem|START]]</var>, <var>[[STOP command: Stopping an application subsystem|STOP]]</var>, <var>[[DEBUG command|DEBUG]]</var>, or <var>[[TEST command|TEST]]</var> any PUBLIC or SEMI-PUBLIC subsystem (not PRIVATE), without having to
add the system manager to the [[SCLASS]] authorized to do these things.

For versions of Model 204 prior to 7.5, setting this parameter has no effect at sites not authorized for [[SirSafe]].

The <var>APSYSEC</var> parameter is a bitmask parameter where the bits mean:
<table class="thJustBold">
<tr><th>X'01'</th>

<td>System managers are allowed to enter SUBSYSMGMT and DICTADMIN without prior authorization. System managers are also allowed to <var>START</var>, <var>STOP</var>, <var>DEBUG</var>, or <var>TEST</var> any PUBLIC or SEMI-PUBLIC subsystem (not PRIVATE).

System managers cannot use SUBSYSMGMT or DICTADMIN unless another
system manager, who has privileges to use those subsystems, gives
them access through SUBSYSMGMT and DICTADMIN. When employee turnover
and retirements leave no one with those privileges, new system
managers cannot get access. This option solves that problem.

In addition to those privileges, the authority to issue START, STOP, TEST and DEBUG
commands saves the effort of adding a system manager to a privileged
SCLASS in every subsystem in an Online so that the system manager could
at least start and stop the subsystems — a common thing for system
managers to need to do.

In fact, if no users other than system managers need to start or stop
subsystems, this can eliminate the need to even have sclasses in a subsystem to allow starting or stopping of the subsystem.
In some cases, eliminating this need can reduce the subsystem definition to
a single default sclass, which has performance benefits — no sclass
lookup is required when a user enters a subsystem, and no sclass-specific
compilations are done for the procedures in the subsystem.

Because of the overhead associated with multiple sclasses in a
subsystem (not huge, but possibly measurable), some sites take the risk
of adding <var>START</var> and <var>STOP</var> privileges (and perhaps <var>TEST</var> and <var>DEBUG</var>) to the one and only sclass for a subsystem.
This, of course, means that any user can start and stop the subsystem, which might not be ideal from a control or security perspective. 

The <var>APSYSEC</var> parameter allows such a site to keep one sclass but remove the risk.
<var>START</var> and <var>STOP</var> privileges can be removed from the default/only sclass for a
subsystem, and only system managers (or users running subsystems that give them system manager privileges) can start or stop subsystems.

To continue using Model 204's traditional fine-grained control of granting access to run SUBSYSMGMT and DICTADMIN through those subsystems and grant
control of <var>START</var>, <var>STOP</var>, <var>TEST</var>, and <var>DEBUG</var> privileges, the <var>APSYSEC</var> X'01' bit should not be set.</td></tr>
</table>



[[Category:System parameters]]
[[Category:Parameters]]

APSYSEC parameter

2025-05-09T22:00:33Z

JDamon: /* Description */

{{Template:APSYSEC parameter subtitle}}

==Summary==
<dl>
<dt>Default value
<dd>X'00'
<dt>Parameter type
<dd>System
<dt>Where set
<dd>User 0 CCAIN parameters
<dt>Related products
<dd>Prior to Version 7.5 of [[Model 204]], this parameter required the <var class="product">SirSafe</var> product.
<dt>Introduced
<dd><var class="product">[[Sirius Mods]]</var> 6.7
</dl>

==Description==
The <var>APSYSEC</var> parameter makes it possible for a system manager to enter <var>[[SUBSYSMGMT]]</var> and <var>DICTADMIN ([[Dictionary/204 administration]])</var> without
prior authorization. It also allows a system manager to <var>[[START command: Starting an application subsystem|START]]</var>, <var>[[STOP command: Stopping an application subsystem|STOP]]</var>, <var>[[DEBUG command|DEBUG]]</var>, or <var>[[TEST command|TEST]]</var> any PUBLIC or SEMI-PUBLIC subsystem (not PRIVATE), without having to
add the system manager to the [[SCLASS]] authorized to do these things.

For versions of Model 204 prior to 7.5, setting this parameter has no effect at sites not authorized for [[SirSafe]].

The <var>APSYSEC</var> parameter is a bitmask parameter where the bits mean:
<table class="thJustBold">
<tr><th>X'01'</th>

<td>System managers are allowed to enter SUBSYSMGMT and DICTADMIN without prior authorization. System managers are also allowed to <var>START</var>, <var>STOP</var>, <var>DEBUG</var>, or <var>TEST</var> any PUBLIC or SEMI-PUBLIC subsystem (not PRIVATE).

System managers cannot use SUBSYSMGMT or DICTADMIN unless another
system manager, who has privileges to use those subsystems, gives
them access through SUBSYSMGMT and DICTADMIN. When employee turnover
and retirements leave no one with those privileges, new system
managers cannot get access.

In addition to those privileges, the authority to issue START, STOP, TEST and DEBUG
commands saves the effort of adding a system manager to a privileged
SCLASS in every subsystem in an Online so that the system manager could
at least start and stop the subsystems — a common thing for system
managers to need to do.

In fact, if no users other than system managers need to start or stop
subsystems, this can eliminate the need to even have sclasses in a subsystem to allow starting or stopping of the subsystem.
In some cases, eliminating this need can reduce the subsystem definition to
a single default sclass, which has performance benefits — no sclass
lookup is required when a user enters a subsystem, and no sclass-specific
compilations are done for the procedures in the subsystem.

Because of the overhead associated with multiple sclasses in a
subsystem (not huge, but possibly measurable), some sites take the risk
of adding <var>START</var> and <var>STOP</var> privileges (and perhaps <var>TEST</var> and <var>DEBUG</var>) to the one and only sclass for a subsystem.
This, of course, means that any user can start and stop the subsystem, which might not be ideal from a control or security perspective. 

The <var>APSYSEC</var> parameter allows such a site to keep one sclass but remove the risk.
<var>START</var> and <var>STOP</var> privileges can be removed from the default/only sclass for a
subsystem, and only system managers (or users running subsystems that give them system manager privileges) can start or stop subsystems.

To continue using Model 204's traditional fine-grained control of granting access to run SUBSYSMGMT and DICTADMIN through those subsystems and grant
control of <var>START</var>, <var>STOP</var>, <var>TEST</var>, and <var>DEBUG</var> privileges, the <var>APSYSEC</var> X'01' bit should not be set.</td></tr>
</table>



[[Category:System parameters]]
[[Category:Parameters]]

APSYSEC parameter

2025-05-09T17:06:10Z

JDamon: /* Description */

{{Template:APSYSEC parameter subtitle}}

==Summary==
<dl>
<dt>Default value
<dd>X'00'
<dt>Parameter type
<dd>System
<dt>Where set
<dd>User 0 CCAIN parameters
<dt>Related products
<dd>Prior to Version 7.5 of [[Model 204]], this parameter required the <var class="product">SirSafe</var> product.
<dt>Introduced
<dd><var class="product">[[Sirius Mods]]</var> 6.7
</dl>

==Description==
The <var>APSYSEC</var> parameter makes it possible for a system manager to enter <var>[[SUBSYSMGMT]]</var> and <var>DICTADMIN ([[Dictionary/204 administration]])</var> without
prior authorization. It also allows a system manager to <var>[[START command: Starting an application subsystem|START]]</var>, <var>[[STOP command: Stopping an application subsystem|STOP]]</var>, <var>[[DEBUG command|DEBUG]]</var>, or <var>[[TEST command|TEST]]</var> any PUBLIC or SEMI-PUBLIC subsystem (not PRIVATE), without having to
add the system manager to the [[SCLASS]] authorized to do these things.

For versions of Model 204 prior to 7.5, setting this parameter has no effect at sites not authorized for [[SirSafe]].

The <var>APSYSEC</var> parameter is a bitmask parameter where the bits mean:
<table class="thJustBold">
<tr><th>X'01'</th>

<td>System managers are allowed to enter SUBSYSMGMT and DICTADMIN without prior authorization. System managers are also allowed to <var>START</var>, <var>STOP</var>, <var>DEBUG</var>, or <var>TEST</var> any PUBLIC or SEMI-PUBLIC subsystem (not PRIVATE).
This saves the effort of adding a system manager to a privileged
SCLASS in every subsystem in an Online so that the system manager could
at least start and stop the subsystems — a common thing for system
managers to need to do.

In fact, if no users other than system managers need to start or stop
subsystems, this can eliminate the need to even have sclasses in a subsystem to allow starting or stopping of the subsystem.
In some cases, eliminating this need can reduce the subsystem definition to
a single default sclass, which has performance benefits — no sclass
lookup is required when a user enters a subsystem, and no sclass-specific
compilations are done for the procedures in the subsystem.

Because of the overhead associated with multiple sclasses in a
subsystem (not huge, but possibly measurable), some sites take the risk
of adding <var>START</var> and <var>STOP</var> privileges (and perhaps <var>TEST</var> and <var>DEBUG</var>) to the one and only sclass for a subsystem.
This, of course, means that any user can start and stop the subsystem, which might not be ideal from a control or security perspective. 

The <var>APSYSEC</var> parameter allows such a site to keep one sclass but remove the risk.
<var>START</var> and <var>STOP</var> privileges can be removed from the default/only sclass for a
subsystem, and only system managers (or users running subsystems that give them system manager privileges) can start or stop subsystems.

To continue using Model 204's traditional fine-grained
control of <var>START</var>, <var>STOP</var>, <var>TEST</var>, and <var>DEBUG</var> privileges, the <var>APSYSEC</var> X'01' bit should not be set.</td></tr>
</table>



[[Category:System parameters]]
[[Category:Parameters]]

M204.0473

2025-04-08T17:13:04Z

JDamon:

{{Template:M204.0473 skeleton}}
<ul>
<LI>If the message reports a specific subsystem name, that subsystem could not be initialized because of an error.</LI>

<LI>If the message is issued by User 0 during Model 204 initialization and it reports <code>SUBSYSTEMS</code>, APSY initialization failed, and APSY subsystems will not be available during this run. Otherwise, <code>subsysName</code> has failed to initialize.</LI>

<LI>If this message is preceded by the following message, then the user attempted to start a suspended subsystem:
M204.2661: SUBSYSTEM name SUSPENDED

The user must issue the <var>RESUME SUBSYSTEM</var> command to make the subsystem available for use.</li>
</ul>

Response: Notify the system manager.

System manager response: If the message reports a specific subsystem, look at the audit trail or issue the <var>TEST</var> subsystem command to determine which error caused subsystem initialization to fail.

If the message reports <code>SUBSYSTEMS</code>, there are two possible causes:
<ol>
<li>[[M204.0027]] was issued indicating that CCASYS contained non-Rocket supported procs or the CCASYS auxiliary procedure dictionary was full</li>
or
<li>Server tables for User 0 are not large enough to initialize subsystem handling. Change the User 0 parameters so that its server table sizes are at least as large as the sizes listed in the description of message [[M204.1457]], and then restart Model 204.
</li>
</ol>
{{Template:M204.0473 footer}}

M204.1457

2025-04-08T17:10:21Z

JDamon:

{{Template:M204.1457 skeleton}}

Model 204 is unable to scan the CCASYS auxiliary procedure dictionary. This scan is required to check the START SUBSYS command you entered against the list of application subsystems defined at your installation. The command is not executed and Subsystem processing is disabled for this run; Model 204 must be restarted to enable Subsystem processing. This message can be caused by any of the following: 
<ul>
<LI>The system manager did not set the <var>SYSOPT</var> X'01' bit.</LI>

<LI>An error occurred during Model 204 initialization. Early in CCAAUDIT, you may see</li>
[[M204.0027]]: Aux procedure dictionary full
followed by
[[M204.0473]]: Unable to initialize subsysName

The [[M204.0027]] indicates that the CCASYS auxiliary procedure dictionary could not be built in memory because:
<ol>
<li>unsupported procs have been stored in CCASYS; only Rocket supplied procs can be stored in CCASYS</li>
<li>building the CCASYS auxiliary procedure dictionary failed due to memory constraints</li>
</ol>
<LI>There is insufficient space in the server tables of the user who issued the command.</LI>

<LI>A new Model 204 release was installed, but a matching Dictionary/204 upgrade was either omitted or not performed properly.</LI>

<LI>There is some problem with the CCASYS file.</LI>
</ul>

Response: Subsystems cannot be started unless there are 288 unused bytes in the global variable table (GTBL). The following sequence of commands may assist you in verifying and creating adequate GTBL space:
<TABLE>
<TR class="head"><TH>Command </TH>
<TH>Purpose</TH></TR>

<TR><TD>CLEARG </TD>
<TD>Deletes all global string variables from GTBL</TD></TR>

<TR><TD>CLEARGO </TD>
<TD>Deletes all global objects from GTBL</TD></TR>

<TR><TD>VIEW LGTBL </TD>
<TD>Displays the allocated size of GTBL</TD></TR>

<TR><TD>VIEW GTBLHASH </TD>
<TD>Displays the number of GTBL hash buckets</TD></TR>

<TR><TD>UTABLE LGTBL=value </TD>
<TD>Resizes GTBL to the indicated size</TD></TR>
</TABLE>

If GTBLHASH is zero, <code>LGTBL=288</code> is sufficient. However, if GTBLHASH is nonzero, LGTBL should be at least <code>(288 + (10 * GTBLHASH))</code>. The extra space represents 8 bytes of control information per hash bucket, plus an allowance
because hashing cannot distribute values exactly evenly. 

If this error occurs when GTBL is large enough, use the VIEW command to verify that the sizes of the server tables are at least this size:
<TABLE>
<TR class="head"><TH>Server table </TH>
<TH>Size</TH></TR>

<TR><TD>LNTBL </TD>
<TD>50</TD></TR>

<TR><TD>LQTBL</TD>
<TD>120</TD></TR>

<TR><TD>LSTBL</TD>
<TD>250</TD></TR>

<TR><TD>LVTBL </TD>
<TD>50</TD></TR>

<TR><TD>LFSCB </TD>
<TD>256</TR>
</TABLE>

If the values of these parameters are adequate when this message is issued, contact the system manager.

System manager response:Look at the audit trail for an earlier message identifying the cause of the error. Verify that CCASYS was installed properly. Was Dictionary/204 correctly installed or upgraded for this release? If CCASYS is physically
inconsistent, reorganize the file. The reorganization should include a reload of data and the procedures stored in CCASYS.

{{Template:M204.1457 footer}}

M204.0027

2025-04-08T16:59:13Z

JDamon:

{{Template:M204.0027 skeleton}}
This error can occur:

<ol>
<li>During Model 204 initialization, if unsupported procs have been stored in CCASYS. Only Rocket supplied procs can be stored in CCASYS.</li>
or
<li>When the START SUBSYS subsysName command is issued for a subsystem. During a subsystem initialization, the subsystem procedure file is scanned twice. The first scan retrieves the number of subsystem procedures in order to allocate the subsystem's in-core procedure dictionary. The second scan retrieves the procedure information that is copied into the in-core procedure dictionary. If another user adds a new subsystem procedure between the first procedure file scan and the second, the error can occur.</li>
</ol>

Response:
<ol>
<li>Remove all non-ROCKET procs from CCASYS and restart Model 204.</li>
<li>Reissue the START SUBSYS subsysName command. If this doesn't help, issue the DEBUG SUBSYS subsysName command; the messages produced may provide information pointing to the problem.</LI>

{{Template:M204.0027 footer}}

M204.0027

2025-04-08T16:53:21Z

JDamon:

{{Template:M204.0027 skeleton}}
This error can occur:

<ol>
<li>During Model 204 initialization, if unsupported procs have been stored in CCASYS. Only Rocket supplied procs can be stored in CCASYS.</li>
or
<li>When the START SUBSYS subsysName command is issued for a subsystem. During a subsystem initialization, the subsystem procedure file is scanned twice. The first scan retrieves the number of subsystem procedures in order to allocate the subsystem's in-core procedure dictionary. The second scan retrieves the procedure information that is copied into the in-core procedure dictionary. If another user adds a new subsystem procedure between the first procedure file scan and the second, the error can occur.</li>
</ol>

Response:
<ol>
<li>Remove all non-ROCKET procs from CCASYS and restart Model 204.</li>
<li>Reissue the START SUBSYS subsysName command. If this doesn't help, issue the '''DEBUG SUBSYS subsysName''' command; the messages produced may provide information pointing to the problem.</LI>

{{Template:M204.0027 footer}}

M204.0027

2025-04-07T23:28:31Z

JDamon:

{{Template:M204.0027 skeleton}}
This error can occur:

<ol>
<li>During Model 204 initialization, if unsupported procs have been stored in CCASYS. Only Rocket supplied procs can be stored in CCASYS.</li>
or
<li>When the START SUBSYS subsysName command is issued for a subsystem. During a subsystem initialization, the subsystem procedure file is scanned twice. The first scan retrieves the number of subsystem procedures in order to allocate the subsystem's in-core procedure dictionary. The second scan retrieves the procedure information that is copied into the in-core procedure dictionary. If another user adds a new subsystem procedure between the first procedure file scan and the second, the error can occur.</li>
</ol>

Response:
<ol>
<li>Remove all non-ROCKET procs from CCASYS and restart Model 204.</li>
<li>Reissue the START SUBSYS subsysName command.</LI>

{{Template:M204.0027 footer}}

M204.0027

2025-04-07T22:48:07Z

JDamon:

{{Template:M204.0027 skeleton}}
When Model 204 performs a subsystem initialization, the subsystem procedure file is scanned twice. The first scan retrieves the number of subsystem procedures in order to allocate the subsystem's in-core procedure dictionary. The second scan retrieves the procedure information that is copied into the in-core procedure dictionary. This error occurs when another user adds a new subsystem procedure between the first procedure file scan and the second. The error can also occur if unsupported procs have been stored in CCASYS; only Rocket supplied procs can be stored in CCASYS.
Response: Reissue the subsystem command. 
{{Template:M204.0027 footer}}

M204.0473

2025-04-07T22:46:07Z

JDamon:

{{Template:M204.0473 skeleton}}
<ul>
<LI>If the message reports a specific subsystem name, that subsystem could not be initialized because of an error.</LI>

<LI>If the message is issued by User 0 during Model 204 initialization and it reports <code>SUBSYSTEMS</code>, APSY initialization failed, and APSY subsystems will not be available during this run. Otherwise, <code>subsysName</code> has failed to initialize.</LI>

<LI>If this message is preceded by the following message, then the user attempted to start a suspended subsystem:
M204.2661: SUBSYSTEM name SUSPENDED

The user must issue the <var>RESUME SUBSYSTEM</var> command to make the subsystem available for use.</li>
</ul>

Response: Notify the system manager.

System manager response: If the message reports a specific subsystem, look at the audit trail or issue the <var>TEST</var> subsystem command to determine which error caused subsystem initialization to fail.

If the message reports <code>SUBSYSTEMS</code>, there are two possible causes:
<ol>
<li>[[M204.0027]] was issued indicating that the CCASYS auxiliary procedure dictionary was full</li>
or
<li>Server tables for User 0 are not large enough to initialize subsystem handling. Change the User 0 parameters so that its server table sizes are at least as large as the sizes listed in the description of message [[M204.1457]], and then restart Model 204.
</li>
</ol>
{{Template:M204.0473 footer}}

M204.0027

2025-04-07T22:27:18Z

JDamon:

{{Template:M204.0027 skeleton}}
When Model 204 performs a subsystem initialization, the subsystem procedure file is scanned twice. The first scan retrieves the number of subsystem procedures in order to allocate the subsystem's in-core procedure dictionary. The second scan retrieves the procedure information that is copied into the in-core procedure dictionary. This error occurs when another user adds a new subsystem procedure between the first procedure file scan and the second. The error can also occur if unsupported procs have been store in CCASYS; only Rocket supplied procs can be stored in CCASYS.
Response: Reissue the subsystem command. 
{{Template:M204.0027 footer}}

M204.1457

2025-04-07T22:24:46Z

JDamon:

{{Template:M204.1457 skeleton}}

Model 204 is unable to scan the CCASYS auxiliary procedure dictionary. This scan is required to check the START SUBSYS command you entered against the list of application subsystems defined at your installation. The command is not executed and Subsystem processing is disabled for this run; Model 204 must be restarted to enable Subsystem processing. This message can be caused by any of the following: 
<ul>
<LI>The system manager did not set the <var>SYSOPT</var> X'01' bit.</LI>

<LI>An error occurred during Model 204 initialization. Early in CCAAUDIT, you may see</li>
[[M204.0027]]: Aux procedure dictionary full
followed by
[[M204.0473]]: Unable to initialize subsysName

The [[M204.0027]] indicates that the CCASYS auxiliary procedure dictionary could not be built in-memory because unsupported procs have been stored in CCASYS. Only Rocket supplied procs can be stored in CCASYS.

<LI>There is insufficient space in the server tables of the user who issued the command.</LI>

<LI>A new Model 204 release was installed, but a matching Dictionary/204 upgrade was either omitted or not performed properly.</LI>

<LI>There is some problem with the CCASYS file.</LI>
</ul>

Response: Subsystems cannot be started unless there are 288 unused bytes in the global variable table (GTBL). The following sequence of commands may assist you in verifying and creating adequate GTBL space:
<TABLE>
<TR class="head"><TH>Command </TH>
<TH>Purpose</TH></TR>

<TR><TD>CLEARG </TD>
<TD>Deletes all global string variables from GTBL</TD></TR>

<TR><TD>CLEARGO </TD>
<TD>Deletes all global objects from GTBL</TD></TR>

<TR><TD>VIEW LGTBL </TD>
<TD>Displays the allocated size of GTBL</TD></TR>

<TR><TD>VIEW GTBLHASH </TD>
<TD>Displays the number of GTBL hash buckets</TD></TR>

<TR><TD>UTABLE LGTBL=value </TD>
<TD>Resizes GTBL to the indicated size</TD></TR>
</TABLE>

If GTBLHASH is zero, <code>LGTBL=288</code> is sufficient. However, if GTBLHASH is nonzero, LGTBL should be at least <code>(288 + (10 * GTBLHASH))</code>. The extra space represents 8 bytes of control information per hash bucket, plus an allowance
because hashing cannot distribute values exactly evenly. 

If this error occurs when GTBL is large enough, use the VIEW command to verify that the sizes of the server tables are at least this size:
<TABLE>
<TR class="head"><TH>Server table </TH>
<TH>Size</TH></TR>

<TR><TD>LNTBL </TD>
<TD>50</TD></TR>

<TR><TD>LQTBL</TD>
<TD>120</TD></TR>

<TR><TD>LSTBL</TD>
<TD>250</TD></TR>

<TR><TD>LVTBL </TD>
<TD>50</TD></TR>

<TR><TD>LFSCB </TD>
<TD>256</TR>
</TABLE>

If the values of these parameters are adequate when this message is issued, contact the system manager.

System manager response:Look at the audit trail for an earlier message identifying the cause of the error. Verify that CCASYS was installed properly. Was Dictionary/204 correctly installed or upgraded for this release? If CCASYS is physically
inconsistent, reorganize the file. The reorganization should include a reload of data and the procedures stored in CCASYS.

{{Template:M204.1457 footer}}

M204.1457

2025-04-07T20:27:01Z

JDamon:

{{Template:M204.1457 skeleton}}

Model 204 is unable to scan the CCASYS auxiliary procedure dictionary to check the START SUBSYS command you entered against the list of application subsystems defined at your installation. The command is not executed and Subsystem processing is disabled for this run; Model 204 must be restarted to enable Subsystem processing. This message can be caused by any of the following: 
<ul>
<LI>The system manager did not set the <var>SYSOPT</var> X'01' bit.</LI>

<LI>An error occurred during Model 204 initialization. This is indicated in the audit trail by message [[M204.0473]], issued by User 0 during initialization. </LI>

<LI>There is insufficient space in the server tables of the user who issued the command.</LI>

<li>M204.1457 may be preceded by M204.0027: Aux procedure dictionary full
During Model 204 initialization, the CCASYS auxiliary procedure dictionary could not be built in-memory because unsupported procs have been stored in CCASYS. Only Rocket supplied procs can be stored in CCASYS.
</LI>

<LI>A new Model 204 release was installed, but a matching Dictionary/204 upgrade was either omitted or not performed properly.</LI>

<LI>There is some problem with the CCASYS file.</LI>
</ul>

Response: Subsystems cannot be started unless there are 288 unused bytes in the global variable table (GTBL). The following sequence of commands may assist you in verifying and creating adequate GTBL space:
<TABLE>
<TR class="head"><TH>Command </TH>
<TH>Purpose</TH></TR>

<TR><TD>CLEARG </TD>
<TD>Deletes all global string variables from GTBL</TD></TR>

<TR><TD>CLEARGO </TD>
<TD>Deletes all global objects from GTBL</TD></TR>

<TR><TD>VIEW LGTBL </TD>
<TD>Displays the allocated size of GTBL</TD></TR>

<TR><TD>VIEW GTBLHASH </TD>
<TD>Displays the number of GTBL hash buckets</TD></TR>

<TR><TD>UTABLE LGTBL=value </TD>
<TD>Resizes GTBL to the indicated size</TD></TR>
</TABLE>

If GTBLHASH is zero, <code>LGTBL=288</code> is sufficient. However, if GTBLHASH is nonzero, LGTBL should be at least <code>(288 + (10 * GTBLHASH))</code>. The extra space represents 8 bytes of control information per hash bucket, plus an allowance
because hashing cannot distribute values exactly evenly. 

If this error occurs when GTBL is large enough, use the VIEW command to verify that the sizes of the server tables are at least this size:
<TABLE>
<TR class="head"><TH>Server table </TH>
<TH>Size</TH></TR>

<TR><TD>LNTBL </TD>
<TD>50</TD></TR>

<TR><TD>LQTBL</TD>
<TD>120</TD></TR>

<TR><TD>LSTBL</TD>
<TD>250</TD></TR>

<TR><TD>LVTBL </TD>
<TD>50</TD></TR>

<TR><TD>LFSCB </TD>
<TD>256</TR>
</TABLE>

If the values of these parameters are adequate when this message is issued, contact the system manager.

System manager response:Look at the audit trail for an earlier message identifying the cause of the error. Verify that CCASYS was installed properly. Was Dictionary/204 correctly installed or upgraded for this release? If CCASYS is physically
inconsistent, reorganize the file. The reorganization should include a reload of data and the procedures stored in CCASYS.

{{Template:M204.1457 footer}}

Subroutines

2025-01-29T19:56:04Z

JDamon: /* DECLARE before CALL */

<div class="toclimit-3">

==Overview==

User Language lets you treat a single set of statements as a simple or complex subroutine. You can:
<ul>
<li>Execute simple subroutines a number of times from different locations within a request.</li>
<li>Use complex subroutines as you would simple subroutines. </li>
</ul>
In addition, you can:
<ul>
<li>Pass parameters via parameter lists.</li>
<li>Declare variables locally.</li>
</ul>

===Common elements===

An element that is not passed as a parameter can be shared between complex subroutines, or between a complex subroutine and the main request, when you declare that element as <var>COMMON</var>.

===On units===

As [[#On statement|described later]], an <var>On</var> unit specifies a response action to a triggering event: for example, the terminal operator pressing one of the ATTENTION identifier (AID) keys. <var>On</var> units let an application override the normal system response.

==Simple subroutines==

===Outlining a simple subroutine===

The following statements are used in simple subroutines within a request:
<table>
<tr class="head">
<th>Statement</th>
<th>Purpose</th></tr>

<tr>
<td><var>CALL</var></td>
<td>Transfers control to the subroutine.</td></tr>

<tr>
<td nowrap><var>END SUBROUTINE</var></td>
<td>Indicates the end of the subroutine.</td></tr>

<tr>
<td><var>JUMP TO</var></td>
<td>Transfers control to another statement in the request.</td></tr>

<tr>
<td><var>RETURN</var></td>
<td>Returns control to the statement immediately following the CALL statement. </td></tr>

<tr>
<td><var>SUBROUTINE</var></td>
<td>Indicates the beginning of a subroutine. </td></tr>
</table>

The statements are coded in the following sequence, so they are described in order of usage.
<ol>
<li><var>SUBROUTINE</var> statement</li>
<li><var>JUMP TO</var> and <var>RETURN</var> statements as appropriate</li>
<li><var>END SUBROUTINE</var> statement</li>
<li><var>CALL</var> statement</li>
</ol>

===SUBROUTINE statement===

A simple subroutine consists of a sequence of SOUL statements that must begin with a <var>SUBROUTINE</var> statement. The body of the subroutine is composed of the statements immediately following the <var>SUBROUTINE</var> statement. 

====Syntax====

The format of the <var>SUBROUTINE</var> statement is: 
label: SUBROUTINE


A simple subroutine must be labeled; without a label it cannot be executed. You cannot use field names in the subroutine, except within a FOR loop, even if the subroutine is always called from within a record loop.

====Example of a simple subroutine====

The following request uses two subroutines. 
Note: Simple subroutine statements in the following example are described more fully after this example.

The first subroutine, <code>TOTAL</code>, accumulates a total in the %variable named <code>%TOTAL.MUSTANGS</code>. The second subroutine, <code>PRINT.TOTAL</code>, prints a literal that varies depending on the total accumulated. 
BEGIN
MUSTANGS: FIND ALL RECORDS FOR WHICH
MODEL = MUSTANG
END FIND
FOR EACH RECORD IN MUSTANGS
CALL TOTAL
END FOR
CALL PRINT.TOTAL
TOTAL: SUBROUTINE
%TOTAL.MUSTANGS = %TOTAL.MUSTANGS + 1
RETURN
END SUBROUTINE TOTAL
PRINT.TOTAL: SUBROUTINE
IF %TOTAL.MUSTANGS LE 10 THEN
PRINT 'TOTAL MUSTANG POLICIES -
NOT GREATER THAN 10'
ELSEIF %TOTAL.MUSTANGS LE 50 THEN
PRINT 'TOTAL MUSTANG POLICIES -
NOT GREATER THAN 50'
ELSEIF %TOTAL.MUSTANGS GT 50 THEN
PRINT 'TOTAL MUSTANG POLICIES -
GREATER THAN 50'
END IF
RETURN
END SUBROUTINE PRINT.TOTAL
END


===JUMP TO statements===

<var class="product">Model 204</var> compiles subroutines only after they are called, regardless of where they are in your program.

If you use a <var>JUMP TO</var> statement, its destination must be within the same subroutine. You cannot jump into a subroutine from outside of a subroutine.

===RETURN statement===

The <var>RETURN</var> statement returns control from the subroutine to the statement following the most recent <var>CALL</var> statement. 

====Syntax====

The format of the <var>RETURN</var> statement is: 
RETURN


The <var>RETURN</var> statement can appear only within the body of a subroutine. Use of the <var>RETURN</var> statement inside of an <var>ON</var> unit terminates compilation, the procedure cannot run, and the following message is produced: 
M204.1779 RETURN IS INVALID IN ON UNITS, USE BYPASS STATEMENT


<var class="product">Model 204</var> automatically generates a return at the end of a subroutine, if you do not specify one. 

For more information, see [[#ON units|ON units]] and [[#Passing control to and from ON units|Passing control to and from ON units]].

===END SUBROUTINE statement===

You can end a subroutine using an <var>END SUBROUTINE</var> statement or an <var>END BLOCK</var> statement. 

====Syntax====

The END SUBROUTINE statement is formatted as follows: 
END SUBROUTINE [label]


===CALL statement===

The <var>CALL</var> statement transfers control to the subroutine. 

====Syntax====

The format of the <var>CALL</var> statement is:
CALL label


====Example====

This statement:
CALL.SUB: CALL COMPUTE.PREMIUM


transfers control to the following statement:
COMPUTE.PREMIUM: SUBROUTINE


When you use a simple subroutine, no arguments are passed in subroutine calls. Instead, input and output values are implicitly passed in %variables or global variables. If you want field values as arguments, you must assign the values to %variables before the call, or the subroutine must contain its own <var>FOR EACH RECORD</var> loop on the set of records to be processed.

Processing continues sequentially from that statement until another control transfer statement — a <var>CALL</var>, <var>IF</var>, <var>JUMP TO</var>, <var>RETURN</var>, or <var>STOP</var> statement — is encountered. 

==Complex subroutines==

Complex subroutines perform all the operations of a simple subroutine. In addition, a complex subroutine can pass parameters via parameter lists and can declare local variables. 
Note: The format of the <var>SUBROUTINE</var> statement changes for a complex subroutine and the <var>CALL</var> statement is also more complex.

===Symbolic parameter passing===

You can specify positional parameters on the <var>CALL</var> statement for a complex subroutine. These parameters are substituted for symbolic parameters used within the subroutine during execution. You can use the following elements as parameters to a complex subroutine:
<ul>
<li>Scalar %variables</li>

<li>%variable arrays</li>

<li>Lists of records</li>
</ul>

===Local variable declaration===

Labels, %variables, and other elements in a complex subroutine are local to the subroutine; they do not conflict with elements of the same name in the request or in other complex subroutines. This allows the same element to be used in different portions of a request, and for the same name to describe different elements in each portion.

===Processing===

All data within the subroutine is statically allocated. When the subroutine is called, the values of all found sets, counts, noted values, and variables are as they were when the subroutine was last executed. Recursive calls to the same subroutine do not allocate separate storage for each subroutine local variable. Local variables are allocated only one time.

====OPEN statement within a complex subroutine====

A SOUL <var>OPEN</var> statement — an <var>OPEN</var> statement inside a <var>BEGIN/END</var> — when used within a complex subroutine on a file that is not defined to the region produces the following counting error and the request is not compiled:
M204.1521: entity-name DOES NOT EXIST OR REQUESTED ACCESS NOT AUTHORIZED


===SUBROUTINE statement for complex subroutines===

Complex subroutines begin with the following form of the <var>SUBROUTINE</var> statement: 
SUBROUTINE subname [(formal-parameter
[inout-option] [, ...])]

Where:
<ul>
<li><var class="term">subname</var> is the name of the subroutine.</li>

<li><var class="term">formal-parameter</var> is the declaration of a symbolic parameter used within the subroutine. The parameter list is comprised of the <var class="term">formal-parameter</var> and subsequent input-options. The parameter list is enclosed in parentheses, and it contains declarations for each parameter separated by commas. The parameter list must be specified on one logical line. Null parameters are not allowed.</li>

<li><var class="term">formal-parameter</var> specifies the name and type of element to be used within the subroutine and can be any of the following:
<ul>
<li>Scalar (nonarray) %variable formatted as:
%variable [IS] {[STRING] [LEN] n [DP {n | *}]
| [FIXED [DP n] | FLOAT]}


For example:
SUBROUTINE EXAMPLE (%W IS STRING DP * -
%X IS STRING LEN 40, -
%Y IS STRING LEN 10 DP 2, -
%Z IS FLOAT, -
%A IS FIXED DP 4)
</li>

<li>Array %variable formatted as:
%variable [IS] [[STRING] [LEN n] [DP {n | *}]
[ARRAY(* [,*[,*]])] [NO FIELD SAVE]
| {FIXED [DP n] | FLOAT} [ARRAY(* [,*[,*]])]]


The number of dimensions must be specified in the subroutine declaration, but the exact size of each dimension is not specified. An asterisk (<tt>*</tt>) is used instead of the dimension size. For example:
SUBROUTINE EXAMPLE(%ARR IS STRING LEN 10 - ARRAY(*,*))
</li>

<li>A list of records formatted as:
[LIST] listname [IN [FILE | [PERM | TEMP] GROUP]] name


The context of the list is restricted to a single file or group. For example:
SUBROUTINE GENERAL(LIST TOTRECS IN FILE VEHICLES)
</li>
</ul>

<li><var class="term">inout-option</var> specifies whether a formal-parameter is to be used as input to the subroutine or passed as output from the subroutine. Options are as follows:
<table>
<tr class="head">
<th>Option</th>
<th>Data can be...</th>
</tr>

<tr>
<td>INPUT 
(the default)</td>
<td>Passed into, but not out of, a subroutine. In addition, data conversions are performed automatically, in the same manner as an assignment statement. All references to <var>INPUT</var> parameters that update the parameter, for example, assignment statements, result in compiler errors.</td>
</tr>

<tr>
<td nowrap>INPUT OUTPUT</td>
<td>This option is equivalent to the OUTPUT option. </td>
</tr>

<tr>
<td>OUTPUT</td>
<td>Returned from a subroutine. No data conversions are performed.

The lengths of complex subroutine string OUTPUT parameters are inherited from calling parameters. If the lengths are specified in the subroutine declaration, the following message is written to the audit trail: 
M204.1981 LENGTH IGNORED FOR OUTPUT PARAMETER


Compilation and evaluation of the procedure continues, with the inherited length.
</td>
</tr>
</table></li>
</ul>

===END SUBROUTINE statement===

Like simple subroutines, a complex subroutine ends with an <var>END SUBROUTINE</var> statement. However, unlike simple subroutines, you must not label the <var>SUBROUTINE</var> statement. 

All declarations and statements compiled after the <var>SUBROUTINE</var> statement become a part of the subroutine until the <var>END SUBROUTINE</var> statement is encountered or until the request is ended with the <var>END</var> statement. 

===CALL statement===

The execution of a <var>CALL</var> statement passes control to a complex subroutine. The first time a subroutine is called, all elements in the subroutine are initialized. Subsequently, each time the subroutine is called, all elements in the subroutine remain in the same state as they were when the subroutine was last exited. You are responsible for reinitializing the elements within the subroutine.

====Syntax====

A complex subroutine is invoked with this form of the <var>CALL</var> statement:
CALL subname [(actual-parameter [, ...])]

Where:
<ul>
<li><var class="term">subname</var> is the name of the subroutine.</li>

<li><var class="term">actual-parameter</var> specifies the actual data that replaces the symbolic formal-parameter within the subroutine. At execution time, the value of each actual-parameter is substituted, based on the order in which it appears, for a formal-parameter declared for the subroutine. The correspondence of each formal-parameter in the <var>SUBROUTINE</var> statement to an actual-parameter in the <var>CALL</var> statement is by position rather than by name.

An actual-parameter can be any of the following:
<ul>
<li>%variable or expression

Expressions can contain field names, screen items, image items, and constants.</li>

<li>Array %variable

When an entire array is passed as a parameter, the %variable name is used with the percent (%) sign, but no parenthesis or subscript expressions follow it. For example:
BEGIN
%A IS FLOAT ARRAY(10,10)
DECLARE SUBROUTINE FDO(FLOAT ARRAY(*,*))
.
.
.
CALL FDO (%A)
.
.
.
SUBROUTINE FDO (%B IS FLOAT ARRAY(*,*))
PRINT %B(1,1)
END SUBROUTINE
END


The <var>[[$ArrSize]]</var> function can be used to determine the number of elements in a particular dimension of an array. </li>

<li>A list

An actual-parameter can be a list, optionally preceded by the word LIST to distinguish it from a field name. 

If the compiler already knows of the formal-parameter list because the subroutine is already compiled or declared, the LIST keyword is unnecessary. 

If the list has never been declared in the request, a compilation error results. 
</li></ul>
</li></ul>

====Additional rules for parameters====

The following additional rules apply to actual-parameters and parameter passing:
<ul>
<li>The maximum number of parameters that can be passed in complex subroutines is 63.</li>

<li>If the formal-parameter is specified as an OUTPUT parameter, the corresponding actual-parameter must match type.</li>

<li>The INPUT parameters of a %variable array requires that the type of the array — <var>FLOAT</var>, <var>FIXED</var>, or <var>STRING</var> — the <var>DP</var> specification, and the number of dimensions match the actual-parameter. In addition, if the <var>NO FIELD SAVE</var> (<var>NO FS</var>) option is specified for a <var>STRING</var> formal-parameter, it also must be specified for the corresponding actual-parameter and vice versa. All checking of array bounds within subroutines occurs during evaluation.</li>

<li>The INPUT parameters of a list requires the same file or group context as the actual-parameter.
</li>

<li>An INPUT parameter of a scalar %variable can be called with an actual-parameter that is an expression or %variable of a differing type. <var class="product">Model 204</var> converts the actual-parameter to the type required by the subroutine, according to the rules of the assignment statement. The converted value has a separate storage location from the original variable or expression.

Passing arguments to INPUT parameters might involve truncation where the number of decimal places is different, or conversion to 0 for non-numeric strings.
</li>

<li>OUTPUT parameters of lists and %variable arrays follow the same rules as INPUT parameters for lists and %variable arrays.</li>
</li>

<li>OUTPUT parameters of scalar %variables require that the actual-parameter supplied in the <var>CALL</var> statement be another scalar %variable (no constants or expressions) of the same type — <var>FLOAT</var>, <var>FIXED</var>, or <var>STRING</var> — and that the number of decimal places be the same, or the following message is issued by <var class="product">Model 204</var>:
M204.1725 PARAMETER NUMBER n IS TYPE INCOMPATIBLE


Strings can be of any length. The length used is that of the actual input parameter. 
</li>
</ul>

===Processing complex subroutines===

Checking for the validity of parameter lists occurs during compilation. When the SUBROUTINE statement is compiled, the types of parameters are saved by the compiler, and any subsequent CALL statements are verified as to whether the actual parameter is consistent with the type of formal parameter.

When a CALL statement is compiled and the subroutine to which it refers has not been compiled, the compiler verifies whether the actual parameter list is compatible with other CALL statements for the subroutine that it has already compiled. 

The compiler cannot verify that the actual parameters are compatible with the SUBROUTINE statement until that SUBROUTINE statement is compiled. If the compiler then detects a CALL statement that is not compatible with the SUBROUTINE statement, an error is issued at that time. Checking is done at compile time, so a statement that is not executed during evaluation can still generate an error. 

===DECLARE SUBROUTINE statement===

The DECLARE statement for a complex subroutine is similar to the SUBROUTINE statement, except that the parameter names are omitted. 

====Syntax====
The complete syntax for the DECLARE SUBROUTINE statement is:
DECLARE SUBROUTINE subname [(type [inout-option] [, ...])] 
Where:
<ul>
<li><var class="term">subname</var> is the name of the subroutine.</li>

<li><var class="term">type</var> is one of the following:
<ul>
<li>Scalar %variable of the following format:
{STRING [LEN] n [DP {n | *}] | [FIXED [DP n] | FLOAT]}
</li>

<li>Array %variable of the following format:
{STRING [LEN n] [DP [n | *}] [ARRAY(* [,*[,*]]) [NO FIELD SAVE]]
| [FIXED [DP n] | FLOAT] [ARRAY(* [,*[,*]])]}
</li>

<li>A list of records of the following format:
[LIST] [IN {FILE | [PERM | TEMP] GROUP} name]
</li>
</ul></li>

<li>
<var class="term">inout-option</var> specifies whether each formal parameter is to be used as input to the subroutine or passed as output from the subroutine. Options are the same as those that can be specified on the SUBROUTINE statement: INPUT, OUTPUT, or INPUT OUTPUT. </li>
</ul>

====DECLARE before CALL====
When a <var>CALL</var> statement refers to a subroutine that has not yet been compiled, the error checking capabilities of the compiler are limited, because the number and type of formal parameters are not known to the compiler. If the first <var>CALL</var> statement for a particular subroutine is not correctly coded, then a large number of error messages can be generated when compiling subsequent <var>CALL</var> statements, although these statements might be correctly coded.

You can avoid this problem in one of the following ways:
<ul>
<li>Declare the formal parameter list with the <var>DECLARE</var> statement. When the <var>DECLARE</var> statement precedes the first <var>CALL</var>, the compiler generates the correct error messages, if problems are encountered. </li>

<li>Place the subroutine declaration before the first <var>CALL</var> statement.</li>
</ul>

====Specifying a list of records====

If you specify a <var>LIST</var> (of records), you must also specify <var>FILE</var> or <var>GROUP</var>. For example:
OPEN METADATA
password

BEGIN
DECLARE LIST ORIG IN METADATA
DECLARE SUBROUTINE THE.SUB(LIST IN FILE METADATA INOUT)
.
.
CALL THE.SUB (LIST ORIG)
.
.
SUBROUTINE THE.SUB(LIST ORIG IN METADATA INOUT)
.
.
END SUBROUTINE THE.SUB
END


If you do not specify <var>FILE</var> or <var>GROUP</var> in the code, you receive the following error message:
M204.1725: PARAMETER NUMBER n IS TYPE INCOMPATIBLE


====DECLARE parameters and CALL parameters====

In the following example, note that the <var>DECLARE</var> statement lists the formal parameters, while the <var>CALL</var> statement lists the actual parameters:
DECLARE SUBROUTINE SUB1(FLOAT, FIXED DP 2, STRING, STRING DP *)
.
.
CALL SUB1(%INCREASE,%WAGES,%NAME,%DEPT)
.
.
SUBROUTINE SUB1(%A IS FLOAT,
%B IS FIXED DP 2,
%C IS STRING,
%D IS STRING DP *)
END SUBROUTINE
.
.
END


====Impact on CALL and SUBROUTINE statements====

The <var>CALL</var> and <var>SUBROUTINE</var> statements are not overridden when a <var>DECLARE SUBROUTINE</var> statement is present. The <var>DECLARE SUBROUTINE</var> statement does not cause the compiler to use more table space, nor does it alter the way in which the compiler output is generated.

Rocket Software recommends that you use a <var>DECLARE SUBROUTINE</var> statement before the <var>CALL</var> statement for a subroutine or that you place the subroutine itself before the <var>CALL</var> statement. Error reporting will be more complete and specific to the subroutine.

===Exiting the subroutine===

The <var>RETURN</var> statement returns control to the statement immediately following the most recent <var>CALL</var> statement. If an <var>END SUBROUTINE</var> or <var>END</var> statement is encountered without a <var>RETURN</var> statement, <var>RETURN</var> processing is implied and automatically added by the compiler. More than one <var>RETURN</var> statement can be specified in a subroutine.

If a <var>JUMP</var> statement is used within a subroutine, its destination must be within the same subroutine. You cannot jump into a subroutine. 

A <var>STOP</var> statement, when executed inside a subroutine, terminates the request in the same manner as it does when executed outside a subroutine. 

===Examples using complex subroutines===

In the following example, an employee name with regular and overtime hours is passed to the subroutine <code>CALC.WAGES</code>. The total pay is returned and a list of records processed by the routine is updated.
BEGIN
DECLARE SUBROUTINE CALC.WAGES(FIXED DP 2, -
FIXED DP 2, STRING, FIXED DP 2 OUTPUT, -
LIST IN FILE EMPLOYEE INOUT)
.
.
.
CALL CALC.WAGES(%R.HRS, %OT.HRS, %NAME, -
%TOTAL.PAY, LIST EMPLST)
.
.
.
SUBROUTINE CALC.WAGES(%REG IS FIXED DP 2, -
%OT IS FIXED DP 2, -
%E.NAME IS STRING, -
%TOTAL IS FIXED DP 2 OUTPUT, -
LIST EMPLIST IN FILE EMPLOYEE INOUT)

%TEMP IS FIXED DP 2

WAGES1: IN EMPLOYEE FIND ALL RECORDS FOR WHICH
NAME = %E.NAME
END FIND
FOR EACH RECORD IN WAGES1
%TEMP = (RATE * %REG)
%TOTAL = %TEMP + (RATE * 1.5 * %OT)
END FOR
PLACE RECORDS IN WAGES1 ON LIST EMPLIST
RETURN
END SUBROUTINE
END


In the following example, an entire array is passed as a single subroutine parameter:
BEGIN
%NUMBERS IS FLOAT ARRAY(10,10)
%MAX IS FLOAT
DECLARE SUBROUTINE MAXIMUM(FLOAT ARRAY(*,*), FLOAT OUTPUT)
.
.
.
CALL MAXIMUM(%NUMBERS,%MAX)
.
.
.

SUBROUTINE MAXIMUM(%ARR IS FLOAT ARRAY(*,*), %M IS FLOAT OUTPUT)
%I IS FIXED
%J IS FIXED
%M = 0
FOR %I FROM 1 TO $arrsize('%ARR',1)
FOR %J FROM 1 TO $arrsize('%ARR',2)
IF %ARR(%I,%J) GT %M THEN
%M = %ARR(%I,%J)
END IF
END FOR
END FOR
END SUBROUTINE
END


==Sharing common elements==

An element that is not passed as a parameter can be shared between complex subroutines, or between a complex subroutine and the main request, when it is declared as a common element. A common element is created by using the <var>Declare</var> statement or by using the <var>Common</var> keyword on a <var>%variable Is</var> declaration. For an element to be shared, it must be declared as common in every place (each separate scope) in which it is used. 

Note: In [[Object oriented programming in SOUL|SOUL OOP]], the <var>Common</var> keyword is used for non-class properties and subroutines, which are typically defined for more confined, special-purpose uses (such as migration from SOUL to object-oriented SOUL). See [[Local and Common entities#Common methods and aliases|Common methods and aliases]].

===Scope of elements===

The scope of an element refers to the area within a request in which an element has a particular meaning. In User Language, complex subroutines have a different scope than the remainder of the request (the elements of a complex subroutine differ from the elements outside the subroutine even when they have the same name). This concept applies to labels, lists, %variables and %variable arrays, menus, screens, and images.

The elements of the main request (the statements not enclosed by any <var>Subroutine</var>/<var>End Subroutine</var> statements) and the elements of all simple subroutines share the same scope. Simple subroutines share the same elements with the main request and all other simple subroutines within the request. 

===Shareable elements===

The following elements can be shared if they are declared as common:

====%variables and %variable arrays====

You can share %variables if a <var>Declare %variable</var> or a <var>%variable Is</var> statement that declares the %variable as common is present in each portion of the request where you use the %variable. The %variable must have the same type, length, number of decimal places, and <var>Field Save</var> option in each declaration. 

====Lists of records====

You can share a list if a <var>Declare</var> statement that declares the list as common is contained in each place where you use the list. The declaration of the list must precede the first reference to that list, or <var class="product">Model 204</var> declares the list implicitly without the common attribute.

====Found sets====

You can share found sets if the label of the <var>Find</var> statement is declared as common. To effectively share a found set, follow these steps: 
<ol>
<li>Add a <var>Declare</var> statement that declares the statement label as common before the actual label in the portion of the request where the <var>Find</var> statement will be executed. </li>

<li>Add a <var>Declare</var> statement that declares the label as common to any parts of the request that require access to that found set. These parts, however, cannot contain a label with the same name, or a compiler error occurs. </li>
</ol>

After execution of the <var>Find</var> statement, you can access the record set in any portion of the request that contains the proper <var>Declare</var> statement. 

====Menus and screens====

You can share a menu or screen as common under the following conditions: 
<ul>
<li>The first reference to the menu or screen must be the complete definition of the menu or screen, with the <var>Common</var> keyword following the <var>Menu</var> or <var>Screen</var> statement. </li>

<li>Other parts of the request can reference the same menu or screen by using an abbreviated declaration of the form:
Declare [Menu menuname | Screen screenname] Common 

If the complete definition of the menu or screen exists, and if that definition was declared as common, the menu or screen is shared. If not, a compiler error results. Two or more complete menu or screen definitions with the <var>Common</var> keyword also result in a compiler error. 

If you use a menu or screen %variable (:%variable) within a complex subroutine to refer to a <var>Common</var> screen element, you must include a <var>Common</var> declaration for each possible value of the menu or screen name. 
</li>
</ul>

====Images====

The sharing of [[Images|images]] follows the same rules used for the sharing of menus and screens. If multiple images are contained within the same block, then the following rules also apply: 
<ul>
<li>You can use the <var>Common</var> keyword on only the first <var>Image</var> statement of an image block. All other images within the same block are automatically considered as candidates for sharing as common data.</li>

<li>All other parts of the request that access common images must contain the following abbreviated form of the <var>Declare</var> statement for each image to which access is required:
Declare Image imagename Common
</li>
</ul>

===Declare statement===

You can use the <var>Declare</var> statement to perform the following functions: 
<ul>
<li>Specify subroutine formal parameter types. </li>

<li>Specify variables, labels, lists, menus, screens, and images as <var>Common</var>. </li>
</ul>

Menus and screens are discussed in detail in [[Full-screen feature]]. 

Images are discussed in detail in [[Images]]. 

<ul>
<li>To declare lists without having to use an <code>In filename Clear List listname</code> clause. See [[Lists#Creating and clearing a list|Creating and clearing a list]]. </li>

<li>To declare %variables, see [[Using variables and values in computation#Declaring|Declaring %variables and %variable arrays]]. </li>
</ul>

====Syntax====

In the context of sharable elements, the format of the <var>Declare</var> statement is shown below. For information about using <var>Declare</var> for global elements, see [[Global features#Global objects|Global objects]]. For the detailed syntax of <var>Declare</var>, see [[Statement syntax#Declare|Statement syntax]].

Declare declaration


where declaration is one of the following:
Label label Common

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

Image imagename Common

Menu menuname Common

Screen screenname Common

%variable [Is] {Fixed [Dp n] | Float}
[Array(d1 [,d2 [,d3]])] [Common]

%variable [Is] String [Len n] [Dp {dn1 | *}]
[Array(d1 [,d2 [,d3]])] [No Field Save] [Common]

Subroutine subname[(type [inout-option] [,...]) ]


====Example====

For example, the <var>Declare</var> statement declares the list <code>RECNAMES</code> in the following request: 
BEGIN
DECLARE LIST RECNAMES
DECLARE SUBROUTINE REGION(LIST OUTPUT, STRING)
.
.
.
CALL REGION(LIST RECNAMES, 'NORTHEAST')
.
.
.
SUBROUTINE REGION(LIST RGNLST OUTPUT, %REGION IS STRING)

R1: IN EMPLOYEE FIND ALL RECORDS FOR WHICH REGION = %REGION
R2: PLACE RECORDS IN R1 ON LIST RGNLIST
END SUBROUTINE
END


===Defining common variables===

You can define common variables at the beginning of all programs without later redefinitions. The syntax lets you use the <var>%var Is Common</var> clause without duplicating the previous attributes. 

However, if attributes, such as <var>String</var> or <var>Len</var>, are included in the redefinition, which differ from those previously defined, a compilation error occurs. In addition, if the variable is not previously defined, it is allocated based on the current default variable definition. 

For example: 
BEGIN
VARIABLES ARE STRING LEN 20
%X IS STRING LEN 3 INITIAL ('AAA') STATIC COMMON
SUBROUTINE A
* full definition on next line no longer required
** %X IS STRING LEN 3 INITIAL ('AAA') STATIC COMMON
* new syntax on next line replaces previous line
%X IS COMMON /? defaults to previous %X definition ?/
CALL B
END SUBROUTINE

SUBROUTINE B
* But next line will fail compile since %X already exists
%X IS STRING LEN 4 COMMON /? compiler error ?/
* And the next line will result in a default definition
* since %Y is not previously defined.
%Y IS COMMON
END SUBROUTINE
PRINT %X
CALL A
END


===Shared common element examples===

The following examples illustrate the differences between data that is locally scoped and data that is shared using the <var>Common</var> keyword. 

====Example 1====

In this example, the variable <code>%I</code> assumes different values depending upon which part of the request is being executed: 
BEGIN
%I IS FIXED
DECLARE SUBROUTINE SUBR1(STRING)
.
.
.
FOR %I FROM 1 TO 10
CALL SUBR1(%ARR(%I))
END FOR
.
.
.
SUBROUTINE SUBR1(%A IS STRING)
%I IS FIXED
FOR %I FROM 1 TO 10
PRINT %I and %A
END FOR
END SUBROUTINE
END


====Example 2====

In this example, the screen <code>EXAMPLE</code> and the <code>%A</code> and <code>%B</code> variables retain the same values no matter which part of the request is being executed: 
BEGIN
SCREEN EXAMDEF COMMON
TITLE 'THIS IS A COMMON SCREEN DEFINITION'
PROMPT 'ENTER VALUE'
INPUT FLD1 AT 10 LEN 20 PAD '_'
END SCREEN
%A IS STRING LEN 10 COMMON
%B IS FLOAT COMMON
DECLARE SUBROUTINE SUBR1(STRING LEN 10)
.
.
.
SUBROUTINE SUBR1(%Z IS STRING LEN 10)
DECLARE SCREEN EXAMDEF COMMON
%A IS STRING LEN 10 COMMON
%B IS FLOAT COMMON
.
.
.
END


====Example 3====

In this example, the main request and the subroutine share the common data of an array and a found set:
BEGIN
%COM.ARRAY IS STRING LEN 10 ARRAY(10,10) COMMON
DECLARE LABEL ALL.RECS COMMON
%I IS FIXED
DECLARE SUBROUTINE EXAMPLE
.
.
.
ALL.RECS: FIND ALL RECORDS
END FIND
%I = 0
%J = 1
FOR 10 RECORDS IN ALL.RECS
%I = %I + 1
%COM.ARRAY(%I,%J) = FLD
END FOR
CALL EXAMPLE
STOP

SUBROUTINE EXAMPLE
%COM.ARRAY IS STRING LEN 10 ARRAY(10,10) COMMON
DECLARE LABEL ALL.RECS COMMON
%I IS FIXED
%I = 0
%J = 2
FOR 10 RECORDS IN ALL.RECS
%I = %I + 1
%COM.ARRAY(%I,%J) = FLD2
END FOR
END SUBROUTINE
END


In the preceding example, the main request updates column 1 of the array <code>%COMM.ARRAY</code> with the contents of <code>FLD</code>. The subroutine, <code>EXAMPLE</code>, updates column 2 of the same array with the contents of <code>FLD2</code>. Both the array <code>%COM.ARRAY</code> and the found set <code>ALL.RECS</code> are shared by using the <var>Common</var> keyword. <code>%I</code> and <code>%J</code> are both local variables. <code>%I</code> is local because it was declared without the <var>Common</var> keyword; <code>%J</code> is local because it was not declared at all. 

==On units==

An <var>On</var> unit lets you specify a course of action following a triggering event, such as the terminal operator pressing one of the <var>Attention</var> identifier (AID) keys. The <var>On</var> unit provides an application with a way to override the normal system response. 

====Syntax====

To define an <var>On</var> unit, use an <var>On</var> block in the following format:
[label] On unittype
statement
...
End On


where <var class="term">unittype</var> is one of the following:
<table>
<tr class="head">
<th>unittype</th>
<th>You can specify the course of action to take if...</th>
</tr>

<tr>
<td>ATTENTION</td>
<td>The end user invokes the attention feature (for example, presses the <var>BREAK, ATTN,</var> or <var>PA1</var> key, or enters <var>*CANCEL</var>). </td>
</tr>

<tr>
<td>ERROR</td>
<td><var class="product">Model 204</var> cancels a request. Before a request is canceled or, for transaction backout files, after the current transaction is backed out, the ON ERROR unit is processed instead of returning control to the terminal command level. For more information on transaction backout files, see [[Data recovery]]. </td>
</tr>

<tr>
<td nowrap>FIELD CONSTRAINT
CONFLICT (FCC)</td>
<td>There are field level constraint conflicts. Violating the UNIQUE and AT-MOST-ONE attributes causes field-level conflicts.*</td>
</tr>

<tr>
<td>FIND CONFLICT</td>
<td>A conflict arises evaluating a FIND statement or a FOR EACH RECORD statement used for retrieval.</td>
</tr>

<tr>
<td>MISSING FILE</td>
<td>A remote file is no longer available.</td>
</tr>

<tr>
<td>MISSING MEMBER</td>
<td>A remote optional member is no longer available.</td>
</tr>

<tr>
<td>RECORD LOCKING CONFLICT</td>
<td>A conflict arises during a record locking attempt.</td>
</tr>
</table>

*If you have procedures written for <var class="product">Model 204</var> V2R1.0 that use ON FCC for UNIQUE fields, and you are planning to use ON FCC for AT-MOST-ONE fields, you might need to rewrite the ON FCC unit to take the new value of $UPDSTAT (2 for AT-MOST-ONE) into account. 

Several $functions provide information about conflicts. They are:
<table>
<tr>
<td>[[$UpdFile]]</td>
<td>[[$UpdFld]]</td>
<td>[[$UpdOval]]</td>
<td>[[$UpdRec]]</td>
</tr>
<tr>
<td>[[$UpdStat]]</td>
<td>[[$UpdStmt]]</td>
<td>[[$UpdVal]]</td>
<td>[[$UnqRec]]</td>
</tr>
</table>

===Body of an On unit===

The body of the <var>On</var> unit consists of statements immediately following the <var>On</var> statement. Any User Language statement can appear within an <var>On</var> unit except the SUBROUTINE statement.

===Ending an On unit===

You must conclude an ON unit with either an END ON statement or an END BLOCK statement. The format of the END ON statement is as follows:
END ON [label]


where <var class="term">label</var> is the label of the statement that began the ON statement. 

===Processing an On unit===

When an <var>On</var> statement is evaluated, <var class="product">Model 204</var> remembers the location of the <var>On</var> unit body (the statement after the <var>On</var> statement and within the unit), but does not immediately evaluate the body. Instead, it passes control to the statement immediately following the <var>On</var> unit. The <var>On</var> unit body is evaluated only when the triggering event takes place.

===Usage guidelines for On units===

Note the following considerations when using <var>On</var> units:
<ul>
<li>You must define the <var>On</var> unit before it is invoked (that is, you should typically place the <var>On</var> unit near the beginning of your procedure). </li>

<li>A subsequent definition of an <var>On</var> unit of the same kind replaces the previous one. For example, if you define two ON ATTN units, the second one becomes the current one.</li>

<li>You can jump to destinations within the same <var>On</var> unit. </li>

<li>You can jump out of an <var>On</var> unit only to unnested, labeled statements.</li>

<li>You cannot jump into an <var>On</var> unit.</li>

<li>You can jump outside of an ON unit only if the <var>On</var> unit is part of a main routine or part of a complex subroutine. </li>

<li>You cannot jump out of an <var>On</var> unit contained in a simple subroutine, regardless of whether the destination is within the subroutine or back in the mainline program, because <var>On</var> units are part of the mainline program; hence, there is no scoping of ON units. This restriction ensures that the <var>On</var> unit is executed and the control returned to the main routine.</li>

<li>An <var>On</var> unit definition is not preserved when a request is continued with an END MORE statement and a MORE command. Each new request continuation must define its own <var>On</var> units. (See [[Large request considerations#Rules for request continuation|Rules for request continuation]].)</li>

<li>For complex subroutines, an active <var>On</var> unit is temporarily disabled when a subroutine is called that contains an <var>On</var> UNIT of the same type; it is restored when the subroutine returns. Any ON unit enabled during the execution of a subroutine is replaced by the active <var>On</var> unit at the time of the last CALL statement as soon as the RETURN statement is evaluated.</li>

<li><var>On</var> units coded inside complex subroutines can contain JUMP statements that specify a destination outside the <var>On</var> unit. The destination must be to an unnested labeled statement within the complex subroutine. Also, if the <var>On</var> unit is to be jumped out of, the condition that causes the <var>On</var> unit to be invoked must be raised in the subroutine that contains the <var>On</var> unit.

This prevents a lower level subroutine from returning inadvertently by raising a condition for which there is an <var>On</var> unit coded in a higher level subroutine. If the inadvertent return is attempted, the request is canceled. 
</li>

<li><var>On</var> units do not have their own local data and labels. They inherit the scope of the part of the program in which they are compiled. An <var>On</var> unit that is compiled within a complex subroutine is considered part of only that subroutine.
</li>
</ul>

====Example====

In the following example, if the user presses the<var> ATTN</var> key instead of entering a response to the prompt in the GET.REC.TYPE statement, the <code>ON ATTENTION</code> unit sets %FLAG to 1. The FLAG.SET statement tests %FLAG. If %FLAG is set, the request branches to END.REQUEST and the FIND statement is not executed. 
%FLAG=0
ON ATTENTION
%FLAG=1
BYPASS
END ON
GET.REC.TYPE: %TYPE=$READ('ENTER RECORD TYPE')
FLAG.SET: IF %FLAG=1 THEN
JUMP TO END.REQUEST
END IF
FIND.RECS: FIND ALL RECORDS FOR WHICH
TYPE = %TYPE
END FIND
.
.
.
END.REQUEST:
END


===Only one On unit at a time===

Only one <var>On</var> unit of each kind is active at a time. For example, the processing of a second ON ERROR statement resets the current ON ERROR unit, but does not affect the current ON ATTENTION unit. Thus, you can redefine what to do in a variety of cases by having several ON statements and units within a request. An <var>On</var> unit can be redefined within another <var>On</var> unit.

===Passing control to and from On units===

<var class="product">Model 204</var> passes control to an <var>On</var> unit when the triggering event occurs. For example, an ON ATTENTION unit receives control when a user presses one of the ATTENTION identifier (AID) keys at the terminal during the execution of a request. Use one of the following statements to return control to the body of the request. 

====BYPASS statement====

The BYPASS statement handles the various unittypes of an <var>On</var> statement as follows:
<table>
<tr class="head">
<th>For unittype...</th>
<th>The BYPASS statement...</th>
</tr>
<tr>
<td>ON MISSING FILE 
ON MISSING MEMBER</td>
<td>Returns control to the statement immediately after the END FOR statement that closes the current FOR loop. </td>
</tr>
<tr>
<td>ON ERROR</td>
<td>Ends the request.</td>
</tr>
<tr>
<td nowrap>ON ATTENTION 
ON FIND CONFLICT 
ON RECORD LOCKING CONFLICT</td>
<td>Returns control to the statement immediately after the statement that invoked the <var>On</var> unit.</td>
</tr>
</table>

The format of the BYPASS statement is as follows:
BYPASS [PENDING STATEMENT]


where the PENDING STATEMENT keyword is optional. If the <var>On</var> unit is not ended with a BYPASS statement, <var class="product">Model 204</var> automatically generates a STOP statement at the end of the unit. 

====CONTINUE statement====

The CONTINUE statement is supported only with the Parallel Query Option. If you lose access to a group member that is an optional file during FOR processing, the CONTINUE statement continues FOR processing with the next available file, and skips any other unavailable files.

====JUMP TO statement====

The JUMP statement, when used to jump to a labeled statement outside the ON unit, causes the request to continue at that point. There are restrictions pertaining to jumps; see [[Flow of control in User Language#Branching statements|Branching statements]] and [[#Simple subroutines|Simple subroutines]]. 

====RETRY statement====

The RETRY statement passes control to the statement that invoked the ON unit, thereby retrying that statement. The RETRY statement is not valid in an ON ERROR unit.

The format of the RETRY statement is as follows:
RETRY [PENDING STATEMENT]


where the <var>PENDING STATEMENT</var> keyword is optional.

====STOP statement====

The STOP statement is used to end the request. 

===Clearing On units===

You can issue the following statement to clear the definition of an <var>On</var> unit: 
CLEAR ON unittype


This statement clears any defined <var>On</var> unit of the type specified. Clearing an ON unit produces the following results:

<ul>
<li>After a CLEAR ON ATTENTION, pressing one of the ATTENTION identifier (AID) keys at the terminal does not invoke the ON ATTENTION unit.</li>

<li>After a CLEAR ON ERROR, a request cancellation error does not invoke the ON ERROR unit. </li>
</ul>

An <var>On</var> unit can be defined, cleared, and then redefined. 

===Pausing during the request===

The <var>[[Pause statement|Pause]]</var> statement can be used with <var>On</var> units to cause the request to wait a specified number of seconds and then to retry the statement that caused the evaluation of the <var>On</var> unit. <var>Pause</var> is typically used with the other <var>On</var> unit types (<var>On Record Locking Conflict</var> and <var>On Find Conflict</var>) and is discussed in [[Record level locking and concurrency control]]. 

The <var>[[$WakeUp]]</var> function is an alternative approach; it offers millisecond resolution pausing.

</div> 

[[Category:SOUL]]

CREATE command: Temporary group

2025-01-23T00:42:45Z

JDamon: /* Temporary group parameters */

==Summary==
<dl>
<dt>Privileges
<dd>Any user
<dt>Function
<dd>Creates a <var class="product">Model 204</var> temporary file group
</dl>

==Syntax==
CREATE [TEMP] GROUP <var class="term">groupname</var>
FROM {<var class="term">filename</var> [AT <var class="term">location</var>]
[(OPTIONAL) | (MANDATORY)]} ,...
[PARAMETER <var class="term">parameter</var>[=<var class="term">value</var>]
[,<var class="term">parameter</var>[=<var class="term">value</var>]]...
.
.
.
END


Where:
<table>
<tr>
<th>groupname</th>
<td>The name of the temporary file group that is being created (1 to 8 characters). The group name cannot be <code>FILE</code> or <code>GROUP</code>, and it cannot start with <code>CCA</code>, <code>SYS</code>, <code>OUT</code>, <code>TAPE</code>, dollar sign (<tt>$</tt>), or percent sign (<tt>%</tt>).

The group name can contain any alphanumeric characters except those in the following table: 
<table>
<tr class="head"> <th>Character name </th>
<th>Keyboard symbol</th> </tr>

<tr> <th><var>Asterisk</var></th>
<td>( * )</td> </tr>

<tr> <th><var>Equal sign </var></th>
<td>( = )</td> </tr>

<tr> <th><var>Left parenthesis </var></th>
<td>( ( )</td> </tr>

<tr> <th><var>Minus sign</var></th>
<td>( - )</td> </tr>

<tr> <th><var>Plus sign </var></th>
<td>( + )</td> </tr>

<tr> <th><var>Right parenthesis </var></th>
<td>( ) )</td> </tr>

<tr> <th><var>Semicolon</var></th>
<td>( ; )</td> </tr>

<tr> <th><var>Single quote </var></th>
<td>( ' ) </td> </tr>

<tr> <th><var>Slash </var></th>
<td>( / )</td> </tr>

<tr> <th><var>Space </var></th>
<td></td> </tr>
</table>
</td></tr>

<tr>
<th>filename</th>
<td>The name of a <var class="product">Model 204</var> file.

If you are specifying [[PQO|Parallel Query Option/204]] remote files, <var class="term">filename</var> must include a remote location (AT <var class="term">location</var>) or be a defined file synonym. Also, you cannot specify multiple identifiers for the same file: that is, you cannot include two synonyms for the same file, and you cannot include a synonym and a remote file specification for the same file. 
</td>
</tr>

<tr>
<th>location</th>
<td>For PQO files, <var class="term">location</var> is the symbolic name (as many as eight characters) that refers to the location of the node on which the remote file resides. An unquoted equal sign (<tt>=</tt>) specifies that the file is local.</td></tr>

<tr>
<th><var>OPTIONAL</var> or <var>MANDATORY</var></th>
<td>Indicates whether PQO scattered group operations can proceed in the absence of this group member. The default is <var>MANDATORY</var>. Valid abbreviations are <var>OPT</var> and <var>MAND</var>.

You cannot open a group if a mandatory member is unavailable. Also, you cannot specify <var>OPTIONAL</var> for local files.</td></tr>

<tr>
<th>parameter=value</th>
<td>Specifies <var class="product">Model 204</var> temporary group parameters. Multiple <var>PARAMETER</var> statements can follow, and each statement can contain as many parameters in any order as will fit on one input line. Valid temporary group parameters are described in [[#Temporary group parameters|Temporary group parameters]], below.</td></tr>
</table>

==Example==
CREATE GROUP REGION FROM DELAWARE, MARYLAND, VIRGINIA 
*** M204.0825: READING GROUP PARAMETERS
PARAMETER PROCFILE = VIRGINIA
END
*** M204.0828: TEMP GROUP CREATED: REGION


==Usage notes==
<ul>
<li>The <var>CREATE TEMP GROUP</var> command creates a temporary file group from the <var class="product">Model 204</var> files specified in the command. A temporary group is established by a user for use during the current login session. </li>

<li>A temporary group can be referenced only by the user who creates it.
The temporary group ceases to exist when the user logs out. </li>

<li>If you omit <code>TEMP</code> from the <var>CREATE GROUP</var> command, <var class="product">Model 204</var> assumes you are creating a temporary group.</li>
</ul>

===Temporary group parameters===
The [[#Example|CREATE GROUP REGION example]] above shows how group parameters can be specified. The <var class="product">Model 204</var> temporary group parameters that can be set in the <var>CREATE</var> command's parameter list are shown in the table below:
<table>
<tr class="head"> <th>Parameter</th>
<th>Defines...</th> </tr>

<tr> <th><var>UPDTFILE</var></th>
<td>Group's update file for the STORE RECORD statement. </td> </tr>

<tr> <th><var>PROCFILE</var></th>
<td>Group's procedure file, or specifies that the group can contain multiple procedure files. </td> </tr>

<tr> <th><var>BLDGFT</var></th>
<td>Whether to build an internal field table for this group. Can be YES or NO; YES is the default. </td> </tr>
</table>

<ul>
<li>The <var>UPDTFILE</var> parameter defines the group's update file for the STORE RECORD statement. When a SOUL <var>Store Record</var> statement is encountered in group context, and <var class="product">Model 204</var> cannot determine a file context, the record is stored in the group-update file. If <var>UPDTFILE</var> is not specified, no update file is assigned and any attempt to issue a STORE RECORD statement will fail with:
M204.0203: "Store" requires update file
In that case, use the "IN FILE" or 'IN MEMBER" clause with STORE RECORD:
IN FILE filename STORE RECORD
IN GROUP groupname MEMBER %membername STORE RECORD


The [[$Update]] function also provides a convenient method for manipulating the update file. </li>

<li>The <var>PROCFILE</var> parameter defines the group's procedure file. All procedure-related commands and the <var>INCLUDE</var> statement operate on this file if no other file context is established. If this parameter is omitted, no procedure file is assigned.

You can also use <var>PROCFILE</var> to specify multiple procedure files for a group. If a group contains multiple procedure files, then the <var>INCLUDE</var> statement searches the entire group for the procedure to be included. The search proceeds in order from the first file defined in the <var>CREATE GROUP</var> command to the last. 

To allow for multiple procedure files, specify <code>PROCFILE = *</code>, which indicates that any of the files in a group can contain procedures. This specification is optional; use it only if more than one file in the group contains procedures that you want to include.

For more information, see [[Application Subsystem development#Multiple procedure files|multiple procedure files]]. </li>

<li>The <var>BLDGFT</var> parameter, if <code>YES</code> (the default), directs <var class="product">Model 204</var> to maintain certain information about the group in an internal field table. The option to specify depends upon how long you expect to use the group. If the group is only to satisfy a few short requests, specify <code>NO</code>.</li>
</ul>

==See also==
<ul>
<li>[[CREATE command: Permanent group]] </li>
</ul>

[[Category: User commands]]
[[Category:Commands]]

CREATE command: Temporary group

2025-01-17T02:44:01Z

JDamon: /* Temporary group parameters */

==Summary==
<dl>
<dt>Privileges
<dd>Any user
<dt>Function
<dd>Creates a <var class="product">Model 204</var> temporary file group
</dl>

==Syntax==
CREATE [TEMP] GROUP <var class="term">groupname</var>
FROM {<var class="term">filename</var> [AT <var class="term">location</var>]
[(OPTIONAL) | (MANDATORY)]} ,...
[PARAMETER <var class="term">parameter</var>[=<var class="term">value</var>]
[,<var class="term">parameter</var>[=<var class="term">value</var>]]...
.
.
.
END


Where:
<table>
<tr>
<th>groupname</th>
<td>The name of the temporary file group that is being created (1 to 8 characters). The group name cannot be <code>FILE</code> or <code>GROUP</code>, and it cannot start with <code>CCA</code>, <code>SYS</code>, <code>OUT</code>, <code>TAPE</code>, dollar sign (<tt>$</tt>), or percent sign (<tt>%</tt>).

The group name can contain any alphanumeric characters except those in the following table: 
<table>
<tr class="head"> <th>Character name </th>
<th>Keyboard symbol</th> </tr>

<tr> <th><var>Asterisk</var></th>
<td>( * )</td> </tr>

<tr> <th><var>Equal sign </var></th>
<td>( = )</td> </tr>

<tr> <th><var>Left parenthesis </var></th>
<td>( ( )</td> </tr>

<tr> <th><var>Minus sign</var></th>
<td>( - )</td> </tr>

<tr> <th><var>Plus sign </var></th>
<td>( + )</td> </tr>

<tr> <th><var>Right parenthesis </var></th>
<td>( ) )</td> </tr>

<tr> <th><var>Semicolon</var></th>
<td>( ; )</td> </tr>

<tr> <th><var>Single quote </var></th>
<td>( ' ) </td> </tr>

<tr> <th><var>Slash </var></th>
<td>( / )</td> </tr>

<tr> <th><var>Space </var></th>
<td></td> </tr>
</table>
</td></tr>

<tr>
<th>filename</th>
<td>The name of a <var class="product">Model 204</var> file.

If you are specifying [[PQO|Parallel Query Option/204]] remote files, <var class="term">filename</var> must include a remote location (AT <var class="term">location</var>) or be a defined file synonym. Also, you cannot specify multiple identifiers for the same file: that is, you cannot include two synonyms for the same file, and you cannot include a synonym and a remote file specification for the same file. 
</td>
</tr>

<tr>
<th>location</th>
<td>For PQO files, <var class="term">location</var> is the symbolic name (as many as eight characters) that refers to the location of the node on which the remote file resides. An unquoted equal sign (<tt>=</tt>) specifies that the file is local.</td></tr>

<tr>
<th><var>OPTIONAL</var> or <var>MANDATORY</var></th>
<td>Indicates whether PQO scattered group operations can proceed in the absence of this group member. The default is <var>MANDATORY</var>. Valid abbreviations are <var>OPT</var> and <var>MAND</var>.

You cannot open a group if a mandatory member is unavailable. Also, you cannot specify <var>OPTIONAL</var> for local files.</td></tr>

<tr>
<th>parameter=value</th>
<td>Specifies <var class="product">Model 204</var> temporary group parameters. Multiple <var>PARAMETER</var> statements can follow, and each statement can contain as many parameters in any order as will fit on one input line. Valid temporary group parameters are described in [[#Temporary group parameters|Temporary group parameters]], below.</td></tr>
</table>

==Example==
CREATE GROUP REGION FROM DELAWARE, MARYLAND, VIRGINIA 
*** M204.0825: READING GROUP PARAMETERS
PARAMETER PROCFILE = VIRGINIA
END
*** M204.0828: TEMP GROUP CREATED: REGION


==Usage notes==
<ul>
<li>The <var>CREATE TEMP GROUP</var> command creates a temporary file group from the <var class="product">Model 204</var> files specified in the command. A temporary group is established by a user for use during the current login session. </li>

<li>A temporary group can be referenced only by the user who creates it.
The temporary group ceases to exist when the user logs out. </li>

<li>If you omit <code>TEMP</code> from the <var>CREATE GROUP</var> command, <var class="product">Model 204</var> assumes you are creating a temporary group.</li>
</ul>

===Temporary group parameters===
The [[#Example|CREATE GROUP REGION example]] above shows how group parameters can be specified. The <var class="product">Model 204</var> temporary group parameters that can be set in the <var>CREATE</var> command's parameter list are shown in the table below:
<table>
<tr class="head"> <th>Parameter</th>
<th>Defines...</th> </tr>

<tr> <th><var>UPDTFILE</var></th>
<td>Group's update file. </td> </tr>

<tr> <th><var>PROCFILE</var></th>
<td>Group's procedure file, or specifies that the group can contain multiple procedure files. </td> </tr>

<tr> <th><var>BLDGFT</var></th>
<td>Whether to build an internal field table for this group. Can be YES or NO; YES is the default. </td> </tr>
</table>

<ul>
<li>The <var>UPDTFILE</var> parameter defines the group's update file for the STORE RECORD statement. When a SOUL <var>Store Record</var> statement is encountered in group context, and <var class="product">Model 204</var> cannot determine a file context, the record is stored in the group-update file. If <var>UPDTFILE</var> is not specified, no update file is assigned and any attempt to issue a STORE RECORD statement will fail with:
M204.0203: "Store" requires update file
In that case, use the "IN FILE" or 'IN MEMBER" clause with STORE RECORD:
IN FILE filename STORE RECORD
IN GROUP groupname MEMBER %membername STORE RECORD


The [[$Update]] function also provides a convenient method for manipulating the update file. </li>

<li>The <var>PROCFILE</var> parameter defines the group's procedure file. All procedure-related commands and the <var>INCLUDE</var> statement operate on this file if no other file context is established. If this parameter is omitted, no procedure file is assigned.

You can also use <var>PROCFILE</var> to specify multiple procedure files for a group. If a group contains multiple procedure files, then the <var>INCLUDE</var> statement searches the entire group for the procedure to be included. The search proceeds in order from the first file defined in the <var>CREATE GROUP</var> command to the last. 

To allow for multiple procedure files, specify <code>PROCFILE = *</code>, which indicates that any of the files in a group can contain procedures. This specification is optional; use it only if more than one file in the group contains procedures that you want to include.

For more information, see [[Application Subsystem development#Multiple procedure files|multiple procedure files]]. </li>

<li>The <var>BLDGFT</var> parameter, if <code>YES</code> (the default), directs <var class="product">Model 204</var> to maintain certain information about the group in an internal field table. The option to specify depends upon how long you expect to use the group. If the group is only to satisfy a few short requests, specify <code>NO</code>.</li>
</ul>

==See also==
<ul>
<li>[[CREATE command: Permanent group]] </li>
</ul>

[[Category: User commands]]
[[Category:Commands]]

CREATE PERM GROUP command

2025-01-17T02:40:30Z

JDamon: /* Syntax */

==Summary==
<dl>
<dt>Privileges
<dd>System manager
<dt>Function
<dd>Creates a <var class="product">Model 204</var> permanent [[Files,_groups,_and_reference_context#File_groups|file group]]
</dl>

==Syntax==
CREATE PERM GROUP <var class="term">groupname</var>
FROM {<var class="term">filename</var> [AT <var class="term">location</var>]
[(OPTIONAL) | (MANDATORY)]} ,...
[PARAMETER <var class="term">parameter</var>[=<var class="term">value</var>]
[PARAMETER <var class="term">parameter</var>[=<var class="term">value</var>]]...
.
.
.
END


Where:
<table>
<tr>
<th>groupname</th>
<td>The name of the permanent file group that is being created (1 to 8 characters). The group name cannot be <code>FILE</code> or <code>GROUP</code>, and it cannot start with <code>CCA</code>, <code>SYS</code>, <code>OUT</code>, <code>TAPE</code>, dollar sign (<tt>$</tt>), or percent sign (<tt>%</tt>).

The group name can contain any alphanumeric characters except those shown in the following table: 
<table>
<tr class="head"> <th>Character name </th> <th>Keyboard symbol</th> </tr>

<tr> <th><var>Asterisk</var></th>
<td>(*)</td> </tr>

<tr> <th><var>Equal sign </var></th>
<td>(=)</td> </tr>

<tr> <th><var>Left parenthesis </var></th>
<td>(()</td> </tr>

<tr> <th><var>Minus sign</var></th>
<td>(-)</td> </tr>

<tr> <th><var>Plus sign </var></th>
<td>(+)</td> </tr>

<tr> <th><var>Right parenthesis </var></th>
<td>())</td> </tr>

<tr> <th><var>Semicolon</var></th>
<td>(;)</td> </tr>

<tr> <th><var>Single quote </var></th>
<td>(') </td> </tr>

<tr> <th><var>Slash </var></th>
<td>(/)</td> </tr>

<tr> <th><var>Space </var></th>
<td></td> </tr>
</table>
</td></tr>

<tr>
<th>filename</th>
<td>The name of a <var class="product">Model 204</var> file.
If you are specifying [[PQO|Parallel Query Option/204]] remote files, <var class="term">filename</var> must include a remote location (<var>AT</var> <var class="term">location</var>) or be a defined file synonym. Also, do not specify multiple identifiers for the same file; that is, you cannot include two synonyms for the same file, and you cannot include a synonym and a remote file specification for the same file. A group may have up to 254 files.
</td></tr>

<tr>
<th>location</th>
<td>For PQO files, <var class="term">location</var> is the symbolic name (as many as eight characters) that refers to the location of the node on which the remote file resides. An unquoted equal sign (<tt>=</tt>) specifies that the file is local.</td></tr>

<tr>
<th><var>OPTIONAL</var> or <var>MANDATORY</var></th>
<td>Indicates whether PQO scattered group operations can proceed in the absence of this group member. The default is <var>MANDATORY</var>. Valid abbreviations are <var>OPT</var> and <var>MAND</var>.

You cannot open a group if a mandatory member is unavailable. Also, you cannot specify <var>OPTIONAL</var> for local files.
</td></tr>

<tr>
<th>parameter</th>
<td>Specifies <var class="product">Model 204</var> group parameters. Any number of <var>PARAMETER</var> statements can follow, and each can contain as many parameters in any order as fit on one input line. Valid permanent group parameters are described in the table below. All but <code>PRIVATE</code>, <code>PUBLIC</code>, and <code>SEMIPUB</code> must be followed by a value:
<table>
<tr class="head"> <th>Parameter</th> <th>Meaning</th> </tr>

<tr>
<th><var>ADDLVL</var></th>
<td>Identifies the <var>ADD</var> field level security access level for the files making up the group. The default is 0. </td> </tr>

<tr>
<th><var>BLDGFT </var></th>
<td>Indicates whether to build an internal field table for this group. Can be <code>YES</code> (default) or <code>NO</code>.

<var>BLDGFT</var> is ignored for groups that include remote members.</td> </tr>

<tr>
<th><var>MAXFAIL</var></th> <td>For scattered groups (PQO), the maximum number of optional members that can be unavailable. If more than <var>MAXFAIL</var> files are unavailable, the group fails to open or operations on the group are aborted.

The value of <var>MAXFAIL</var> must be one of the following: 
<ul>
<li>An integer between one and the number of optional group members. </li>

<li>An asterisk (<tt>*</tt>), which is equivalent to the number of optional members in the group. This setting means that the group can function without any of its optional members. This is the default. </li>
</ul>

For ad hoc scattered groups, <var>MAXFAIL</var> is always set to the default.
</td> </tr>

<tr>
<th><var>PCLASSDF</var></th>
<td>Identifies the default user class with respect to the procedures defined for a permanent group. </td> </tr>

<tr>
<th><var>PRIVATE</var></th>
<td>Indicates that users are asked for a group password when they open the group. The password entered must be valid to open the group. </td> </tr>

<tr>
<th><var>PRIVDEF</var></th>
<td>Indicates the default privileges for public and semi-public groups. If not specified, default group privileges are set to X'3FFF' (all privileges). </td> </tr>

<tr>
<th id="PROCFILE"><var>PROCFILE</var></th>
<td>Defines the group's procedure file. Multiple procedure files can be specified with <code>PROCFILE = *</code>, as explained in [[CREATE command: Temporary group#Temporary group parameters|Temporary group parameters]].

With scattered groups, <var>PROCFILE</var> must refer to a local file, and its value cannot be an asterisk (<tt>*</tt>). 
</td> </tr>

<tr>
<th><var>PUBLIC</var></th>
<td>Indicates that users are not asked for a group password when they open the group and are automatically given default group privileges. If none of the parameters <var>PUBLIC</var>, <var>SEMIPUB</var>, or <var>PRIVATE</var> is specified, <var>PUBLIC</var> is the default. </td> </tr>

<tr>
<th><var>READLVL</var></th>
<td>Identifies the <var>READ</var> field level security access level for the files making up the group. The default is 0. </td> </tr>

<tr>
<th><var>SELLVL</var></th>
<td>Identifies the <var>SELECT</var> access level for the fields in the files making up the group. The default is 0. </td> </tr>

<tr>
<th><var>SEMIPUB</var></th>
<td>Indicates that users are asked for a group password to open the group. If the password is valid, the group is opened with the privileges assigned to that password. If the password is invalid, the group is opened with the default group privileges. </td> </tr>

<tr>
<th><var>UPDTFILE</var></th>
<td>Defines the group's update file for the STORE RECORD statement.

<ul>
<li>When a SOUL <var>Store Record</var> statement is encountered in a group context, and <var class="product">Model 204</var> cannot determine a file context, the record is stored in the group-update file. If <var>UPDTFILE</var> is not specified, no update file is assigned and any attempt to issue a STORE RECORD statement will fail with:
M204.0203: "Store" requires update file
In that case, use the "IN FILE" or 'IN MEMBER" clause with STORE RECORD:
IN FILE filename STORE RECORD
IN GROUP groupname MEMBER %membername STORE RECORD


The [[$Update]] function also provides a convenient method for manipulating the update file. </li>

If used in PQO, <var>UPDTFILE</var> can refer to either local or remote files. If the update file you are naming is a remote file, you can include its remote file specification (AT <var class="term">location</var>). 
</td> </tr>

<tr>
<th><var>UPDTLVL</var></th>
<td>Identifies the <var>UPDATE</var> field level security access level for the files making up the group. The default is 0.
</td> </tr>
</table>
</td></tr>
</table>

===Syntax notes===
Commas and equal signs are optional.

==Example==
CREATE PERM GROUP ACCOUNT FROM ACC1, ACC2, ACC3, ACC4
*** M204.0825: READING GROUP PARAMETERS
PARAMETER PROCFILE = ACC1, PRIVDEF = X'3FFF'
END
*** M204.0830: PERM GROUP CREATED


==Usage notes==
<ul>
<li>The <var>CREATE PERM GROUP</var> command creates a permanent file group from the files specified in the command. A permanent group is a group established by the system manager and maintained permanently in an external file (the [[Storing_and_using_file_group_definitions_(CCAGRP)|CCAGRP]] file) until it is explicitly deleted. Before a permanent group can be created, the system manager must create the CCAGRP file in which the group definitions are stored. This is accomplished with the <var>[[CREATEG_command|CREATEG]]</var> command.</li>

<li>When it processes <var>CREATE PERM GROUP</var>, <var class="product">Model 204</var> ends any update unit in progress and begins a [[File integrity and recovery#Model 204 update units|non-backoutable update unit]]. </li>

<li>Duplicate identifiers for a local file are detected when <var class="product">Model 204</var> tries to open the group. A <var class="product">Model 204</var> messages tells you the name of the file duplicates that result from using file synonyms. You cannot:
<ul>
<li>
Specify multiple identifiers for the same file in a CREATE GROUP command: that is, you cannot include two synonyms for the same file.
</li>

<li>
Include a synonym and a remote file specification for the same file.</li>
</ul></li>
</ul>

==See also==
<ul>
<li>[[CREATE command: Temporary group]] </li>
</ul>

[[Category: System manager commands]]
[[Category:Commands]]

CREATE command: Temporary group

2025-01-17T01:30:08Z

JDamon: /* Temporary group parameters */

==Summary==
<dl>
<dt>Privileges
<dd>Any user
<dt>Function
<dd>Creates a <var class="product">Model 204</var> temporary file group
</dl>

==Syntax==
CREATE [TEMP] GROUP <var class="term">groupname</var>
FROM {<var class="term">filename</var> [AT <var class="term">location</var>]
[(OPTIONAL) | (MANDATORY)]} ,...
[PARAMETER <var class="term">parameter</var>[=<var class="term">value</var>]
[,<var class="term">parameter</var>[=<var class="term">value</var>]]...
.
.
.
END


Where:
<table>
<tr>
<th>groupname</th>
<td>The name of the temporary file group that is being created (1 to 8 characters). The group name cannot be <code>FILE</code> or <code>GROUP</code>, and it cannot start with <code>CCA</code>, <code>SYS</code>, <code>OUT</code>, <code>TAPE</code>, dollar sign (<tt>$</tt>), or percent sign (<tt>%</tt>).

The group name can contain any alphanumeric characters except those in the following table: 
<table>
<tr class="head"> <th>Character name </th>
<th>Keyboard symbol</th> </tr>

<tr> <th><var>Asterisk</var></th>
<td>( * )</td> </tr>

<tr> <th><var>Equal sign </var></th>
<td>( = )</td> </tr>

<tr> <th><var>Left parenthesis </var></th>
<td>( ( )</td> </tr>

<tr> <th><var>Minus sign</var></th>
<td>( - )</td> </tr>

<tr> <th><var>Plus sign </var></th>
<td>( + )</td> </tr>

<tr> <th><var>Right parenthesis </var></th>
<td>( ) )</td> </tr>

<tr> <th><var>Semicolon</var></th>
<td>( ; )</td> </tr>

<tr> <th><var>Single quote </var></th>
<td>( ' ) </td> </tr>

<tr> <th><var>Slash </var></th>
<td>( / )</td> </tr>

<tr> <th><var>Space </var></th>
<td></td> </tr>
</table>
</td></tr>

<tr>
<th>filename</th>
<td>The name of a <var class="product">Model 204</var> file.

If you are specifying [[PQO|Parallel Query Option/204]] remote files, <var class="term">filename</var> must include a remote location (AT <var class="term">location</var>) or be a defined file synonym. Also, you cannot specify multiple identifiers for the same file: that is, you cannot include two synonyms for the same file, and you cannot include a synonym and a remote file specification for the same file. 
</td>
</tr>

<tr>
<th>location</th>
<td>For PQO files, <var class="term">location</var> is the symbolic name (as many as eight characters) that refers to the location of the node on which the remote file resides. An unquoted equal sign (<tt>=</tt>) specifies that the file is local.</td></tr>

<tr>
<th><var>OPTIONAL</var> or <var>MANDATORY</var></th>
<td>Indicates whether PQO scattered group operations can proceed in the absence of this group member. The default is <var>MANDATORY</var>. Valid abbreviations are <var>OPT</var> and <var>MAND</var>.

You cannot open a group if a mandatory member is unavailable. Also, you cannot specify <var>OPTIONAL</var> for local files.</td></tr>

<tr>
<th>parameter=value</th>
<td>Specifies <var class="product">Model 204</var> temporary group parameters. Multiple <var>PARAMETER</var> statements can follow, and each statement can contain as many parameters in any order as will fit on one input line. Valid temporary group parameters are described in [[#Temporary group parameters|Temporary group parameters]], below.</td></tr>
</table>

==Example==
CREATE GROUP REGION FROM DELAWARE, MARYLAND, VIRGINIA 
*** M204.0825: READING GROUP PARAMETERS
PARAMETER PROCFILE = VIRGINIA
END
*** M204.0828: TEMP GROUP CREATED: REGION


==Usage notes==
<ul>
<li>The <var>CREATE TEMP GROUP</var> command creates a temporary file group from the <var class="product">Model 204</var> files specified in the command. A temporary group is established by a user for use during the current login session. </li>

<li>A temporary group can be referenced only by the user who creates it.
The temporary group ceases to exist when the user logs out. </li>

<li>If you omit <code>TEMP</code> from the <var>CREATE GROUP</var> command, <var class="product">Model 204</var> assumes you are creating a temporary group.</li>
</ul>

===Temporary group parameters===
The [[#Example|CREATE GROUP REGION example]] above shows how group parameters can be specified. The <var class="product">Model 204</var> temporary group parameters that can be set in the <var>CREATE</var> command's parameter list are shown in the table below:
<table>
<tr class="head"> <th>Parameter</th>
<th>Defines...</th> </tr>

<tr> <th><var>UPDTFILE</var></th>
<td>Group's update file. </td> </tr>

<tr> <th><var>PROCFILE</var></th>
<td>Group's procedure file, or specifies that the group can contain multiple procedure files. </td> </tr>

<tr> <th><var>BLDGFT</var></th>
<td>Whether to build an internal field table for this group. Can be YES or NO; YES is the default. </td> </tr>
</table>

<ul>
<li>The <var>UPDTFILE</var> parameter defines the group's update file. When a SOUL <var>Store Record</var> statement is encountered and <var class="product">Model 204</var> cannot determine a file context, the record is stored in the group update file. If <var>UPDTFILE</var> is not specified, no update file is assigned and any attempt to issue a STORE RECORD statement will fail with:
M204.0203: "Store" requires update file
In that case, use the "IN FILE" or 'IN MEMBER" clause with STORE RECORD:
IN FILE filename STORE RECORD
IN GROUP groupname MEMBER %membername STORE RECORD


The [[$Update]] function also provides a convenient method for manipulating the update file. </li>

<li>The <var>PROCFILE</var> parameter defines the group's procedure file. All procedure-related commands and the <var>INCLUDE</var> statement operate on this file if no other file context is established. If this parameter is omitted, no procedure file is assigned.

You can also use <var>PROCFILE</var> to specify multiple procedure files for a group. If a group contains multiple procedure files, then the <var>INCLUDE</var> statement searches the entire group for the procedure to be included. The search proceeds in order from the first file defined in the <var>CREATE GROUP</var> command to the last. 

To allow for multiple procedure files, specify <code>PROCFILE = *</code>, which indicates that any of the files in a group can contain procedures. This specification is optional; use it only if more than one file in the group contains procedures that you want to include.

For more information, see [[Application Subsystem development#Multiple procedure files|multiple procedure files]]. </li>

<li>The <var>BLDGFT</var> parameter, if <code>YES</code> (the default), directs <var class="product">Model 204</var> to maintain certain information about the group in an internal field table. The option to specify depends upon how long you expect to use the group. If the group is only to satisfy a few short requests, specify <code>NO</code>.</li>
</ul>

==See also==
<ul>
<li>[[CREATE command: Permanent group]] </li>
</ul>

[[Category: User commands]]
[[Category:Commands]]

Table B (File architecture)

2024-11-15T03:25:28Z

JDamon: /* Structure of a Table B page */

This page describes the internal architecture of a Model 204 Table B page.

For a discussion of the ways a File Manager can organize these pages in a file, refer to [[File design]].

At a minimum, Table B contains all of the base records in a Model 204 file.
Up to Model 204 version 7.4, Table B has a maximum number of 16.7 million record numbers (IRNs for Internal Record Numbers).
As of Model 204 version 7.5, Table B has a maximum number of 48 million record numbers (if the <var>[[FILEORG parameter|FILEORG]]</var> X'200' bit is set). 
If [[Table X (File architecture)|Table X]] is not enabled, these "slots" are used for both base records and extension records. If [[Table E (File architecture)|Table E]] is not enabled, any data with contents greater than 255 bytes must be stored as a series of repeating fields.

==Structure of a Table B page==

:[[File:Table_B_structure.jpg|border|400 px]]

Not shown in the figure above is a 4-byte "Reuse Queue page number" for Unordered files. If it is present, it is in the lower right-hand corner (offset 6140), before working backwards to the first record on the page.

Each item in the figure is described below.

===Pointers===

====Free space pointer====

The free space pointer points to the last cell in the currently allocated pointer array, which in turn points to the beginning of free space on a page, where the next record can begin. (See the above diagram.)
On pages with no records yet stored, the free space pointer points to the last byte on the page (either the very end, of just before the Reuse Queue Page Number described above).

====Record pointer array====

There are ''as many as'' <var>[[BRECPPG parameter|BRECPPG]]</var> record pointers. These are not physically put onto the page until the record is being added to the file. ''As many as'' because, (except as noted below) it is possible that, as large records are stored, there will not be room for the full number of <var>BRECPPG</var> on the page, and so they would not be stored.

For Enhanced Data Handling (<var>FILEORG</var> X'100') files, with <var>[[RECRDOPT parameter|RECRDOPT]]</var> set to X'01', you will always have space for the full number of <var>BRECPPG</var> record pointers, as their length is included in the calculation of the <var>[[BRLIMSZ parameter|BRLIMSZ]]</var>. They still are not present on the page until the record is stored.

====Internal Record Number====

The record pointer is a useful identifier of a record, and is referred to as the "Internal Record Number" (IRN).

If, for example, <var>BRECPPG</var> is set to 10, the first Table B page contains, at most, records 0 to 9 (the first record in a Model 204 file is IRN 0). The second page contains IRNs 10 to 19, and so on.

Even if all the record slots are not used, they are treated as if they were. That is, in the example above, the second page in the file will still contain IRNs 10 to 19, even if only one record is physically present on the first page.

See <var>[[$CURREC]]</var> for a handy way to retrieve the IRN.

Note that the IRN is not a permanent record identifier. If the file is reorganized, it is highly likely that almost all records will have a different IRN afterward.

===Space management===

A Table B page grows from the top down (the pointers) and the bottom up (data area) simultaneously.

When adding records, there must be enough room to add all the preallocated fields on that page. Also, no new record will be added to the page if there are less than <var>[[BRESERVE parameter|BRESERVE]]</var> bytes available on the page. In each of these cases, the "next" page is used (see [[Adding records (File architecture)|adding records]]).

Similarly, when adding fields to existing records and the new field (or fieldgroup) does not fit on the current page, data is moved from the record into the extension record next in the chain, with, perhaps, a new extension being created at the end of the chain.

=== Further information about records ===

Refer to [[Record (File architecture)|Record]] and [[Adding records (File architecture)|Adding records]] for a full discussion of record architecture.

Refer also to [[Record design]] for the best use of Model 204 records.

===Table B segments===

====Definition====

As discussed below, [[Bitmaps (File architecture)|bitmaps]] are used in a number of ways in Model 204's processing. As bitmaps can contain bits covering 49152 records (usable space of 6144 * 8) records, this number of records is called a segment.

====Importance of and use====

Segments are used in indexing (as discussed below). In addition, when a procedure is compiled, the maximum number of Table B segments that the code needs to be able to handle is tracked (remember that sets of records are tracked with bitmaps). 

====INCREASE command boundaries====

When Model 204 code is compiled, one of the critical things noted is the number of segments in the file. This is necessary so that space can be reserved for found sets and other record tracking methodology.

Because of this, if you want to increase Table B, and other users or subsystems have the file open, you can only increase it to the next segment boundary (that is, the next multiple of 49152), and you must use the <var>DYNAMIC</var> option of the <var>[[INCREASE command|INCREASE]]</var> command. Otherwise, you can use the <var>INCREASE</var> command to extend Table B beyond the current segment boundary, but this requires exclusive access to the file.

For flexibility, consider using the <var>[[MAXINCBP parameter|MAXINCBP]]</var> parameter. This parameter (expressed as a percentage) is the additional number of segments reserved in compilation for growth. See the <var>MAXINCBP</var> explanation in [[Managing file and table sizes#MAXINCBP parameter|Managing file and table sizes]] for details.

====Use in indexing====

The segment concept is inherent to Model 204 indexing in a number of ways. Specifically:

<ul>
<li>See [[Table C (File architecture)#Segment entries |Table C segment entries]] for the effect of segments in the hash index.

<li>See [[Table D (File architecture)#B-tree index structure|B-tree index structure]] for the effect of segments in the ordered index.

<li>See [[Table D (File architecture)#Bitmaps used in indexing|Bitmaps used in indexing]] for how segments relate to the detailed level of both types of indexes.
</ul>

===Reuse queue===

For Reuse Record Number (RRN) files (<var>FILEORG</var> X'04' bit set), pages with sufficient space (see the <var>[[BREUSE parameter]]</var>) and one or more available record slots are kept in a reuse queue.

This may happen due to records (or large numbers of fields) being deleted.

These use the 4-byte reuse queue page number to track the pages's availability.

RRN files add records to the pages from the queue before adding records to <var>[[BHIGHPG parameter|BHIGHPG]]</var>.

==Parameters related to the use of Table B==

This table excludes the parameters used for [[Hash key files|Hash Key]] and [[Sorted files]]. See those topics for a full discussion of their special parameters (and distinction in meanings for some of the parameters below).

Also not shown are the parameters that control the [[Managing file and table sizes#Automatic increases|automatic increase]] in table size.

<table class="thJustBold" style="Width:80%">
<tr><th>[[BHIGHPG parameter|BHIGHPG]]</th>
<td>Table B highest active page. Normally the high water mark of pages used (except for Hash Key and Sorted files). Viewable only. </td></tr>

<tr><th>[[BQLEN parameter|BQLEN]]</th>
<td>The number of pages in the reuse queue. Viewable only. </td></tr>

<tr><th>[[BRECPPG parameter|BRECPPG]]</th>
<td>The maximum number of record slots on a Table B page. </td></tr>

<tr><th>[[BRESERVE parameter|BRESERVE]]</th>
<td>Table B Reserved space. </td></tr>

<tr><th>[[BREUSE parameter|BREUSE]]</th>
<td>The minimum percentage of free space necessary to add a page to the reuse queue, over and above BRESERVE. </td></tr>

<tr><th>[[BREUSED parameter|BREUSED]]</th>
<td>The numberof record slots reused. </td></tr>

<tr><th>[[BRLIMSZ parameter|BRLIMSZ]]</th>
<td>Base record size maximum. Viewable only. </td></tr>

<tr><th>[[BSIZE parameter|BSIZE]]</th>
<td>The number of pages in Table B. </td></tr>

<tr><th nowrap>[[RECRDOPT parameter|RECRDOPT]]</th>
<td>Record storage options. </td></tr>
</table>

[[Category:File architecture]]

Table B (File architecture)

2024-11-07T20:24:22Z

JDamon: /* Structure of a Table B page */

This page describes the internal architecture of a Model 204 Table B page.

For a discussion of the ways a File Manager can organize these pages in a file, refer to [[File design]].

At a minimum, Table B contains all of the base records in a Model 204 file.
Up to Model 204 version 7.4, Table B has a maximum number of 16.7 million record numbers (IRNs for Internal Record Numbers).
As of Model 204 version 7.5, Table B has a maximum number of 48 million record numbers (if the <var>[[FILEORG parameter|FILEORG]]</var> X'200' bit is set). 
If [[Table X (File architecture)|Table X]] is not enabled, these "slots" are used for both base records and extension records. If [[Table E (File architecture)|Table E]] is not enabled, any data with contents greater than 255 bytes must be stored as a series of repeating fields.

==Structure of a Table B page==

:[[File:Table_B_structure.jpg|border|400 px]]

Not shown in the figure above is a 4-byte "Reuse Queue page number" for Unordered files. If it is present, it is in the lower right-hand corner, before working backwards to the first record on the page.

Each item in the figure is described below.

===Pointers===

====Free space pointer====

The free space pointer points to the last cell in the currently allocated pointer array, which in turn points to the beginning of free space on a page, where the next record can begin. (See the above diagram.)
On pages with no records yet stored, the free space pointer points to the last byte on the page (either the very end, of just before the Reuse Queue Page Number described above).

====Record pointer array====

There are ''as many as'' <var>[[BRECPPG parameter|BRECPPG]]</var> record pointers. These are not physically put onto the page until the record is being added to the file. ''As many as'' because, (except as noted below) it is possible that, as large records are stored, there will not be room for the full number of <var>BRECPPG</var> on the page, and so they would not be stored.

For Enhanced Data Handling (<var>FILEORG</var> X'100') files, with <var>[[RECRDOPT parameter|RECRDOPT]]</var> set to X'01', you will always have space for the full number of <var>BRECPPG</var> record pointers, as their length is included in the calculation of the <var>[[BRLIMSZ parameter|BRLIMSZ]]</var>. They still are not present on the page until the record is stored.

====Internal Record Number====

The record pointer is a useful identifier of a record, and is referred to as the "Internal Record Number" (IRN).

If, for example, <var>BRECPPG</var> is set to 10, the first Table B page contains, at most, records 0 to 9 (the first record in a Model 204 file is IRN 0). The second page contains IRNs 10 to 19, and so on.

Even if all the record slots are not used, they are treated as if they were. That is, in the example above, the second page in the file will still contain IRNs 10 to 19, even if only one record is physically present on the first page.

See <var>[[$CURREC]]</var> for a handy way to retrieve the IRN.

Note that the IRN is not a permanent record identifier. If the file is reorganized, it is highly likely that almost all records will have a different IRN afterward.

===Space management===

A Table B page grows from the top down (the pointers) and the bottom up (data area) simultaneously.

When adding records, there must be enough room to add all the preallocated fields on that page. Also, no new record will be added to the page if there are less than <var>[[BRESERVE parameter|BRESERVE]]</var> bytes available on the page. In each of these cases, the "next" page is used (see [[Adding records (File architecture)|adding records]]).

Similarly, when adding fields to existing records and the new field (or fieldgroup) does not fit on the current page, data is moved from the record into the extension record next in the chain, with, perhaps, a new extension being created at the end of the chain.

=== Further information about records ===

Refer to [[Record (File architecture)|Record]] and [[Adding records (File architecture)|Adding records]] for a full discussion of record architecture.

Refer also to [[Record design]] for the best use of Model 204 records.

===Table B segments===

====Definition====

As discussed below, [[Bitmaps (File architecture)|bitmaps]] are used in a number of ways in Model 204's processing. As bitmaps can contain bits covering 49152 records (usable space of 6144 * 8) records, this number of records is called a segment.

====Importance of and use====

Segments are used in indexing (as discussed below). In addition, when a procedure is compiled, the maximum number of Table B segments that the code needs to be able to handle is tracked (remember that sets of records are tracked with bitmaps). 

====INCREASE command boundaries====

When Model 204 code is compiled, one of the critical things noted is the number of segments in the file. This is necessary so that space can be reserved for found sets and other record tracking methodology.

Because of this, if you want to increase Table B, and other users or subsystems have the file open, you can only increase it to the next segment boundary (that is, the next multiple of 49152), and you must use the <var>DYNAMIC</var> option of the <var>[[INCREASE command|INCREASE]]</var> command. Otherwise, you can use the <var>INCREASE</var> command to extend Table B beyond the current segment boundary, but this requires exclusive access to the file.

For flexibility, consider using the <var>[[MAXINCBP parameter|MAXINCBP]]</var> parameter. This parameter (expressed as a percentage) is the additional number of segments reserved in compilation for growth. See the <var>MAXINCBP</var> explanation in [[Managing file and table sizes#MAXINCBP parameter|Managing file and table sizes]] for details.

====Use in indexing====

The segment concept is inherent to Model 204 indexing in a number of ways. Specifically:

<ul>
<li>See [[Table C (File architecture)#Segment entries |Table C segment entries]] for the effect of segments in the hash index.

<li>See [[Table D (File architecture)#B-tree index structure|B-tree index structure]] for the effect of segments in the ordered index.

<li>See [[Table D (File architecture)#Bitmaps used in indexing|Bitmaps used in indexing]] for how segments relate to the detailed level of both types of indexes.
</ul>

===Reuse queue===

For Reuse Record Number (RRN) files (<var>FILEORG</var> X'04' bit set), pages with sufficient space (see the <var>[[BREUSE parameter]]</var>) and one or more available record slots are kept in a reuse queue.

This may happen due to records (or large numbers of fields) being deleted.

These use the 4-byte reuse queue page number to track the pages's availability.

RRN files add records to the pages from the queue before adding records to <var>[[BHIGHPG parameter|BHIGHPG]]</var>.

==Parameters related to the use of Table B==

This table excludes the parameters used for [[Hash key files|Hash Key]] and [[Sorted files]]. See those topics for a full discussion of their special parameters (and distinction in meanings for some of the parameters below).

Also not shown are the parameters that control the [[Managing file and table sizes#Automatic increases|automatic increase]] in table size.

<table class="thJustBold" style="Width:80%">
<tr><th>[[BHIGHPG parameter|BHIGHPG]]</th>
<td>Table B highest active page. Normally the high water mark of pages used (except for Hash Key and Sorted files). Viewable only. </td></tr>

<tr><th>[[BQLEN parameter|BQLEN]]</th>
<td>The number of pages in the reuse queue. Viewable only. </td></tr>

<tr><th>[[BRECPPG parameter|BRECPPG]]</th>
<td>The maximum number of record slots on a Table B page. </td></tr>

<tr><th>[[BRESERVE parameter|BRESERVE]]</th>
<td>Table B Reserved space. </td></tr>

<tr><th>[[BREUSE parameter|BREUSE]]</th>
<td>The minimum percentage of free space necessary to add a page to the reuse queue, over and above BRESERVE. </td></tr>

<tr><th>[[BREUSED parameter|BREUSED]]</th>
<td>The numberof record slots reused. </td></tr>

<tr><th>[[BRLIMSZ parameter|BRLIMSZ]]</th>
<td>Base record size maximum. Viewable only. </td></tr>

<tr><th>[[BSIZE parameter|BSIZE]]</th>
<td>The number of pages in Table B. </td></tr>

<tr><th nowrap>[[RECRDOPT parameter|RECRDOPT]]</th>
<td>Record storage options. </td></tr>
</table>

[[Category:File architecture]]

Tracking system activity (CCAJRNL, CCAAUDIT, CCAJLOG)

2024-10-02T17:08:56Z

JDamon: /* AUDIT204 Return Codes */

<div class="toclimit-3">
==Overview of the journal data sets==

This topic discusses the journal data sets you can create and use in <var class="product">Model 204</var>, how to manage them, and the utilities you can use to report on and analyze the <var class="product">Model 204</var> information collected. The system manager can set up the following journal data sets, which are not part of <var class="product">Model 204</var> installation.

The data sets are CCAJRNL, CCAAUDIT, and CCAJLOG. You set each up as:
<ul>
<li>A ddname in z/OS</li>

<li>A FILEDEF in z/VM</li>

<li>A DLBL in z/VSE</li>
</ul>

===CCAJRNL===

The complete repository of <var class="product">Model 204</var> system activity and data that would be used in recovery is CCAJRNL. The CCAJRNL file collects all update information used to reconstruct the database during recovery and all other activity history, such as messages and statistics, in an unformatted, therefore unreadable, binary format.

===CCAAUDIT and CCAJLOG===

You can also create a CCAAUDIT and/or a CCAJLOG file to track information. CCAAUDIT and CCAJLOG are comprised of the same <var class="product">Model 204</var> audit trail data, however, differently. The activity history or audit trail is comprised of:
<ul>
<li>Important characteristics of a run</li>

<li>All error messages encountered during a run</li>

<li>All communications with the operator's console</li>

<li>Input lines from Online terminals</li>

<li>HLI calls</li>

<li>Utilization statistics</li>

<li>Information specifically directed to the journal/audit trail by users </li>
</ul>

====Watching your system in action: CCAAUDIT====

The CCAAUDIT file, also known as the audit trail, logs information about a <var class="product">Model 204</var> run and prints the information in readable format for the terminal screen while processes are running or to paper.

====Improving recovery performance: CCAJLOG====

The CCAJLOG file off loads the audit trail information into itself, so that the CCAJRNL contains only the information required for RESTART recovery. Recovery performance is improved, because the audit trail information does not have to be read and rejected for recovery.

===Version-specific journals===

Journals created by <var class="product">Model 204</var> prior to V7R1.0 cannot by processed in V7R1.0. The reverse is also true: journals created in V7R1.0 cannot be processed by an earlier version of <var class="product">Model 204</var>.

==Using Model 204 journal files==

<var class="product">Model 204</var> system managers and file managers use the journal files in some of the following ways:
<table>
<tr class="head">
<th>Task </th>
<th>Journal used </th>
<th>Utility/command used</th>
</tr>

<tr>
<td>Generate an audit trail that can be viewed during processing </td>
<td>CCAAUDIT</td>
<td> </td>
</tr>

<tr>
<td>Generate an audit trail for printing out later </td>
<td nowrap>CCAJRNL, CCAJLOG </td>
<td>Audit204 utility</td>
</tr>

<tr>
<td>Regenerate a file to complete media recovery</td>
<td>CCAJRNL (ddname CCAGEN) </td>
<td>REGENERATE command</td>
</tr>

<tr>
<td>Recover <var class="product">Model 204</var> following a system failure </td>
<td>CCAJRNL (ddname CCARF) </td>
<td>RESTART command</td>
</tr>

<tr>
<td>Extract a report </td>
<td>CCAJRNL</td>
<td>UTILJ utility</td>
</tr>

<tr>
<td>Performance tuning by analyzing statistics </td>
<td>CCAJRNL</td>
<td>Audit204 utility or site written analysis program</td>
</tr>
</table>

The <var class="product">Model 204</var> system manager is expected to create the CCAJRNL file at their site for recovery purposes. The <var class="product">Model 204</var> file manager may be responsible for using the CCAJRNL file to regenerate data files.

==Creating and generating CCAJRNL==

A journal is generated if: 
<ul>
<li>The <var>SYSOPT</var> parameter includes the 128 specification.

You must set <var>BLKSIZE</var> for CCAJRNL to not less than 6749 on up to 32K. Buffers are written to CCAJRNL either when a transaction is committed or when the buffer fills. Frequent commits may result in many short blocks/buffers being written to CCAJRNL.
</li>

<li>A CCAJRNL is defined with BLKSIZE set to the minimum, 6749, for:
<ul>
<li>z/OS, a DD statement</li>

<li>z/VM, a FILEDEF</li>
</ul></li>
</ul>

Statistics generated in an audit trail line are presented in [[Using system statistics#User statistics entries (Type 9)|User statistics entries (Type 9)]]. 

The use of CCAJRNL in recovery procedures is explained in [[System and media recovery#Recovery data sets and job control|Recovery data sets and job control]]. 

How to use CCAJRNL to regenerate a data set is discussed
in [[Media recovery]].

CCAJRNL may take multiple extents and may span multiple volumes, since it is read forward-only. Its size cannot be limited in a way similar to the CHKPOINT data set (see [[Checkpoints: Storing before-images of changed pages#Limiting the size of CHKPOINT|Limiting the size of CHKPOINT]]), because CCAJRNL records all update activity in an Online, which may be required in a subsequent REGENERATE or RESTART process.

===CCAJRNL as single data set or stream===

You can define CCAJRNL as a single data set or as a stream. Using a <var>[[DEFINE STREAM command|DEFINE STREAM]]</var> command, you incorporate multiple journal data sets. 
<ul>
<li>For parallel and ring structures, see [[Configuring checkpoint and journal data streams#Example 1: Ring/parallel journal stream|Example 1: Ring/parallel journal stream]].</li>

<li>For GDG structure, see [[Configuring checkpoint and journal data streams#Perpetual journaling for z/OS|Perpetual journaling for z/OS]]. </li>
</ul>

==SWITCH STREAM command==

The <var>[[SWITCH STREAM command|SWITCH STREAM]]</var> command switches a stream to the next member of a parallel, ring, concatenated, or Generation Data Group (GDG) stream. You can issue the <var>SWITCH STREAM</var> command for the following streams: CCAJLOG, CCAJRNL, CHKPOINT, or CHKPNTS. 

===Using the SWITCH STREAM command===

When the <var>SWITCH STREAM</var> command is issued, the following messages are produced:
M204.2712: STREAM streamname IS BEING SWITCHED
M204.2712: STREAM streamname SWITCHED VIA COMMAND

<ul>
<li>When switching a journal stream, CCAJRNL or CCAJLOG, the currently active data set in that stream is closed. The next data set defined to the stream is opened when the next write to that stream is required. </li>

<li>When switching a checkpoint stream, CHKPOINT or CHKPNTS, the currently active data set in that stream is closed after the next record is written to that data set.</li>
</ul>

If not in an extended quiesce, Rocket Software recommends that you follow a <code>SWITCH STREAM CCAJRNL</code> command with a <var>CHECKPOINT</var> command to ensure that you have a checkpoint in the current journal. 

The <var>SWITCH STREAM command</var> is sometimes useful for CCAJLOG and rarely required for CHKPOINT or CHKPNTS.

===Journal block header information for SWITCH STREAM===

Some journal analysis utilities require additional journal information at sites that embrace GDG streams and the <var>SWITCH STREAM</var> command as a means to keep their Onlines up for long periods. <var class="product">Model 204</var> includes this additional information in the header for each journal block. 

To ensure that the required information is present in the first block of each journal data set created by the <var>SWITCH STREAM</var> command, the header has been expanded. This expansion makes the journal up to 4% larger than in previous releases.
Note: Due to these changes in journal record layouts, CCAJRNL and CHKPOINT/CHKPNT data sets are not compatible with previous releases of <var class="product">Model 204</var>.

For the complete description of the header entry formats in the journal block, see [[Using system statistics#Header entries (Type 0)|Header entries (Type 0)]].

In pre-7.4.0 versions of Rocket <var class="product">Model 204</var>, each Online environment might produce a single merged journal daily. If an Online was bounced during the day, then the various journals for the day were merged into a single daily journal. Usually the daily merged journal contained records from only one run. The single merged journal could be used to automate media recovery, rather than manually assemble the recovery job journal concatenation.

Using the <var>SWITCH STREAM</var> command, a site can still prepare a daily merged journal. However, when the <var>SWITCH STREAM</var> command is used, each journal merged does not begin with the initialization of the Online. This means that no Type 12 records or M204.0061 initialization messages are included. Although <var class="product">Model 204</var> recovery, including media recovery, can successfully process these merged journals, various journal analysis utilities cannot.

===Using a SWITCH STREAM CCAJRNL command during extended quiesce===

In pre-7.1.0 releases, if you used the checkpoint quiesce feature, a switch to the next journal member at checkpoint quiesce could occur only when CCAJRNL was defined as a ring stream.

However, a switch at checkpoint quiesce may be desirable for all stream configurations of CCAJRNL: ring, parallel, concatenated, and GDG. The switch marks the point where the CCAJRNL data collected thus far is not needed in subsequent <var>REGENERATE</var> processing against files backed up during the quiesce. If file backups or dumps are taken during the checkpoint quiesce, only CCAJRNL data collected after checkpoint quiesce is useful for <var>REGENERATE</var> processing against those files.

A checkpoint is automatically taken if you issue a <code>SWITCH STREAM CCAJRNL</code> command while you are in extended quiesce, as shown in the following table:
<table>
<caption>SWITCH command within extended quiesce</caption>

<tr class="head">
<td>Step </td>
<td>Command issued </td>
<td>Purpose</td>
</tr>

<tr>
<td align="right">1 </td>
<td>CHECKPOINT SET EXTENDED QUIESCE </td>
<td>Enables extended quiesce</td>
</tr>

<tr>
<td align="right">2 </td>
<td>CHECKPOINT or automated checkpoint</td>
<td>

The next checkpoint, automated or command initiated, begins the extended quiesce

When the checkpoint is successful, the extended quiesce is entered. While in extended quiesce, you cannot issue a <var>CHECKPOINT</var> command. However, you can issue a <var>SWITCH STREAM</var> command, such as the following:
</td>
</tr>

<tr>
<td align="right">3</td>
<td>SWITCH STREAM CCAJRNL </td>
<td>When the checkpoint is successful, extended quiesce processing can begin for backups, SnapShots, or any activity that does not involve updating.</td>
</tr>

<tr>
<td align="right">4</td>
<td nowrap>CHECKPOINT END EXTENDED QUIESCE</td>
<td>Concludes extended quiesce. Should recovery be required due to a failure during extended quiesce, journals created prior to the <var>SWITCH STREAM</var> command will not be required, as the last checkpoint resides in the current CCAJRNL member.</td>
</tr>
</table>

This automated checkpoint functionality of <var>SWITCH STREAM CCAJRNL</var> applies only during checkpoint quiesce. The automated checkpoint functionality is not supported for CCAJLOG, CHKPOINT, or CHKPNTS.

===SWITCH STREAM limitations===

In order for a stream to be switched, there must be a target data set to switch to. If there is no target data set, the following message is issued:
M204.2712: MEMBER membername IS INELIGIBLE FOR SWITCHING


Consider the following example:
DEFINE STREAM CCAJRNL WITH SCOPE=SYSTEM PARALLEL=(JRNL1,JRNL2) MINAVAIL=2
DEFINE DATASET JRNL1 WITH SCOPE=SYSTEM DSN=CCAJRNL.JRNL1 OLD
DEFINE STREAM JRNL2 WITH SCOPE=SYSTEM GDG=J2 CONTROL=J2CTL
DEFINE DATASET J2 WITH SCOPE=SYSTME DSN=CCAJRNL.GDGBASE.JRNL2 CATALOG -
GEN=+1 CYL PRI 500
DEFINE DATASET J2CTL WITH SCOPE=SYSTEM DSN=CCAJRNL.GDGBASE.JRNL2.CTL OLD


Since data set <code>JRNL1</code> has no target data set for a switch, when the <code>JRNL1</code> data set is marked full, the number of available parallel stream members (<var>MINAVAIL</var>) drops to one, since only <code>JRNL2</code> now has space available. Since the number of available members is now less than <var>MINAVAIL</var>, the Online would stop with a "CCAJRNL full" message.

If before <code>JRNL1</code> fills, a <code>SWITCH STREAM CCAJRNL</code> command were issued, the following messages would be produced:
M204.2712: MEMBER JRNL1 IS INELIGIBLE FOR SWITCHING
M204.2712: STREAM JRNL2 IS BEING SWITCHED
M204.2712: STREAM CCAJRNL - NOT ALL MEMBERS SWITCHED


Member <code>JRNL1</code> was not switched. However, if <code>JRNL1</code> has not filled, the parallel stream will remain open because the number of available members (<var>MINAVAIL</var>) is still 2. Stream <code>JRNL2</code> always has a target data set to switch to since it is a GDG. Nevertheless, whenever <code>JRNL1</code> fills, the minimum available members will be less than <var>MINAVAIL</var>, the stream will be closed, and the run will terminate.

Because stream members are not locked before switch processing, and because all members are not switched at exactly the same time, the number of records in individual data sets of a parallel stream may not be identical. This is of no consequence to recovery or <var>REGENERATE</var>, but should be noted. However, the total number of records in each member is identical. 

Previously, you had to concatenate all journals into one data set or specify a concatenated <code>CCAGEN DD</code> statement.

===SWITCH STREAM command for concatenated streams===

The same limitation exists for the last member in a concatenated stream. Since there is no additional member to switch to, the following message is issued:
M204.2712: STREAM streamname IS INELIGIBLE FOR SWITCHING


If all members of a stream are switched, the following message is issued:
M204.2712: STREAM CCAJRNL SWITCHED VIA COMMAND


===Handling streams without records===

You cannot switch a stream member that contains no records. So in the previous case, if the first G1 stream member has just become full and the newly opened (second) GDG member contains zero records, then a <code>SWITCH STREAM CCAJRNL</code> command is not processed.

Since <code>J1</code> is ineligible, and <code>G1</code> (second member) is empty, no switch occurs. The messages issued are:
M204.2712: MEMBER J1 IS INELIGIBLE FOR SWITCHING
M204.2712: MEMBER G1 IS EMPTY AND CANNOT BE SWITCHED
M204.2712: SWITCH WAS UNSUCCESSFUL


===Recovery parameters===

Use the following recovery parameters when generating a journal:
<table>
<tr class="head">
<th>Parameter </th>
<th>Set </th>
<th>Specifies...</th>
<th>Comments</th>
</tr>

<tr>
<td>FRCVOPT </td>
<td>During file creation or with the <var>RESET</var> command </td>
<td>File recovery options</td>
<td>If the file is included in system or media recovery, do not use <code>FRCVOPT=X'04'</code>, which suppresses roll forward logging. </td>
</tr>

<tr>
<td>RCVOPT </td>
<td>On the JCL EXEC parameter or on User 0's parameter line </td>
<td>Type of information written to the journal</td>
<td>

X'08' writes the roll forward information that is required for system and media recovery to CCAJRNL.

X'09' also causes preimages to be written to the CHKPOINT data set for roll back recovery. Use this setting if you want to enable full recovery.
</td>
</tr>
</table>

===Writing error messages to the journal data set===

You can control which error messages or classes of error messages to store in CCAJRNL, CCAAUDIT, or CCAJLOG using <var>[[MSGCTL command|MSGCTL]]</var> command parameters.

===ERRMSGL: Setting the length of saved error messages===

The <var>[[ERRMSGL parameter|ERRMSGL]]</var> parameter provides the ability to set the number of bytes to use for saved error messages — messages returned by <var>[[$Errmsg]]</var> and <var>[[$Fsterr]]</var>. You can set <var>ERRMSGL</var> to any value from 80 to 256 — that length includes a count byte. The value is rounded up to an 8-byte multiple. For example, if you set <code>ERRMSGL=99</code>, it will be rounded to 104, that value is reduced by 1 for the count byte, thus allowing up to 103 characters of an error message to be saved.


====Server size requirements for saved error messages====

Increasing <var>ERRMSGL</var> increases the requirement of the fixed table size of a server. This may necessitate an increase in you <var>SERVSIZE</var> settings. The size requirement for <var>ERRMSGL</var> is:
3 * (ERRMSGL - 80)


For example, increasing <var>ERRMSGL</var> to its maximum of 256 would increase the fixed server requirement by <code>(3 * (256-80) -1)</code>, or 527 bytes. 

For a full update to the <var>SERVSIZE</var> formula, see [[Defining the runtime environment (CCAIN)#Calculating fixed table size|Calculating fixed table size]].

==Using the CCAJRNL data set==

During a production Online run, roll forward recovery information is written to the CCAJRNL data set. Additionally, a substantial amount of unformatted audit trail data is also written. When recovery is required and after roll back recovery has completed, that data set (during recovery its ddname is CCARF) is read and the roll forward information is extracted and used to reapply all committed updates up to the time of the system failure.

CCAJRNL collecting all roll forward and audit information
[[File:SM13ccaprint1_sep05.gif|468px]] 

==Performance efficiencies using CCAJRNL==

===Choosing whether to define CCAAUDIT===

<var class="product">Model 204</var> operates more efficiently using CCAJRNL without CCAAUDIT, because it is not also generating a separate audit trail. If you need printed information and your site does not maintain CCAAUDIT, you can extract the audit trail from CCAJRNL in a separate step using AUDIT204. 

If you need printed run information immediately upon completion of the job and you also need Roll Forward or Accounting facilities, create both the journal (CCAJRNL) and the audit trail (CCAAUDIT). 

You can use CCAJRNL in place of CCAAUDIT when you do not need audit trail data immediately following run termination.

===Allocating multiple journal buffers===

Setting <var>NJBUFF</var> to a value (<code>NSERVS + NSUBTKS + 1</code>) allocates multiple journal buffers and ensures that a free buffer is always available for the journal. In z/VM, the <var>NJBUFF</var> parameter is stacked in the EXEC that issues all the FILEDEFs.

===Using the CCAJLOG data set===

If you allocate CCAJLOG, the unformatted audit trail data is written to it and only roll forward recovery data is written to CCAJRNL. Reducing the number of records written to CCAJRNL improves recovery performance and also reduces the likelihood of filling CCAJRNL, which would result in run termination.
<ul>
<li>The number of buffers allocated for CCAJLOG is determined by the parameter, <var>[[NLBUFF parameter|NLBUFF]]</var>, which defaults to five. Only full blocks/buffers are written to CCAJLOG.</li>

<li>The size of these buffers is determined by the <var>BLKSIZE</var> parameter defined for the CCAJLOG data set which may be as large as 32K.</li>
</ul>

You can produce a formatted CCAAUDIT report from CCAJLOG using the AUDIT204 utility. In this case, the CCAJLOG is referenced via the ddname CCAJRNL. 

CCAJRNL collecting roll forward data; CCAJLOG collecting audit trail data
[[File:SM13ccaprint2_sep05.gif|466px]] 

====Defining the CCAJLOG stream====

You can define a CCAJLOG using any of the stream definitions: concatenate, parallel, ring, or GDG; see [[DEFINE STREAM command]].

===M204JLOG assembler exit===

The assembler exit, M204JLOG, can be invoked if linked in. This exit is initiated when a <var>SWITCH</var> command is issued against a CCAJLOG GDG stream. The exit may be any AMODE and need not be reentrant.

====Coding considerations====

On entry, the registers contain:

:R4 = A(GDG LIOD)
:R9 = A(new switch control record) (see CRD dsect)
:R13 = A(OSW save area)
:R14 = return address
:R15 = base address

<var class="product">Model 204</var> expects no output from the exit. All registers must be restored before return. If any <var class="product">Model 204</var> data structures are modified by the exit, unpredictable results may occur.
<blockquote class="note">
Note: If the user exit abends, <var class="product">Model 204</var> issues an error and produces a snap. This leaves <var class="product">Model 204</var> waiting for the switch to complete. At that point the switch will never complete, no further Online activity is possible, and the Online must be cancelled.

In addition, while the M204JLOG user exit is running, <var class="product">Model 204</var> cannot continue normal processing until a return from the exit is accomplished. For this reason, WAITs and I/Os inside the exit are strongly discouraged.
</blockquote>

====Sample M204JLOG Assembler exit====
M204JLOG CSECT
M204JLOG AMODE 31
M204JLOG TITLE 'TEST THE MODEL 204 CCAJLOG USER EXIT'
X10 EQU 10
X11 EQU 11
X12 EQU 12
X13 EQU 13
X14 EQU 14
X15 EQU 15
STM X14,X12,12(X13) SAVE CALLERS REGISTERS
LR X12,X15 ESTABLISH BASE REGISTER
USING M204JLOG,X12
LA X10,SAVEAREA GET A(LOCAL REGISTER SAVEAREA)
ST X10,8(,X13) CHAIN OUR SAVEAREA TO CALLERS
ST X13,SAVEAREA+4 CHAIN CALLERS SAVEAREA TO OURS
LA X13,SAVEAREA SET A(OUR SAVEAREA)
WTO 'M204JLOG EXIT INVOKED, DOING SOMETHING'
* ******************************************************************* *
* * CUSTOMERS MAY PLACE CODE HERE TO DO WHATEVER THEY DESIRE. * *
* ******************************************************************* *
WTO 'M204JLOG EXIT ENDING'
L X13,4(,X13) RESTORE CALLERS SAVEAREA ADDRESS
ST X10,16(X13) SET RETURN CODE (R15)
LM X14,X12,12(X13) RESTORE CALLERS REGISTERS
BR X14 RETURN TO CALLER
DS 0D
SAVEAREA DS 18F REGISTER SAVE AREA
LTORG
END


===Model 204 roll forward recovery with CCAJLOG===

<var class="product">Model 204</var> operates more efficiently during roll forward recovery, if you have defined CCAJLOG. This is because CCAJRNL now contains only roll forward recovery data; CCAJLOG contains unformatted CCAAUDIT data, which does not have to be read and ignored during the roll forward recovery since it has been removed from CCAJRNL.

===Separating transaction (CCAJRNL) and auditing (CCAJLOG) information===

Splitting audit trail records — messages and statistics — out from CCAJRNL and writing them to CCAJLOG improves recovery performance by reducing the size of CCAJRNL. This also reduces the likelihood of filling CCAJRNL. However, it does shift the possibility to CCAJLOG and if either CCAJRNL or CCAJLOG fills, the run comes down.

===Regenerating files using CCAJRNL and CCAJLOG===

Sending audit trail data to CCAJLOG also speeds up the <var>REGENERATE</var> processing, if that is required.

===Considerations for CCAJLOG===

By specifying CCAJLOG in the JCL or dynamically at the start of CCAIN, all messages and statistics are written to CCAJLOG. All recovery-type records are written to CCAJRNL. 
<ul>
<li>If you do not specify CCAJLOG, a CCAJRNL is maintained that collects recovery records, messages, and statistics. </li>

<li>If CCAJLOG is specified but the open fails, the run terminates initialization.</li>

<li>If CCAJLOG fills during a run, the run is terminated.</li>
</ul>

Set the <var>[[NLBUFF parameter|NLBUFF]]</var> parameter to specify the number of buffers to use for CCAJLOG. If you do not specify a value for <var>NLBUFF</var>, a default value of five is allocated. 

===Using the journals correctly===

If you create both a CCAJRNL file and a CCAJLOG file, you must use the CCAJLOG file as input to AUDIT204. And, you must continue to use the CCAJRNL file as input to <var>REGEN</var> and <var>RESTART</var> commands; otherwise, <var class="product">Model 204</var> issues one of the following messages:
M204:2515: CCAJRNL DATASET IS INVALID FOR AUDIT 204
M204:2515: CCAJLOG DATASET IS INVALID FOR {REGEN | RESTART}


If you create both a CCAJLOG and CCAJRNL and you use the CCAJRNL as input to AUDIT204, AUDIT204 issues the following message and stops processing:
NON-MESSAGE DATASET IS INVALID FOR CCAJRNL


Although UTILJ can handle a CCAJLOG data set, the utility will, of course, find only message and statistics type records in CCAJLOG. So, if you ask for recovery journal entries, type 1-6, the output is empty, since they do not exist on the CCAJLOG.

Because audit trail information is stored in CCAJLOG, if you have written a custom application for statistics reports, use CCAJLOG for input.

==CCAJRNL data set record layout==

The journal data set is composed of variable length records. Each record consists of a header, one or more journal entries, and a trailer. The format of the journal data set is subject to change with each release of <var class="product">Model 204</var>. 

===Journal entry format===

Journal entries contain audit trail, statistical, and control information, or information used for recovery. Statistics are recorded in the journal as fullword hexadecimal counters. Space is allocated in a given journal statistics entry for all possible statistics, even if they are not being kept. The values for statistics that are not maintained, or do not have relevance to the current configuration of <var class="product">Model 204</var>, are represented as hexadecimal zeros.

Each entry has the same general format: 
<table>
<tr class="head">
<th>Bytes</th>
<th>Contents</th>
</tr>

<tr>
<td align="right"> 0-1</td>
<td>Length</td>
</tr>

<tr>
<td align="right"> 2</td>
<td>Entry type</td>
</tr>

<tr>
<td> 3-n</td>
<td>Data</td>
</tr>
</table>

Offset 0 is a 2-byte hexadecimal field containing the length of the entry. (The only exception to this rule is the header entry, where the length is the length of the entire journal block.)

Offset 2 is a 1-byte field, which identifies the type of the entry: file, system, or user.

Offset 3 is a variable-length data portion. The size and layout depends upon the type of entry.

The following table summarizes the journal entry types, including formatting layouts and statistical information. Use the layout and statistics tables in [[Using system statistics]] for developing customized software to extract particular information from the journal data set. 
<table>
<caption>Summary of journal entry types</caption>
<tr class="head">
<th>Type</th>
<th>Journal record</th>
</tr>

<tr>
<td align="right"> X'00' </td>
<td>Header/Trailer</td>
</tr>

<tr>
<td align="right"> X'01' </td>
<td>Recovery entry</td>
</tr>

<tr>
<td align="right"> X'02' </td>
<td>Recovery entry</td>
</tr>

<tr>
<td align="right"> X'03' </td>
<td>Recovery entry</td>
</tr>

<tr>
<td align="right"> X'04' </td>
<td>Recovery entry</td>
</tr>

<tr>
<td align="right"> X'05' </td>
<td>Recovery entry</td>
</tr>

<tr>
<td align="right"> X'06' </td>
<td>Recovery entry</td>
</tr>

<tr>
<td align="right"> X'07' </td>
<td>Unused</td>
</tr>

<tr>
<td align="right"> X'08' </td>
<td>System statistics</td>
</tr>

<tr>
<td align="right"> X'09' </td>
<td>User statistics</td>
</tr>

<tr>
<td align="right"> X'0A' </td>
<td>File statistics</td>
</tr>

<tr>
<td align="right"> X'0B' </td>
<td>Discontinued audit trail text</td>
</tr>

<tr>
<td align="right"> X'0C' </td>
<td>Initialization entry</td>
</tr>

<tr>
<td align="right"> X'0D' </td>
<td>Possibly continued audit trail text</td>
</tr>

<tr>
<td align="right"> X'0E' </td>
<td>Timestamp</td>
</tr>

<tr>
<td align="right"> X'0F' </td>
<td>Merged journal brackets</td>
</tr>
</table>

===Number of lines in the journal data set===

The number of lines in the journal are controlled by the <var>CAUDIT</var>, <var>LAUDIT</var>, and <var>SYSOPT</var> parameters. 

====CAUDIT parameter====

The <var>[[CAUDIT parameter|CAUDIT]]</var> parameter controls physical input lines from a terminal, procedure, some IFAM arguments, or full-screen input. <var>CAUDIT</var> operates at physical line (card) level. It controls the auditing of input lines after line editing has been performed, but before line continuation is interpreted. 

<var>CAUDIT</var> is set on any user parameter line at the beginning of CCAIN, and can be reset by a user with system manager privileges who logs in with that user number. (<var>CAUDIT</var> is generally used only by Technical Support staff in special instances.)

====LAUDIT parameter====

The <var>[[LAUDIT parameter|LAUDIT]]</var> parameter controls logical input lines from a terminal or procedure, some IFAM arguments, and full screen information. <var>LAUDIT</var> is useful in reconstructing events that lead to a system crash. 

Set <var>LAUDIT</var> on any user parameter (<var>IODEV</var>) line or at the beginning of CCAIN. For example:
PAGESZ=6184,NUSERS=1,NSERVS=1,NFILES=20,
LENQTBL=15,LAUDIT=5, ...


<var>LAUDIT</var> can be reset by a user with system manager privileges who logs in with that user number.


====SYSOPT parameter====

The <var>[[SYSOPT parameter|SYSOPT]]</var> 32 option controls output of information that relates to system initialization or to an IFAM function call.


===Sizing the journal buffer===

In z/OS and z/VM only, you can specify the <var>NJBUFF</var> parameter on the EXEC statement to make journal entries of one user without interrupting other current users. Valid settings are the default <code>NJBUFF=1</code> or, to ensure the availability of a free buffer:
NJBUFF = NSERVS + NSUBTKS + 1


In z/OS only, if the setting of the NJBUFF parameter is greater than 1, the setting is automatically recalculated using the previous formula and the initial value of <var>NJBUFF</var> is used to define the number of concurrent I/O operations (NCP) for the journal data set. Sizing <var>NJBUFF</var> to the value calculated in the formula guarantees the optimal number of Network Control Programs (NCP) for the journal data set.

If you use the <var>NJBUFF</var> option, specify <code>BLKSIZE=6749</code> as the minimum journal buffer size to allow a full page to be written to a single journal buffer. The contents of a buffer are automatically written to CCAJRNL before the buffer is completely full.

Messages giving the number of journal buffers and the number of bytes allocated to the buffers are displayed at the end of the run.

===Managing space requirements for all operating systems===

The space requirement for CCAJRNL is reduced, if CCAJLOG is enabled. However, CCAJRNL must still be sized to prevent B37, D37, or E37 abends, which will terminate the run and require recovery to get files to a state of logical and physical consistency. The same applies to CCAJLOG: If it fills, the run terminates and recovery is required. Generous secondary extents allocated to these data set also help avoid overflow problems.

====Additional managing space requirement on z/OS====

At a z/OS site, the most comprehensive way to avoid data set full problems is to define both CCAJRNL and CCAJOG as generation data groups (GDGs). See [[Configuring checkpoint and journal data streams#Perpetual journaling for z/OS|Perpetual journaling for z/OS]].

==Model 204 statistics==

A statistic is written to CCAAUDIT only if its value is nonzero. However, all statistics, even those with zero values, are written to CCAJRNL (or CCAJLOG). 

===Audit trail and journal statistics lines===

The statistics generated on audit trail lines are valuable in a study of the performance of an individual user or of the <var class="product">Model 204</var> system as a whole. The effect of configuration changes within <var class="product">Model 204</var> and with other jobs in the operating system can be determined by comparing statistics gathered in <var class="product">Model 204</var> runs.
<ul>
<li>Statistics described as percentages are multiplied by 10 (a value printed as 1000 represents 100 percent). </li>

<li>Statistics described as averages are multiplied by 1000 (1000 represents 1.000).</li>
</ul>

===Output lines===

Statistics for each user and file active during a particular run are written to the journal and audit trail files in output lines that begin with <code>ST $$$</code>. The output lines are written in groups of related lines that include: 
<ul>
<li>User lines, which you can monitor to identify active users and to help determine if individual applications are efficiently implemented</li>

<li>File lines</li>

<li>System lines, which you can watch — together with file lines — to signal shifting loads on the CPU, disks, and terminals </li>
</ul>

The type of line written — user, file, or system — is specified by the value of the first parameter after the journal header.

===Identifying subtypes===

The subtype — final, partial, performance, or since-last — within each type is specified by the value of the second parameter after the journal header. In the audit trail, the subtype is indicated by <code>USERID=user-id</code> (user statistics), <code>FILE=filename</code> (file statistics), and <code>SYSTEM=Model-204-version</code> (system statistics). 

Within each major type of statistics line, subtypes are produced under specified conditions: some are always produced, others are optional. Optional subtypes are produced if the appropriate parameters are set during system initialization. See [[Tracking system activity (CCAJRNL, CCAAUDIT, CCAJLOG)#Setting the NSUBTKS parameter|Setting the NSUBTKS parameter]]. 

==Monitoring statistics==

The <var class="product">Model 204</var> statistics that you can monitor are introduced in [[Using system statistics]]. The statistics are presented in alphabetical order with their stated purpose, followed by tables that identify their position in various layouts.

You can monitor statistics using one or more of the following methods: 
<ul>
<li>Print out the audit trail. </li>

<li>View formatted or unformatted displays of all nonzero cumulative statistics for active users — individual, specified groups, and all users — and system activities.</li>

<li>Use the AUDIT204 or UTILJ utility program to extract and summarize statistics lines from the journal data set. See [[#AUDIT204 utility|the AUDIT204 utility]] and [[System and media recovery#Using the UTILJ utility|Using the UTILJ utility]]
</li>

<li>Write optional records to the System Management Facilities (SMF) data set; see [[Using system statistics#System Management Facilities|System Management Facilities]]. </li>
</ul>

===Setting the NSUBTKS parameter===

Gathering partial or performance statistics lines requires a <var class="product">Model 204</var> pseudo subtask. <var class="product">Model 204</var> uses pseudo subtasks to perform actions that must be done regularly but that cannot be assigned to a specific user. To accommodate partial and performance statistics lines you might need to increase the <var>NSUBTKS</var> parameter on User 0's parameter line, which controls the maximum number of [[Controlling system operations (CCAIN)#Pseudo subtasks|pseudo subtasks]] that can be allocated. 

===Setting parameters to collect certain statistics===

You must set various parameters to collect certain statistics. The following table lists the statistics and the corresponding parameter(s):
<table>
<caption>Parameters to set to collect certain statistics</caption>
<tr class="head">
<th>Statistic </th>
<th>Parameter to set to nonzero</th>
</tr>

<tr>
<td>BLKCFRE </td>
<td>CFRJRNL and CFRLOOK</td>
</tr>

<tr>
<td>BLKI</td>
<td>RPTCNT and SMPLTIM</td>
</tr>

<tr>
<td>BLKO</td>
<td>RPTCNT and SMPLTIM</td>
</tr>

<tr>
<td>BLKRLK </td>
<td>CFRJRNL and CFRLOOK</td>
</tr>

<tr>
<td>LONGUPDTIME(MS)</td>
<td>MAXUD</td>
</tr>

<tr>
<td>LONGUPDTS</td>
<td>MAXUD</td>
</tr>

<tr>
<td>PNDGTIME</td>
<td>DKUPDTWT</td>
</tr>

<tr>
<td>REDY </td>
<td>RPTCNT and SMPLTIM</td>
</tr>

<tr>
<td>RUNG </td>
<td>RPTCNT and SMPLTIM</td>
</tr>

<tr>
<td>SMPLS</td>
<td>RPTCNT and SMPLTIM</td>
</tr>

<tr>
<td>SWPG</td>
<td>RPTCNT and SMPLTIM</td>
</tr>

<tr>
<td>USRS</td>
<td>RPTCNT and SMPLTIM</td>
</tr>

<tr>
<td>WTCFR </td>
<td>CFRJRNL and CFRLOOK</td>
</tr>

<tr>
<td>WTRLK </td>
<td>CFRJRNL and CFRLOOK</td>
</tr>

<tr>
<td>WTSV </td>
<td>RPTCNT and SMPLTIM</td>
</tr>
</table>

==Audit trail format==

Whether printed to CCAAUDIT, either directly from ONLINE/BATCH204 (with two exceptions), or from AUDIT204,
the format of an audit trail line is shown below. The two exceptions are:

<ul>
<li>
The YEARFORM 4 parameter is not available in ONLINE/BATCH204; it is only available in AUDIT204.
This means that a 4-digit year cannot be printed in a CCAAUDIT generated by ONLINE/BATCH204.
</li>
<li>
The TIMEHH parameter is not available in ONLINE/BATCH204; it is only available in AUDIT204.
This means that the time stamp with hundredths of a second cannot be printed in a CCAAUDIT generated
by ONLINE/BATCH204.
</li>
</ul>

yydddhhmmss seq sssss uuuuu tt audit-trail-text ...
or
yydddhhmmsshu seq sssss uuuuu tt audit-trail-text ... '''(if TIMEHH was specified)'''


Where:
<ul>
<li><var class="term">yyddd</var> is the Julian year and day.</li>

<li><var class="term">hhmmss</var> is the time of day in hours, minutes, and seconds.</li>
<li><var class="term">hhmmsshu</var> is the time of day in hours, minutes, seconds, hundredths.</li>

<li><var class="term">seq</var> sequence number is a counter to distinguish lines produced in the same second.
</li>

<li><var class="term">sssss</var> is the 5-digit server number the user is currently using. (Leading zeros are suppressed.)</li>

<li><var class="term">uuuuu</var> is the 5-digit user number. (Leading zeros are suppressed.)</li>

<li><var class="term">tt</var> is code for the type of audit trail line. The tt codes are shown in the
"Types of audit trail lines" table, below.</li>
</ul>

====Example 1, CCAAUDIT output direct from ONLINE====

'''COLUMN: These three lines'''
'''2 15 18 23 25 are not present'''
'''DATE/TIME SEQ# S# USR# TYPE in actual output'''

23256145406 0 0 0 RK ... START VERSION =7.8.0A SMF SYSTEM ID = RS26 XX-
23256145406 1 0 0 XX
23256145406 2 0 0 AD /// **************************************************************************
23256145406 3 0 0 AD /// * Model 204 is proprietary to and a registered trademark of Rocket *
23256145406 4 0 0 AD /// * Software, Inc. All title, copyright and other proprietary rights shall *
23256145406 5 0 0 AD /// * be retained by Rocket Software, Inc. Model 204 has been licensed by *
23256145406 6 0 0 AD /// * this customer and the use and protection of Model 204 is governed by *
23256145406 7 0 0 AD /// * the license agreement between the customer and Rocket Software, Inc. *
23256145406 8 0 0 AD /// * *
23256145406 9 0 0 AD /// * Copyright (C) 2016 Rocket Software, Inc. *
23256145406 10 0 0 AD /// * or its affiliates *
23256145406 11 0 0 AD /// **************************************************************************
23256145406 12 0 0 AD /// M204.0060: Model 204 initialization. Version = 7.8.0A 2020/03/06 14.12, RSQL level = 7.8.0A 2020/02/-
23256145406 13 0 0 XX 12 08.14
23256145406 14 0 0 AD /// M204.0061: SMF system ID = RS26, job name = PSTPC780, step name = TPCBV780, job step = , JES ID = J-
23256145406 15 0 0 XX 0130887
23256145406 16 0 0 AD /// M204.0062: Execute parameters: RCVOPT=9,NJBUFF=115,SYSOPT=139,SYSOPT2=64,LIBUFF=6000,XMEMOPT=3,SIRFU-
23256145406 17 0 0 XX NC=1


====Example 2, CCAAUDIT output from AUDIT204====

AUDIT204 Utility - Version 7.8.0A, Assembly date/time: 20200229 22.08
Date/time of run: 09/07/2023 12:56:01
CCAJRNL or CCAJLOG version: 7.8.0A
Zaps: 78Z7759 78Z7891 78Z7973 78Z7975 78Z8066 78Z8075

'''COLUMN: These three lines'''
'''2 18 24 30 32 are not present '''
'''DATE/TIME SEQ# SERV# USER# TYPE in actual output'''

'''FORMAT TIMEHH'''
2216613441420 0 0 0 RK ... START VERSION =7.8.0A SMF SYSTEM ID = RS26 XX-
2216613441420 1 0 0 XX
2216613441420 2 0 0 AD /// **************************************************************************
2216613441420 3 0 0 AD /// * Model 204 is proprietary to and a registered trademark of Rocket *
2216613441420 4 0 0 AD /// * Software, Inc. All title, copyright and other proprietary rights shall *
2216613441420 5 0 0 AD /// * be retained by Rocket Software, Inc. Model 204 has been licensed by *
2216613441420 6 0 0 AD /// * this customer and the use and protection of Model 204 is governed by *
2216613441420 7 0 0 AD /// * the license agreement between the customer and Rocket Software, Inc. *
2216613441420 8 0 0 AD /// * *
2216613441420 9 0 0 AD /// * Copyright (C) 2016 Rocket Software, Inc. *
2216613441420 10 0 0 AD /// * or its affiliates *
2216613441420 11 0 0 AD /// **************************************************************************
2216613441420 12 0 0 AD /// M204.0060: Model 204 initialization. Version = 7.8.0A 2020/03/06 14.12, RSQL level = 7.8.0A 2-
2216613441420 13 0 0 XX 020/02/12 08.14
2216613441420 14 0 0 AD /// M204.0061: SMF system ID = RS26, job name = PSTPC780, step name = TPCBV780, job step = , JES-
2216613441420 15 0 0 XX ID = J0536896
2216613441420 16 0 0 AD /// M204.0062: Execute parameters: RCVOPT=9,NJBUFF=115,SYSOPT=139,SYSOPT2=64,LIBUFF=6000,XMEMOPT=-
2216613441420 17 0 0 XX 3,SIRFUNC=1


====Example 3, CCAAUDIT output from AUDIT204====

AUDIT204 Utility - Version 7.8.0A, Assembly date/time: 20200229 22.08
Date/time of run: 09/07/2023 14:09:46
CCAJRNL or CCAJLOG version: 7.8.0A
Zaps: 78Z7759 78Z7891 78Z7973 78Z7975 78Z8066 78Z8075

'''COLUMN: These three lines'''
'''2 18 24 30 32 are not present '''
'''DATE/TIME SEQ# SERV# USER# TYPE in actual output'''

'''FORMAT'''
'''YEARFORM 4'''
2022166134414 0 0 0 RK ... START VERSION =7.8.0A SMF SYSTEM ID = RS26 XX-
2022166134414 1 0 0 XX
2022166134414 2 0 0 AD /// **************************************************************************
2022166134414 3 0 0 AD /// * Model 204 is proprietary to and a registered trademark of Rocket *
2022166134414 4 0 0 AD /// * Software, Inc. All title, copyright and other proprietary rights shall *
2022166134414 5 0 0 AD /// * be retained by Rocket Software, Inc. Model 204 has been licensed by *
2022166134414 6 0 0 AD /// * this customer and the use and protection of Model 204 is governed by *
2022166134414 7 0 0 AD /// * the license agreement between the customer and Rocket Software, Inc. *
2022166134414 8 0 0 AD /// * *
2022166134414 9 0 0 AD /// * Copyright (C) 2016 Rocket Software, Inc. *
2022166134414 10 0 0 AD /// * or its affiliates *
2022166134414 11 0 0 AD /// **************************************************************************
2022166134414 12 0 0 AD /// M204.0060: Model 204 initialization. Version = 7.8.0A 2020/03/06 14.12, RSQL level = 7.8.0A 2-
2022166134414 13 0 0 XX 020/02/12 08.14
2022166134414 14 0 0 AD /// M204.0061: SMF system ID = RS26, job name = PSTPC780, step name = TPCBV780, job step = , JES-
2022166134414 15 0 0 XX ID = J0536896
2022166134414 16 0 0 AD /// M204.0062: Execute parameters: RCVOPT=9,NJBUFF=115,SYSOPT=139,SYSOPT2=64,LIBUFF=6000,XMEMOPT=-
2022166134414 17 0 0 XX 3,SIRFUNC=1


====Example 4, CCAAUDIT output from AUDIT204====

AUDIT204 Utility - Version 7.8.0A, Assembly date/time: 20200229 22.08
Date/time of run: 09/13/2023 13:34:45
CCAJRNL or CCAJLOG version: 7.8.0A
Zaps: 78Z7759 78Z7891 78Z7973 78Z7975 78Z8066 78Z8075

'''COLUMN: These three lines'''
'''2 20 26 32 34 are not present '''
'''DATE/TIME SEQ# SERV# USER# TYPE in actual output'''

'''FORMAT TIMEHH'''
'''YEARFORM 4'''
202216613441420 0 0 0 RK ... START VERSION =7.8.0A SMF SYSTEM ID = RS26 XX-
202216613441420 1 0 0 XX
202216613441420 2 0 0 AD /// **************************************************************************
202216613441420 3 0 0 AD /// * Model 204 is proprietary to and a registered trademark of Rocket *
202216613441420 4 0 0 AD /// * Software, Inc. All title, copyright and other proprietary rights shall *
202216613441420 5 0 0 AD /// * be retained by Rocket Software, Inc. Model 204 has been licensed by *
202216613441420 6 0 0 AD /// * this customer and the use and protection of Model 204 is governed by *
202216613441420 7 0 0 AD /// * the license agreement between the customer and Rocket Software, Inc. *
202216613441420 8 0 0 AD /// * *
202216613441420 9 0 0 AD /// * Copyright (C) 2016 Rocket Software, Inc. *
202216613441420 10 0 0 AD /// * or its affiliates *
202216613441420 11 0 0 AD /// **************************************************************************
202216613441420 12 0 0 AD /// M204.0060: Model 204 initialization. Version = 7.8.0A 2020/03/06 14.12, RSQL level = 7.8.0A-
202216613441420 13 0 0 XX 2020/02/12 08.14
202216613441420 14 0 0 AD /// M204.0061: SMF system ID = RS26, job name = PSTPC780, step name = TPCBV780, job step = , J-
202216613441420 15 0 0 XX ES ID = J0536896
202216613441420 16 0 0 AD /// M204.0062: Execute parameters: RCVOPT=9,NJBUFF=115,SYSOPT=139,SYSOPT2=64,LIBUFF=6000,XMEMOP-
202216613441420 17 0 0 XX T=3,SIRFUNC=1



The following table lists the code and purpose of the audit trail lines:

<table>
<caption>Types of audit trail lines</caption>
<tr class="head">
<th>Code</th>
<th>Displays...</th>
</tr>

<tr>
<td>AD</td>
<td>Special information about the run, job step return code, status of <var class="product">Model 204</var> files, user or the password table, the SNA Communications Server (formerly VTAM) Interface, or messages sent from an HLI program via the IFERR call.</td>
</tr>

<tr>
<td>CI</td>
<td>Physical input line from a user's terminal or some IFAM arguments.</td>
</tr>

<tr>
<td>CP</td>
<td>Physical input line from a procedure.</td>
</tr>

<tr>
<td>CS</td>
<td>Physical line of full-screen input (see LS below).</td>
</tr>

<tr>
<td>ER</td>
<td>Error message sent to the user.</td>
</tr>

<tr>
<td>LI</td>
<td>Logical input line from a user's terminal or some HLI arguments.</td>
</tr>

<tr>
<td>LP</td>
<td>Logical input line from a procedure.</td>
</tr>

<tr>
<td>LR</td>
<td>Read images from a terminal.</td>
</tr>

<tr>
<td>LS</td>
<td>Full-screen information. For a screen, each line lists one input value. For a menu, the line provides the menu selection number.</td>
</tr>

<tr>
<td>MS</td>
<td>Informational message sent to the user (not an error).</td>
</tr>

<tr>
<td>OI</td>
<td>Input line from the operator's console.</td>
</tr>

<tr>
<td>OO</td>
<td>Message sent to the operator's console.</td>
</tr>

<tr>
<td>RK</td>
<td>Special information that relates to system initialization or to the record of a call to the following types of function:
<ul>
<li>Connect★</li>

<li>HLI</li>

<li>MQ/204</li>

<li>PQO</li>

<li>SQL</li>

<li>UL/DB2</li>
</ul>
</td></tr>

<tr>
<td>QT</td>
<td>Lines of SQL statement level processing </td>
</tr>

<tr>
<td>ST</td>
<td>Utilization statistics (see [[Using system statistics]]).</td>
</tr>

<tr>
<td>US</td>
<td>Line of special information directed to the audit trail by means of the SOUL <var>Audit</var> statement.</td>
</tr>

<tr>
<td>XX</td>
<td>Continuation of the previous line.</td>
</tr>
</table>

==Generating an audit trail==

===Overview of audit trail parameters===

An audit trail is generated if: 
<ul>
<li>The <var>SYSOPT</var> parameter includes the 128 specification</li>

<li>CCAAUDIT DD statement</li>
</ul>

The <var>[[LAUDPROC parameter|LAUDPROC]]</var> parameter controls the length of procedure names that appear in since-last statistic lines of the audit trail. You can reset <var>LAUDPROC</var> to a low or high value. A low value conserves memory. A high value captures long procedure names. 

===z/VSE and the audit trail===

In a z/VSE environment, activate the audit trail by incorporating the following specifications into the JCL:
<ul>
<li>You must set UPSI to <code>1xxxxxxx</code> (<code>SYSOPT=128</code>).</li>

<li>You must write the audit trail file to either a disk device or a print device:
<ul>
<li>Assign a disk device using a DLBL and EXTENT statement for file name <code>CCAUDIT</code> (retention 0 is recommended).</li>

<li>Assign a print device using symbolic unit <code>SYS008</code>. (You cannot assign <code>SYS008</code> to the same physical device as SYSLST.)

If the DLBL and EXTENT for CCAUDIT are provided in the JCL, the audit trail is written to disk regardless of the assignment of <code>SYS008</code>.</li>
</ul></li>
</ul>

The following example shows a job stream for an <var>ONLINE</var> configuration with the audit trail on disk:
// JOB ONLINE
...
// DLBL CCAUDIT,'audit trail file-id',0
// EXTENT SYSnnn,balance of extent information
// ASSGN SYSnnn,X'cuu'
...
// UPSI 10000000
// EXEC ONLINE, SIZE=AUTO
...
/&


After the audit trail has been written to disk, you can print it using the UTLA utility program supplied with the <var class="product">Model 204</var> DBMS.

Use the following JCL:
// JOB UTLA PRINT MODEL 204 AUDIT TRAIL
// DLBL M204LIB,'M204.PROD.LIBRARY'
// EXTENT SYSnnn,...
// LIBDEF PHASE.SEARCH=M204LIB.V411
// DLBL CCAUDIT,'audit trail file-id'
// EXTENT SYSnnn,balance of extent information
// ASSGN SYSnnn,X'cuu'
// ASSGN SYS005,SYSLST
// EXEC UTLA,SIZE=AUTO
/&


===z/VM and the audit trail===

In the z/VM/CMS environment, define CCAAUDIT as one of the following:
<ul>
<li>CMS file:
FILEDEF CCAAUDIT DISK ONLN CCAAUDIT A</li>

<li>Service machine virtual printer:
FILEDEF CCAAUDIT PRINTER</li>
</ul>

==AUDIT204 utility==

The AUDIT204 utility program produces the following reports, all of which are written to CCAAUDIT:
<ul>
<li>Complete or partial audit trail from a journal — CCAJRNL or CCAJLOG, as ddname CCAJRNL — produced by a <var class="product">Model 204</var> run</li>

<li>Report based on statistics that appear on user logout and partial lines or file closed and partial lines</li>

<li>Statistical analysis of the evaluation of SOUL requests </li>
</ul>

The format of AUDIT204 reports is determined by AUDIT204 commands and parameters you enter in:
<ul>
<li>z/OS CCAIN data stream</li>

<li>z/VM (CMS) AUDIT204 CCAIN file</li>

<li>DOS SYSIPT statement</li>
</ul>

The basic AUDIT204 input commands are:
<table>
<tr class="head">
<th>AUDIT204 command </th>
<th>For... </th>
</tr>

<tr>
<td>ANALYZE </td>
<td>Statistical analysis of the evaluation of User Language requests </td>
</tr>

<tr>
<td>FORMAT </td>
<td>Printed audit trail</td>
</tr>

<tr>
<td>REPORT </td>
<td>Breakdown of user and file statistics lines containing optional price calculations</td>
</tr>
</table>

===Input to AUDIT204===

Input to AUDIT204 is free form, located in columns 1-71. The following rules apply:
<ul>

<li>The command line may have one parameter and its subparameters.</li>

<li>Type each subsequent parameter on a separate line.</li>

<ul>
<li>Use blanks to separate subparameters.</li>
</ul>

<li>You can type parameters for a single command in any order.</li>

<li>You can add subparameters for some parameters (PRICE and RENAME) by naming the subparameters in the form of character strings:
<ul>
<li>If a name contains a blank or a single quotation mark, you must enclose the name in single quotation marks.</li>

<li>Use double quotation marks within the name.</li>

<li>Use blanks around the equal signs in the PRICE and RENAME parameters.</li>

<li>Use blanks to separate subparameters.</li>

<li>If more than one line is required for the subparameters, place a nonblank character in column 72 or repeat the parameter on a new line. </li>
</ul></li>

<li>Any characters appearing in columns 73-80 are ignored. </li>

<li>You can repeat any parameter. </li>

<li>Precede each comment by an asterisk (<tt>*</tt>) in column 1.</li>

<li>The effect of parameters containing lists of subparameters is cumulative. </li>

<li>The last value of parameters without subparameter lists is the value used. </li>
</ul>

===ANALYZE command===

The <var>ANALYZE</var> command produces a statistical analysis report on the evaluation of SOUL requests. The complete report comprises an analysis for each individual account and the system as a whole. 

Since-last evaluation lines calculate the mean and standard deviation for each since-last statistic:
<table>
<tr class="head">
<th>Measure </th>
<th>Represents... </th>
</tr>

<tr>
<td>Mean </td>
<td>Center of a set of data points (usually referred to as the average value of the set), obtained by summing the values and dividing by the number of values.</td>
</tr>

<tr>
<td nowrap>Standard deviation </td>
<td>How spread out the data is around the center. In particular, it is useful to know whether the data is tightly clustered around the mean, or more dispersed.

A small standard deviation indicates that any given value is likely to be close to the mean, and a large standard deviation implies that a value is more likely to be far away from the mean. 
</td>
</tr>
</table>

You can obtain more information about the mean and the standard deviation from any standard statistics textbook.

====Syntax====

Use the following syntax for the <var>ANALYZE</var> command:
ANALYZE [USERID | NOUSERID] [USERIDS userid1...useridn]


or
ANALYZE [ACCOUNT | NOACCOUNT] [ACCOUNTS account1...accountn]
[parameters]


Where:

Use the following parameters with the <var>ANALYZE</var> command:
<table>
<tr class="head">
<th>Parameter </th>
<th>Specifies...</th>
</tr>

<tr>
<td><var>ACCOUNT</var>
or <var>NOACCOUNT</var></td>
<td>Whether or not to do an individual account analysis. The <var>ACCT</var> or <var>NOACCT</var> parameters are equivalent to <var>ACCOUNT</var> or <var>NOACCOUNT</var>, respectively. </td>
</tr>

<tr>
<td><var>ACCOUNTS</var> </td>
<td>Login account name(s) to list in the analysis report.

Reports are produced only for the specified accounts and only the since-last evaluation lines for those accounts that are included in the systemwide report.

Specifying <var>ACCOUNTS</var> sets the <var>ACCOUNT</var> parameter when neither <var>ACCOUNT</var> nor <var>NOACCOUNT</var> was specified.
</td>
</tr>

<tr>
<td><var>OMIT name1 name2...</var> </td>
<td>Since-last statistic(s) to list, but omit from the analysis report. The report contains all since-last statistics that are not explicitly omitted. Specifying file or user statistics will generate an error message and terminate the ANALYZE.</td>
</tr>

<tr>
<td nowrap><var>RENAME name=newname</var> </td>
<td>New names to since-last statistics as column headings for an analysis report.</td>
</tr>

<tr>
<td><var>TIME [yydddhhmmss / yydddhhmmss | cyydddhhmmss / cyyddhhmmss]</var></td>
<td>Time range from which since-last evaluation lines are taken.</td>
</tr>

<tr>
<td><var>SYS</var> (the default)
 or <var>NOSYS</var> </td>
<td>Whether or not to do a systemwide analysis using since-last evaluation lines of accounts for which an individual analysis is done. </td>
</tr>

<tr>
<td><var>USERID</var> (the default)
 or <var>NOUSERID</var> </td>
<td>Performing or suppressing an individual user ID analysis. Totals for a systemwide analysis are still accumulated if <var>NOUSERID</var> is specified.</td>
</tr>

<tr>
<td><var>USERIDS</var> </td>
<td>User(s) for which analysis is requested.

The <var>USERIDS</var> keyword is required in addition to the <var>USERID</var> keyword. If neither <var>USERID</var> nor <var>NOUSERID</var> has been specified, specifying <var>USERIDS</var> sets the <var>USERID</var> parameter.

Reports are produced only for the specified users and only the since-last evaluation lines for those users who are included in the systemwide report. 

AUDIT204 uses the values specified in the <var>USERID</var> parameter as a pattern and finds all values that match. For example, <code>USERIDS NANCY KATHY</code> is equivalent to <code>REPORT USERID USERIDS NANCY* KATHY*</code>.</td></tr>
</table>

===FORMAT command===

<var>FORMAT</var> prints an audit trail (CCAAUDIT) from CCAJRNL or CCAJLOG. 

====Syntax====
FORMAT TIME {yydddhhmmss/yydddhhmmss | cyydddhhmmss/cyydddhhmmss}
TIMEHH
TYPE type1
USER usernum
USERID userid
YEARFORM {2 | 4}


Where:

You use the following parameters with the <var>FORMAT</var> command:
<table>
<tr class="head">
<th>Parameter </th>
<th>Specifies...</th>
</tr>

<tr>
<td><var>TIME</var> </td>
<td>Time range to print. The format of the time specification corresponds to the time stamp printed with each audit trail line.

You can specify start and end times in either order. If either time is out of the range covered by the journal, it is corrected to match the actual start or end of the journal. 

If both specified times are before and after the period covered by the journal, nothing is printed.
<ul>
<li><var class="term">yyddd</var> is the year and Julian date; <var class="term">cyyddd</var> is the century, year and Julian date (0=20th century, 1=21st century).</li>

<li><var class="term">hhmmss</var> is time based on a 24-hour clock. </li>
</ul>
NOTE: TIME may be specified with no time range or with a time range in the form noted above. No time range selects the entire journal/jlog for printing.
</td></tr>

<tr>
<td><var>TIMEHH</var> </td>
<td>Indicates that timestamps, printed at the beginning of each line of output, should include hundredths of a second. Requires no other arguments.
NOTE: This parameter and the 78 version of AUDIT204 may be used against a 77 or 78 CCAJRNL or CCAJLOG.
NOTE: TIMEHH may be specified with no time range or with a time range in the form noted above. No time range selects the entire journal/jlog for printing.
</td>
</tr>

<tr>
<td><var>TYPE</var> </td>
<td>Type of lines to print, such as AD or MS (see the [[#Example|"Types of audit trail lines" table]]).</td>
</tr>

<tr>
<td><var>USER</var> </td>
<td>User for whom the printed audit trail lines are generated. Specify user numbers with or without leading zeros. </td>
</tr>

<tr>
<td><var>USERID</var> </td>
<td>One- to ten-character name that identifies the <var class="product">Model 204</var> user about whom the printed audit trail lines are generated.</td>
</tr>

<tr>
<td><var>YEARFORM</var></td>
<td>Two- or four-digit year output. The default is 2.</td>
</tr>
</table>

====Example====

The options specified in the following example restrict the printing of the audit trail to <code>MS</code> (message) lines for <code>USER 01</code> created on September 22, 1998 between 10:41 A.M. and 10:45 A.M.:
FORMAT TYPE MS, ER
TIME 98265104100/98265104500
USER 01


====Usage====

The <var>FORMAT</var> command can be used against a CCAJRNL or CCAJLOG data set. Examine the code examples that begin in [[#Samples of a z/OS job stream|Samples of a z/OS job stream]]. 

===REPORT command===

The <var>REPORT</var> command prints user and file statistics in a tabular format and computes costs by account or by file for billing purposes. AUDIT204 reports have a two-line header, as shown in the following example, that reflect the circumstances of your site. 
AUDIT204 UTILITY - VERSION 7.6.0D
DATE/TIME OF RUN: 10/11/2016 12:25:50


====Syntax====
REPORT type [parameters]


Where:
<ul>
<li><var class="term">type</var> is a subcommand that specifies the type of report to print:
<table>
<tr class="head">
<th>Subcommand </th>
<th>Specifies printing a report from...</th>
</tr>

<tr>
<td><var>ACCOUNT</var> </td>
<td>User statistics for all accounts </td>
</tr>

<tr>
<td><var>ACCOUNTS</var> account1 account2 ...</td>
<td>User statistics for specified accounts</td>
</tr>

<tr>
<td><var>USERID</var> </td>
<td>User statistics for all users</td>
</tr>

<tr>
<td><var>USERID USERIDS user1 user2 ...</var> </td>
<td>User statistics for users listed</td>
</tr>

<tr>
<td><var>FILE</var> </td>
<td>File statistics for all files</td>
</tr>

<tr>
<td><var>FILE FILES fname1 fname2 ...</var> </td>
<td>File statistics for files listed</td>
</tr>

</table></li>

<li><var class="term">parameters</var> is one or more of
the following, which can be used with <var>USERID</var>, <var>ACCOUNT</var>, or <var>FILE</var>:
<table>
<tr class="head">
<th>Parameter </th>
<th>Specifies...</th>
</tr>

<tr>
<td><var>IND</var> (the default)
 or <var>NOIND</var> </td>
<td>Printing or not printing individual lines. Totals are still accumulated if <var>NOIND</var> is specified.</td>
</tr>

<tr>
<td><var>OMIT</var> </td>
<td>Statistic(s) to omit from the report. You must enter the actual name of the statistic, not what appears in a column header in a report. Only file statistics are valid for FILE reports and only since-last and logout stats are valid for USERID reports. See [[Using system statistics#Description of statistics|Description of statistics]] for an alphabetical listing of statistics.</td>
</tr>

<tr>
<td><var>PARTIAL</var>
 or <var>NOPARTIAL</var> </td>
<td>Generation of partial or complete statistics lines. Use:
<ul>
<li><var>PARTIAL</var> when a report is generated from a journal that did not terminate successfully.</li>

<li><var>NOPARTIAL</var> to avoid processing overhead, when a complete journal is available.</li>
</ul>
</td></tr>

<tr>
<td><var>PRICE</var> </td>
<td>Dollar charge up to five decimal places to any statistic. Decimal point, and leading and trailing zeros are optional. For example:
PRICE CPU=0.05 DKRD=.03 DKWR=.035
</td></tr>

<tr>
<td><var>RENAME</var> </td>
<td>Column heading names up to nine characters without truncation. The new name completely replaces the old name and must be used if name is specified on other parameters.</td></tr>

<tr>
<td><var>TIME</var> </td>
<td>Time range for statistics line reporting. One of the following formats is required:
<ul>
<li><var class="term">yydddhhmmss</var><tt>/</tt><var class="term">yydddhhmmss</var> </li>

<li><var class="term">cyydddhhmmss</var><tt>/</tt><var class="term">cyydddhhmmss</var> </li>
</ul>
</td></tr>

<tr><td nowrap><var>TOTAL</var> (the default)
 or <var>NOTOTAL</var> </td>
<td>Totalling or suppression of totalling for individual statistics and costs. </td>
</tr>
</table></li>
</ul>

====Example====

Totals are printed after individual statistics lines if both <var>IND</var> and <var>TOTAL</var> are in effect. Each line must contain only one parameter, as in the following examples:
REPORT USERID NOIND
PARTIAL
TIME yydddhhmmss/yydddhhmmss
RENAME name=newname
NOTOTAL
USERIDS account

REPORT FILE FILES fname1 fname2 fname3 ...
OMIT statistic
PRICE statistic=xx.xx


The subkeywords <var>ACCOUNTS</var>, <var>FILES</var>, and <var>USERIDS</var> can be used with <var>REPORT</var> subcommands <var>ACCOUNT</var>, <var>FILE</var>, and <var>USERID</var> as in the following examples:
REPORT USERID USERIDS JAMES STEVE SANDRA
ACCOUNT ACCOUNTS JAMES STEVE SANDRA
FILE FILES CLIENTS VEHICLES DAILY

Note: The <var>REPORT</var> command for AUDIT204 can process only a single journal: CCAJRNL. You cannot use against a CCAJOG file.

==Using the AUDIT204 utility==

===CCAJRNL and CCAJLOG data sets as input to utilities===

When you need a CCAAUDIT report, use the CCAJLOG data set as input to the AUDIT204 utility, under the ddname of CCAJRNL. You can also use CCAJLOG as input to the UTILJ utility, again under the ddname of CCAJRNL; however, the only useful report produced is a histogram of the number of blocks and block sizes that were written to the CCAJLOG data set.

CCAJRNL is the input data set provided to roll forward recovery (ddname=CCARF), media recovery (ddname= CCAGEN), and UTILJ (ddname=CCAJRNL).

Utilities using CCAJLOG and CCAJRNL data sets as input
[[File:SM13ccaprint3_sep.gif|457px]] 

===Journal stream configurations===

AUDIT204 can process only basic journal streams (single data sets). Members of concatenated, parallel, ring, or GDG streams must be processed one at a time.

If there is a wraparound during the output processing of a ring stream, use the offload stream as input to AUDIT204. You can also use regular z/OS concatenation to print the contents of a concatenated stream.

===z/OS JCL for AUDIT204===

The following considerations apply to z/OS JCL for AUDIT204:
<ul>
<li>Use a SORTLIB DD statement to identify the library in which the sort program is stored, if necessary.</li>

<li>You might need sort work (SORTWKxx) data sets.</li>

<li>SORTIN, SORTOUT, and SYSOUT statements are necessary only for statistical reports. A sort program must be available:
<ul>
<li>SORTIN contains all the user and file statistics entries extracted from the journal. The size of the data set depends on the number of statistics entries extracted. Each user statistics entry is 198 bytes long. Each file entry is 82 bytes long. Partial statistics entries are not copied to SORTIN.</li>

<li>SORTOUT contains the sorted statistics entries from SORTIN. SORTOUT and SORTIN must be the same size.</li>

<li>SYSOUT is the SORT message data set.</li>
</ul></li>

<li>STATIN, STATOUT, and SYSOUT statements are necessary only for statistical analysis reports:
<ul>
<li>STATIN contains all the since-last evaluation statistics entries extracted from the journal. The size of the data set depends on the number of since-last evaluation statistics extracted. Each since-last evaluation statistics entry is 188 bytes long.</li>

<li>STATOUT contains the sorted statistics entries from STATIN. STATOUT and STATIN must be the same size. </li>

<li>Statistics work (STATWKxx) data sets might be needed when using the ANALYZE command, depending on the amount of data generated.</li>
</ul></li>

<li>CCAJRNL describes the data set containing the journal produced by a <var class="product">Model 204</var> run.</li>

<li>AUDIT204 does not support streams. </li>

<li>CCAAUDIT contains the audit trail, statistics report, and statistical analysis report. If you request both the audit trail and statistics, the audit trail appears first.

The value of the BLKSIZE parameter in the CCAAUDIT DD statement is truncated at 4 more than a multiple of 137. A BLKSIZE value of 141 is the default and minimum value.

Any LRECL and RECFM specifications are ignored; these parameter values are forced to be 137 and VBA, respectively.</li>
</ul>

===Samples of a z/OS job stream===

The following sample job streams run AUDIT204, These examples differ in the use of the journal processed, CCAJRNL or CCAJLOG, and the presence or absence of AUDIT204 commands: <var>ANALYZE</var>, <var>FORMAT</var>, and <var>REPORT</var>.

====Where only CCAJRNL is defined, all AUDIT204 commands are valid====
 //AUDIT EXEC PGM=AUDIT204
//STEPLIB DD DSN=M204.LOADLIB,DISP=SHR
//SYSUDUMP DD SYSOUT=A
//CCAJRNL DD DSN=M204.CCAJRNL,DISP=SHR
//CCAAUDIT DD SYSOUT=A
//SORTIN DD DSN=&&SORTIN,UNIT=SYSDA,SPACE=(TRK,nn),
// DISP=(NEW,DELETE)
//SORTOUT DD DSN=*.SORTIN,VOL=REF=*.SORTIN,DISP=(OLD,PASS)
//STATIN DD DSN=&&STATIN,UNIT=SYSDA,SPACE=(TRK,nn),
// DISP=(NEW,DELETE)
//STATOUT DD DSN=*.STATIN,VOL=REF=*.STATIN,DISP=(OLD,PASS)
//SYSOUT DD SYSOUT=A
//CCAIN DD *
FORMAT
ANALYZE
REPORT ACCOUNT
.
. ---- user options
.
/*


====Where CCAJLOG is defined and you want to extract CCAAUDIT====
 //AUDIT EXEC PGM=AUDIT204
//STEPLIB DD DSN=M204.LOADLIB,DISP=SHR
//SYSUDUMP DD SYSOUT=A
//CCAJRNL DD DSN=M204.CCAJLOG,DISP=SHR
//CCAAUDIT DD SYSOUT=A
//SORTIN DD DSN=&&SORTIN,UNIT=SYSDA,SPACE=(TRK,nn),
// DISP=(NEW,DELETE)
//SORTOUT DD DSN=*.SORTIN,VOL=REF=*.SORTIN,DISP=(OLD,PASS)
//STATIN DD DSN=&&STATIN,UNIT=SYSDA,SPACE=(TRK,nn),
// DISP=(NEW,DELETE)
//STATOUT DD DSN=*.STATIN,VOL=REF=*.STATIN,DISP=(OLD,PASS)
//SYSOUT DD SYSOUT=A
//CCAIN DD *
FORMAT
.
. ---- user options
.
/*


====Where both CCAJRNL and CCAJLOG are defined and you want a statistical analysis====
 //AUDIT EXEC PGM=AUDIT204
//STEPLIB DD DSN=M204.LOADLIB,DISP=SHR
//SYSUDUMP DD SYSOUT=A
//CCAJRNL DD DSN=M204.CCAJRNL,DISP=SHR
//CCAAUDIT DD SYSOUT=A
//SORTIN DD DSN=&&SORTIN,UNIT=SYSDA,SPACE=(TRK,nn),
// DISP=(NEW,DELETE)
//SORTOUT DD DSN=*.SORTIN,VOL=REF=*.SORTIN,DISP=(OLD,PASS)
//STATIN DD DSN=&&STATIN,UNIT=SYSDA,SPACE=(TRK,nn),
// DISP=(NEW,DELETE)
//STATOUT DD DSN=*.STATIN,VOL=REF=*.STATIN,DISP=(OLD,PASS)
//SYSOUT DD SYSOUT=A
//CCAIN DD *
ANALYZE
REPORT
.
. ---- user options
.
/*


===z/VSE JCL for AUDIT204===

The following considerations apply to z/VSE: 
<ul>
<li>Under z/VSE, output is sent to SYSLST. </li>

<li>CCAJRNL can be on tape or disk. If CCAJRNL is on tape, SYS004 must be assigned to a tape drive.</li>

<li>Running AUDIT204 might require two sorts:
<ul>
<li><var>REPORT</var> command requires a SORTIN and a SORTOUT data set.</li>

<li><var>ANALYZE</var> command requires a STATIN and a STATOUT data set. </li>
</ul></li>

<li>SORTIN, SORTOUT, STATIN, and STATOUT are work files and must be on disk. </li>

<li>SORTWK1 data set is required.</li>

<li>Statistics work (STATWK1) data set might be needed when using the <var>ANALYZE</var> command, depending on the amount of data generated. </li>
</ul>

===Sample z/VSE job stream===

The following sample job stream runs AUDIT204:
// JOB AUDIT204
// DLBL M204LIB,'M204.PROD.LIBRARY'
// EXTENT SYSnnn,...
// LIBDEF PHASE.SEARCH=M204LIB.V210
// DLBL CCAJRNL,'CCAJRNL' Note 1
// EXTENT SYSnnn,...
// DLBL SORTIN,'AUDIT204.SORTIN',0 Note 2
// EXTENT SYSnnn,...
// DLBL SORTOUT,'AUDIT204.SORTOUT',0 Note 2
// EXTENT SYSnnn,...
// DLBL STATIN,'AUDIT204.STATIN',0 Note 3
// EXTENT SYSnnn,...
// DLBL STATOUT,'AUDIT204.STATOUT',0 Note 3
// EXTENT SYSnnn,...
// DLBL SORTWK1,'SORTWK1',0 Note 4
// EXTENT SYSnnn,...

// EXEC AUDIT204,SIZE=(AUTO,xxK) Note 5
INCLUDE IFYLSQRT
* Insert AUDIT204 CCAIN commands here
FORMAT
REPORT ACCOUNT
REPORT FILE
REPORT ACCOUNT ACCOUNTS MAGGIE MARY DAVE
/*
/&


====Usage notes====
<ul>
<li>If you use tape instead of the DLBL and EXTENT for CCAJRNL, use the following JCL:
// TLBL CCAJRNL
// ASSGN SYS004,X'cuu'
</li>

<li>DLBL and EXTENT are necessary if you use either the <var>REPORT</var> or the <var>ANALYZE</var> command.</li>

<li>You must specify a SIZE parameter in the EXEC statement with AUTO and you need some additional storage for the sort program. To determine the amount of additional storage needed for the sort program, refer to IBM's <var class="book">SORT/MERGE Programmer's Guide</var>.</li>
</ul>

===(z/VM) CMS JCL for AUDIT204===

The CMS AUDIT204 utility program prints a <var class="product">Model 204</var> journal file and produces a statistical report from information in a journal file:
<ul>
<li>If a statistics report is produced, a SORT utility that can be invoked dynamically must be available for use.</li>

<li>AUDIT204 output is produced either as a printer spool file or in a CMS disk file. </li>
</ul>

The following EXEC initiates AUDIT204:

AUDIT204 [datasetname] [filename filetype] filemode


Where:
<ul>
<li><var class="term">datasetname</var> specifies the name of the journal data set on a variable-format disk, with the qualifiers separated by blanks. If no data set name is specified, it is presumed that the name of the journal data set is <code>M204.JOURNAL</code>.</li>

<li><var class="term">filename</var> and <var class="term">filetype</var>
specify the name and type of the journal file on a CMS-format, or a variable format for z/OS and z/VSE, disk.</li>

<li><var class="term">filemode </var> specifies the mode of the disk holding the journal file to be processed. The input to AUDIT204 contains the commands selected from those described earlier and is included in the AUDIT204 CCAIN. </li>
</ul>

===Searching multiple tapes for journal and off load data===

When a journal or offload data set is on multiple tapes, you do not need to mount all of them for AUDIT204 processing. You can process a subset of the tapes, as long as you mount them in the order in which they were originally generated.

For example, suppose that your CCAJRNL data set consists of five tapes labeled <code>TAPE01</code> through <code>TAPE05</code>. You are sure that the information you want to analyze begins on the third tape or later. In this case you can save processing time by specifying only <code>TAPE03</code>, <code>TAPE04</code>, and <code>TAPE05</code> in the DD statement for the CCAJRNL data set.
</div> 

[[Category:System management]]
[[Category:Auditing and problem determination]]
===AUDIT204 Return Codes===
The following return codes may be issued by AUDIT204 upon completion.
<table>
<tr class="head">
<th>Return Code</th>
<th>Meaning</th>
</tr>

<tr>
<td>0</td>
<td>Normal completion</td>
</tr>

<tr>
<td>8</td>
<td>I/O error reading CCAJRNL or CCAJLOG
Out of sequence journal block
Zero length journal block or journal record
</td>
</tr>

<tr>
<td>12</td>
<td>Invalid parameter - various errors with CCAIN input parameters</td>
</tr>

<tr>
<td>16</td>
<td>CCAAUDIT open failed</td>
</tr>

<tr>
<td>20</td>
<td>CCAJRNL or CCAJLOG open failed</td>
</tr>

<tr>
<td>24</td>
<td>SORTIN open failed</td>
</tr>

<tr>
<td>28</td>
<td>STATIN open failed</td>
</tr>

<tr>
<td>32</td>
<td>CCAIN open failed</td>
</tr>

<tr>
<td>36</td>
<td>Operating system does not support Z-architecture</td>
</tr>

System requirements for Application Subsystems

2024-09-27T16:32:06Z

JDamon: /* SUBSYSMGMT privileges screen */

<div class="toclimit-3">
==Overview of CCASYS==

CCASYS is a system file used in conjunction with [[:Category:Dictionary/204|Dictionary/204]] and the [[Subsystem Management facility]] (SUBSYSMGMT). It contains the procedure names, file names, and parameters that create a [[Application Subsystem development|subsystem]] definition. When a subsystem is executed, <var class="product">Model 204</var> opens and reads the CCASYS file.

The CCASYS file must be open to use the Subsystem Management facility and to run any user-written subsystem.

Statistics associated with CCASYS processing are written to the CCAAUDIT system file and can be viewed from a terminal or printed to an audit trail.

This page describes CCASYS and explains how to create and maintain the file.

==Maintaining CCASYS==

===Creating CCASYS===

You can create CCASYS online as a separate file or as a part of the initial installation of Dictionary and the full-screen interface. Regardless of the approach used to create CCASYS, it must be available before Dictionary and the interface are installed. 

A user with system manager privileges can create CCASYS online (see the <var>[[CREATE command: File|CREATE]]</var> command).
The formula for calculating the size of CCASYS is given in the <var class="product">Model 204</var> installation guides.

To create CCASYS during Dictionary installation, follow the instructions given in [[Dictionary/204 installation guide]].

===Reorganizing CCASYS===

For instructions on reorganizing CCASYS and Dictionary files, refer to [[Dictionary/204 operation and file maintenance]].

==Using CCASYS==

You must be a system manager to run the Subsystem Management facility, as well as having privileges defined in the DICTIONARY to use SUBSYSMGMT. (Refer to the DICTADMIN subsystem to add privileges.)

To use the Subsystem Management facility and to run any user-written subsystem, the CCASYS file must be open. <var class="product">Model 204</var> opens CCASYS during initialization when the <var>[[SYSOPT parameter|SYSOPT]]</var> parameter setting includes the X'01' bit (see [[#JCL requirements|JCL requirements]] on this page).

CCASYS is opened and locked in share mode. During the process of defining a subsystem, the lock is changed to exclusive mode for the duration of the session. If more than one copy of <var class="product">Model 204</var> is using the same CCASYS file, the Subsystem Management facility cannot be entered. 

===Subsystems available at initialization===

If the CCASYS file is marked as full (the <var>[[FISTAT parameter|FISTAT]]</var> X'08' bit) during Online initialization, subsystems are now available and the following message is no longer issued:
M204.1457 UNABLE TO SCAN LIST OF SUBSYSTEM NAMES


===JCL requirements===

JCL requirements for CCASYS are:
<ul>
<li>Set the <var>SYSOPT</var> X'01' bit on in the JCL PARM field to enable CCASYS.

The <var>SYSOPT</var> X'01' bit automatically increments NFILES, NDCBS, and NDIR to allow use of the subsystems.

If the <var>SYSOPT</var> parameter is set to an even value, CCASYS is not opened by <var class="product">Model 204</var> and subsystems are unavailable.
You must set the <var>SYSOPT</var> X'01' bit on all nodes that the client subsystem accesses. (For Parallel Query Option/204)</li>

<li>Specify a CCASYS DD statement for running the subsystem. </li>
</ul>

===File security===

You can add additional file security to the security provided by user privileges in the CCASYS file by:
<ul>
<li>Resetting the <var>[[OPENCTL parameter|OPENCTL]]</var> parameter</li>

<li>Entering passwords for the CCASYS file entries in the password table (CCASTAT). See [[Storing security information (CCASTAT)#Using CCASTAT|Using CCASTAT]].</li>
</ul>

===Maintaining CCASYS===

Periodically back up CCASYS. Like other <var class="product">Model 204</var> files, CCASYS can participate in recovery and transaction back out processing. 

As necessary, include [[File reorganization and table compaction|reorganizations]] in the recovery scheme, such as increasing both Table A and Table C and, sometimes, to recover a file if it is not participating in other recovery options.


Set up backup and restore jobs to handle all files at once. If need be, you can set up a separate backup job for CCASYS to run with the files. See the Rocket <var class="product">Model 204</var> installation guide for your operating system.

===Recovering CCASYS===

If CCASYS is used in a run, you can recover it with a <var>[[RESTART command|RESTART]]</var> command without resetting the <var>SYSOPT</var> parameter.

Synchronize recovery of CCASYS and Dictionary files. Dictionary subsystems and the Subsystem Management facility must be stopped to perform file maintenance.

==Activating the APSY Precompiled Procedures in Storage feature==

z/OS sites can keep precompiled procedures in storage. By removing precompiled procedures from the disk buffer pool, the buffer pool pages are available for <var class="product">Model 204</var> files or non-APSY CCATEMP pages. This can reduce disk I/O for both CCATEMP and other <var class="product">Model 204</var> files. The <var>[[APSYPAGE parameter|APSYPAGE]]</var> parameter allows APSY saved compilations to be loaded without having the pages that the compilations are saved on move through the disk buffer pool. This represents a reduced load on page flushing and the HASH LOCK and reduced CPU usage.
Note: As of Model 204 7.5, it is recommended for performance reasons that customers who have been using the <var>APSYPAGE</var> parameter <var class="term">disable the APSYPAGE feature</var> by setting <var>APSYPAGE</var> to 0. Instead of <var>APSYPAGE</var>, use the <var>RESPAGE</var> parameter for [[#APSY precompiled procedures in storage above the bar|storage above the bar]]. 

To activate the APSY Precompiled Procedures in Storage feature in a job, users must set the <var>APSYPAGE</var> parameter in the User 0 CCAIN stream. The <var>APSYPAGE</var> parameter specifies the number of virtual storage pages to allocate.
Note: While <var>APSYPAGE</var> looks very much like <var>[[TEMPPAGE parameter|TEMPPAGE]]</var>, the units are somewhat different: 
<ul>
<li><var>APSYPAGE</var> refers to 4096-byte virtual storage pages</li>

<li><var>TEMPPAGE</var> refers to 6184-byte <var class="product">Model 204</var> file pages</li>
</ul>

There are several reasons to use the <var>APSYPAGE</var> parameter instead of, or in addition to, the <var>TEMPPAGE</var> parameter:
<ul>
<li><var>APSYPAGE</var> virtual storage pages do not have to be big enough to hold all of CCATEMP or even all saved compilations. The APSY Precompiled Procedures In Storage feature uses an LRU algorithm to ensure that frequently loaded APSY procedures remain in storage, while infrequently loaded procedures tend to be loaded from CCATEMP. So, if there is not sufficient real storage to back all of CCATEMP, you might set <var>APSYPAGE</var> to save frequently loaded APSY compilations in real storage. </li>

<li>The path length for retrieving a page out of storage is significantly lower than for retrieving one out of the disk buffer pool, especially in an MP/204 environment.</li>

<li>When <var>APSYPAGE</var> is set, the large <var class="product">Model 204</var> server tables are (hardware) page-aligned as are the saved compilations. This makes it possible to use the hardware MVPG (MoVe PaGe) facility to move pages into a server during an APSY load. On some processors, specialized hardware makes the facility significantly faster than byte-oriented data movement.</li>
</ul>

===Storage improvements for APSY subsystem saved precompilation===

If not otherwise set, <var>[[DSPOPT parameter|DSPOPT]]</var> defaults to X'00'. When a saved compilation page is moved to the <var>APSYPAGE</var> area, it is no longer also kept in CCATEMP, which eliminates duplicate storage. 

This is particularly useful when you keep CCATEMP in memory, using the <var>TEMPPAGE</var> parameter. This reduces in-memory CCATEMP storage requirements by approximately (<code>N/1.50</code>), where <code>N</code> is the number of 4K-byte pages of <var>APSYPAGE</var> that are used. In memory CCATEMP size is defined by the <var>TEMPPAGE</var> parameter.

Setting the <var>DSPOPT</var> X'80' bit and setting <var>TEMPPAGE</var> greater than zero causes saved compilations to be saved in both CCATEMP and <var>APSYPAGE</var>. Although this is wasteful of storage, it does not cause problems. If you set both parameters, you may see a higher use of CCATEMP in storage.

Setting <var>APSYPAGE</var> greater than zero causes APSY subsystem precompiled pages to be saved in storage. If <var>TEMPPAGE</var> is also set to 0, your CCATEMP is kept on disk and all saved compilations are stored in both locations. In-memory APSYPAGE storage can still be reduced if <var>DSPOPT</var> is set to include the X'80' bit. With both those settings, <var class="product">Model 204</var> employs the least recently used (LRU) algorithm to keep the more heavily used saved compilations in memory while the less recently used saved compilations migrate to disk.

===Storage requirements===

The CCASERVR, CCATEMP, and APSY Precompiled Procedures in Storage features may cause operating system paging. Performance degradation is likely, if real storage frames are insufficient, or expanded storage frames in hiperspaces are used to hold the data saved in this storage. The <var>[[MONITOR DATASPACE command|MONITOR DATASPACE]]</var> command can provide some information about the storage usage of these features. 

===Setting the DSPOPT parameter===

If the APSY precompiled procedures in storage feature is used, or CCASERVR In Storage is used with page-oriented data movement (<var>[[DSPOPT parameter|DSPOPT]]</var> X'01' set), then certain large server tables and servers themselves are page-aligned. This might require up to five extra hardware pages of real and virtual storage per server, although more typically it requires about three extra pages or 12K bytes per server. 

If <var>[[NSERVS parameter|NSERVS]]</var> is set to 40 and <var>APSYPAGE</var> is set to a nonzero value, or CCASERVR is kept in storage with <var>DSPOPT</var> X'01' set, enough real storage frames should be available to hold up to an extra 200 pages or 800K of server data. 

The setting of the <var>DSPOPT</var> parameter depends on your installation: 
<ul>
<li>If your site has enough expanded storage, you might use it for CCASERVR in Storage and APSY Precompiled Procedures in Storage in a cache hiperspace (<code>DSPOPT=X'43'</code>). </li>

<li>If this decision causes a large number of CCATEMP reads because z/OS steals a lot of pages from the cache hyperspace, then use <code>DSPOPT=X'23'</code> (no cache hyperspace). </li>

<li>If there is an excessive paging, eliminate one or both In Storage features. </li>

<li>If your installation is z/OS, 64-bit real-storage, do not use any hyperspaces options, but use dataspaces instead. </li>
</ul>

Users with limited resources should try and test for what feature is the most effective.

In addition, enough real storage should be available to hold the APSY precompiled procedures and/or CCASERVR data in real or expanded storage.

===APSY load statistics===

There are three system statistics associated with APSY loads. These statistics are intended to: 
<ul>
<li>Assist in the proper setting of the <var>APSYPAGE</var> and <var>RESLTHR</var> parameters.</li>

<li>Determine the ratio of requests using precompiled and non-precompiled requests, the percentage of requests which are precompiled being the ratio of APSYLD to REQ. </li>
</ul>

The APSY load statistics are:
<table>
<tr class="head">
<th>Statistic </th>
<th>Tracks the number of APSY loads...</th>
</tr>

<tr>
<td>APSYLD </td>
<td>Including internal CCASYS procedures that are run as part of APSY processing.</td>
</tr>

<tr>
<td>APSYLDD </td>
<td>From a dataspace.

This statistic is zero unless the APSYPAGE parameter is set. This parameter can be compared with APSYLD and APSYLDT to determine the percentage of eligible APSY loads that are being performed from a dataspace.</td>
</tr>

<tr>
<td>APSYLDT </td>
<td>That are tiny.

All APSY loads, even those done from dataspaces, read a certain amount of control information from CCATEMP. Immediately following this control information is data that is loaded into NTBL, QTBL, STBL, and VTBL. If this table data does not extend to an extra CCATEMP page beyond the control information, the APSY load is counted as a tiny load. 

This statistic is maintained because tiny APSY loads are not worth saving in dataspaces, so it must be considered when comparing APSYLDD with APSYLD in determining which percentage of pre-compiled procedures are being loaded from dataspaces.</td>
</tr>
</table>

===APSY precompiled procedures in storage above the bar===
You can store APSY precompiled procedures above the bar by using the <var>[[RESPAGE parameter|RESPAGE]]</var> parameter to specify a number of 4K operating system pages. See [[Defining_the_runtime_environment_(CCAIN)#ATB_storage_for_APSY_precompiled_procedures|ATB storage for APSY precompiled procedures]] for details.

==Parallel Query Option/204 and scattered subsystems==

Whenever you log in to a service subsystem, you must reset the <var>[[LGTBL parameter|LGTBL]]</var> parameter on the service thread to at least 288. This sets the size of the global variable table (GTBL). GTBL contains name/value strings for global variables and is used by procedures that are included by APSY to support subsystem processing. 

The subsystem designer will have to place the <var>UTABLE</var> command into the LOGIN procedure, if <var>LGTBL</var> is insufficient before entering the subsystem.

==Overview of the Subsystem Management facility==

The Subsystem Management facility (SUBSYSMGMT) is a full-screen <var class="product">Model 204</var> Dictionary interface. It is used as a tool to define user-written applications that run under the Application Subsystem facility (APSY). 

Subsystem characteristics and components are defined by means of a series of screens and stored in the CCASYS file. Data in the CCASYS file is used by the application subsystem to control the processing required by the subsystem. <var class="product">Model 204</var> Dictionary entries are maintained for the operational parameters, procedure specifications, and subsystem files. The Subsystem Management facility makes SOUL applications easier to use, easier to maintain, and more efficient. 

The following sections provide an overview of subsystem processing and explains how to use the SUBSYSMGMT interface to define a subsystem, establish user privileges, and migrate subsystem definitions from one <var class="product">Model 204</var> environment to another.

For more information on subsystems, requirements, and options, refer to: 
<ul>
<li>[[Dictionary/204 installation guide]] and [[Dictionary/204 operation and file maintenance]], which discuss the installation and preparation of CCASYS, D204SYS, and Dictionary files</li>

<li>[[Dictionary/204 entity type definitions#SUBSYSTEM|SUBSYSTEM]], which describes the dictionary entries relating to subsystems</li>

<li>[[PQO: Overview of Parallel Query Option/204]], which describes a <var class="product">Model 204</var> distributed processing facility</li>

<li>[[Application Subsystem development]], which gives detailed instructions for designing, developing, and debugging a subsystem</li>
</ul>

==Components of a subsystem==

A subsystem is an application consisting of a collection of procedures, files, and assigned characteristics that are defined as a subsystem to <var class="product">Model 204</var> through the <var class="product">Model 204</var> Dictionary interface, SUBSYSMGMT.

The collection of procedures that make up a subsystem perform system startup, login processing, main processing, disconnect processing, and error-handling tasks. 

Control is passed from procedure to procedure by setting a defined communications global variable in each procedure. The communications global variable contains the name of the next procedure to be executed. Detailed information about subsystem design and procedure development is given in [[Application Subsystem development]].

Assigned characteristics of a subsystem include security and system operation options, such as locking files and groups for subsystem use, automatic login and logout, automatic COMMIT for outstanding updates, message displays, and the response of the subsystem when files are unavailable.

The members of an APSY subsystem are files and permanent groups. With <var class="product">PQO</var>, members can be either automatic or manual: 
<ul>
<li>An automatic member is a subsystem group or file that is opened automatically when the subsystem is started or when a user enters the subsystem. </li>

<li>A manual member is a group or file that must be opened explicitly by the <var>OPEN</var> or <var>OPENC</var> command. </li>
</ul>

Members can also be either mandatory or optional:
<ul>
<li>A mandatory member must be open in order to access a subsystem. Mandatory members cannot be manual. </li>

<li>An optional member is not required for subsystem access (start and login processing can succeed without it). </li>
</ul>

At any given time, a member can be open or closed to a subsystem or to a user within a subsystem. The following sections explain the conditions under which the different kinds of members are accessible to APSY subsystems and their users.

==File and group availability==

===Member availability to APSY subsystems===

Automatic members of APSY subsystems are always opened by the <var>START SUBSYSTEM</var> command or by SUBSYSTEM LOGIN. At the end of <var>START</var> processing, each automatic member is open unless either the <var>START</var> or <var>OPEN</var> failed. 

Manual members of APSY subsystems are in the closed state at the completion of <var>START SUBSYSTEM</var> processing and must be explicitly opened by the user. Manual members become open to the subsystem if an OPEN operation succeeds. If <var>OPEN</var> fails due to node unavailability or for user-specific reasons (for example, if the user's line goes down), the member remains closed to the subsystem.
<ul>
<li>If a node becomes unavailable to a subsystem, all automatic subsystem members and all open manual subsystem members residing on the unavailable node are marked disabled.</li>

<li>If a <var>STOP FILE</var> (or <var>STOP GROUP</var>) command is issued for a manual member on the client subsystem's node, the member is closed to the client subsystem when the last user closes it. </li>

<li>If the member is located on the service subsystem node, the file is closed to the service subsystem when either the <var>STOP</var> is complete or the last user closes the file.</li>
</ul>

===Member availability to subsystem users===

When a user enters a subsystem, automatic subsystem members are opened.

If a user <var>LOGIN</var> or <var>OPEN</var> operation fails for an optional member, the member is left closed for the user but remains open to the subsystem. If a mandatory member cannot be opened, the user is denied access to the subsystem.

If a user <var>LOGIN</var> or <var>OPEN</var> operation fails for an already open member, the member is left disabled for the user, but remains open to the subsystem. 

If an automatic mandatory member is closed to the subsystem, new users are not allowed to enter the subsystem.

Manual members of APSY subsystems are closed for a user within a subsystem until the user issues an <var>OPEN</var> command or statement. In this case, it does not matter whether the member is open or closed to the subsystem.

If compilation and/or loading of a request fails due to a communications failure, previously opened members on the failing node become disabled to the user. A user can close optional members at any time by issuing the <var>CLOSE</var> command.

===Enabling a disabled subsystem file===

If a file is marked as disabled to the subsystem, you can use the <var>ENABLE SUBSYSTEM FILE</var> command to make the file available again. If necessary, correct any communications problem. Then enter this command:

ENABLE SUBSYSTEM subsysname [FILE | GROUP] name AT location

Where:
<ul>
<li><var class="term">subsysname </var>is the name of the client subsystem.</li>

<li><var class="term">name</var> specifies the file or group that supports <var class="term">subsysname</var>.</li>

<li><var class="term">location</var> is the value of the client CCAIN LOCATION parameter (which is also the value of the CLNT field in the <var>[[LOGWHO command|LOGWHO]]</var> command output).</li>
</ul>

You must specify the location; you cannot include local files in an <var>ENABLE SUBSYSTEM</var> command.

===Disabling a subsystem file===

You can disable a subsystem file to keep the file itself, or the subsystem to which it belongs, inaccessible for a short period of time, without shutting down the subsystem by using the <var>DISABLE SUBSYSTEM</var> command.

To disable a subsystem file, use this command:

DISABLE <var>SUBSYS</var>TEM subsysname [FILE | GROUP] name AT location

Where:
<ul>
<li><var class="term">subsysname </var>is the name of the client subsystem. </li>

<li><var class="term">name</var> specifies the file or group that supports <var class="term">subsysname</var>.</li>

<li><var class="term">location</var> is the value of the client CCAIN LOCATION parameter (which is also the value of the CLNT field in the <var>LOGWHO</var> command output).</li>
</ul>

The consequence of disabling a subsystem file depends on whether the file is an optional or mandatory group member: 
<ul>
<li>If you disable a mandatory file, you effectively disable the subsystem, because users attempting to access the disabled file cannot access the subsystem. </li>

<li>If you disable an optional file, users can log in to the subsystem, but cannot access the disabled file. </li>
</ul>

==Application subsystem processing==

Subsystem processing includes startup, login processing, locating, compiling and/or loading procedures (main or driver processing), disconnect processing, and error processing. User-written procedures are required for each processing step.

For startup and processing considerations specific to scattered subsystems, see [[PQO: Scattered APSY subsystems#Subsystem command processing|PQO subsystem command processing]]. 

===Subsystem startup===

To start the subsystem, either issue the <var>[[START command: Starting an application subsystem|START]]</var> command. Or, optionally, the first user starts the subsystem automatically, if the Auto Start option is in effect. During subsystem startup, <var class="product">Model 204</var> performs the following tasks:
<ol>
<li>Finds the subsystem definition stored in CCASYS.</li>
<li>Builds an in-core subsystem definition control block.

For z/OS operating systems, application subsystem control blocks reside above the 16-megabyte line.</li>

<li>Opens all required files and groups.</li>

<li>Scans the procedure file for locked members that have precompiled procedure prefixes (see [[#Procedure Specifications screen|Procedure Specifications screen]]).</li>

<li>Enters an entry for each precompiled procedure in the in-core procedure dictionary.
Note:
The maximum size of the in-core procedure dictionary is 16 megabytes.</li>

<li>Adds the subsystem name to the list of active subsystems, if no error occurs.</li>

<li>Performs a user-written initialization procedure (optional).</li>

<li>Closes all associated files and groups, unless the Auto Start option is in effect. </li>
</ol>

===Login processing===

Each time the subsystem is invoked, <var class="product">Model 204</var> automatically performs the following steps:
<ol>
<li>Searches CCASYS for the user's class definition that assigns user privileges.

The subsystem invocation is rejected if privileges consistent with the subsystem invoked are not found. </li>

<li>Logs the user in to <var class="product">Model 204</var> with the subsystem name as the user, account, and record security ID, if the automatic login option (see [[#Operational Parameters screen|Operational Parameters screen]]) is set in the subsystem definition.

If the automatic login option is not set, the user's <var class="product">Model 204</var> ID is retained.</li>

<li>Opens required subsystem files and groups with the found privileges.</li>

<li>Executes the commands and requests, as specified by the login procedure programmed by the user. The login procedure might consist of:
<ul>
<li>Storing current server table sizes in the global variable table for later reference</li>
<li>Issuing UTABLE commands to set compiler table sizes for subsystem use</li>
<li>Setting the communications global variable to the name of the procedure that displays the initial menu </li>
</ul></li>

<li>Begins main processing as long as the login procedure specifies the next procedure to include in the communications global variable. </li>
</ol>

===Main processing===

Main processing consists of locating subsystem eligible procedures, compiling procedures (if necessary), and loading procedures until an exit value is encountered. You can have as many main processing procedures as necessary. 

Procedure names are stored in the in-core procedure dictionary that is built during system startup. Procedures are retrieved by examining the communications global variable for the name of the procedure and then locating the procedure name in the in-core dictionary.

If the procedure name is not found, the subsystem error procedure is executed. If the procedure is not found and no error procedure is specified in the subsystem definition, the user is disconnected from the subsystem.

If the procedure name is found, <var class="product">Model 204</var> checks to see if the procedure has been precompiled:
<ul>
<li>If the procedure is not a precompilable procedure, <var class="product">Model 204</var> includes it for compilation and evaluation. Compilation and evaluation are reported in the audit trail under the CMPL and EVAL since-last statistics.</li>

<li>If the procedure is a precompilable procedure, <var class="product">Model 204</var> checks to see if the procedure was previously compiled with the set of privileges defined for the user's subsystem class.</li>

<li>If the procedure is precompiled for the user's privilege set, <var class="product">Model 204</var> loads the contents of the compiler tables from CCATEMP and evaluates the request. Loading and evaluation are reported in the audit trail as LOAD and EVAL since-last statistics.</li>

<li>If the procedure is not precompiled, <var class="product">Model 204</var> includes the procedure for compilation and evaluation. Contents of compiler tables are saved in CCATEMP, if the compile is successful and the tables are not already saved for another user class.</li>

<li>If the procedure is already precompiled for some other privilege set, <var class="product">Model 204</var> validates whether this user's privilege set is authorized to compile and validate. If successful, the request is loaded and then evaluated. If unsuccessful (for example, if the privilege set fails), the error procedure is executed.
</li>
</ul>

Main processing continues until the value of the communications global variable is set to the exit value specified in the subsystem definition. Once the exit value is set, <var class="product">Model 204</var> proceeds to disconnect processing.
Warning: Rocket advises that when using an <var>INCLUDE</var> statement in a precompiled procedure that the included procedure is the same for all users. Unpredictable results may occur if the procedure is different when compiling for different [[SCLASS]]es.

===Requirements for using temporary groups===

If a precompiled procedure includes an <var>OPEN</var> of a temporary group, an attempt to load that procedure fails (with the <code>GRP NOT OPEN</code> error) if the procedure contains an unreferenced list in the context of that group. An unreferenced list is a list that is declared but not referred to and, therefore, its declaration is not evaluated. 

To avoid an error in this situation, make sure of the following: 
<ul>
<li>Any temporary group in this situation must be open at the time of the load.</li>

<li>Such a temporary group must be a TBO group if the procedure accesses a TBO file for update.</li>
</ul>

===Disconnect processing===

Disconnect processing is invoked when one of the following conditions occurs: 
<ul>
<li>Communications global variable is set to the exit value.</li>

<li>Error occurs with no subsystem error procedure defined.</li>

<li>User is restarted by <var class="product">Model 204</var>.</li>

<li>Logout or disconnect commands are issued from a subsystem procedure. </li>
</ul>

All open subsystem files and groups are closed for the user during disconnect processing. If the subsystem definition includes the automatic logout option (Log User out of M204 on the Operational Parameters screen), the user is logged out of <var class="product">Model 204</var>.

If the subsystem definition includes the automatic login option (Log User in to M204) but not the automatic logout option (Log User out of M204), the user is exited out of the subsystem, logged in again under the original <var class="product">Model 204</var> ID (if previously logged in), and returned to <var class="product">Model 204</var> command level.

===Error processing===

Error processing, an optional procedure, is invoked when an error occurs that cannot be handled by the procedure executing at the time. 

====Recoverable errors====

A subsystem can recover from most errors when an error procedure is used. Recoverable errors include:
<ul>
<li>Compilation errors</li>

<li>Record locking or table-full errors</li>

<li>Attention interrupts and *CANCEL if no ON ATTENTION unit is specified in the application
</li>
</ul>

An error procedure must test for different error conditions. The resulting value stored in the error global variable helps the application programmer determine the type of error that occurred.

====Considerations for the communications global variable====

The communications global variable is ignored and disconnect processing completed when one of the following conditions occurs:
<ul>
<li>Error is a soft restart, a hard restart, or a phone hang-up condition.

If you attempt to set the communications global variable to the name of another procedure, the procedure is not executed.</li>

<li>No error procedure is specified in the subsystem definition. </li>
</ul>

==Subsystem operating requirements==

Meet the following requirements to define and execute a subsystem:
<ul>
<li>Install CCASYS, the <var class="product">Model 204</var> Dictionary, and the subsystem interface SUBSYSMGMT</li>

<li>Allocate sufficient space for subsystem use in the resource locking table, server tables, CCATEMP, and spare core (SPCORE) </li>
</ul>

===Required files===

Dictionary/204, with the files shown in the table below, must be installed to define a subsystem; see the [[Dictionary/204 installation guide]]. Dictionary entries pertaining to subsystems are for reference purposes only. The subsystem is executed by using the data stored in CCASYS.
<table>
<caption>Dictionary/204 files required for subsystem management</caption>
<tr class="head">
<th>File</th>
<th>Description</th>
</tr>

<tr>
<td>CCASYS</td>
<td>Subsystem definition</td>
</tr>

<tr>
<td>D204SYS</td>
<td>Migrating definitions</td>
</tr>

<tr>
<td>DATALINK</td>
<td>Dictionary file</td>
</tr>

<tr>
<td>M204PROC</td>
<td>Procedure file</td>
</tr>

<tr>
<td>M204TEMP</td>
<td>Internal work file</td>
</tr>

<tr>
<td>METADATA</td>
<td>Dictionary file</td>
</tr>
</table>

===Resource locking table space===

<var class="product">Model 204</var> locks in share mode on subsystem procedure names or permanent group names. Locking ensures that the procedures or group definitions do not change while the subsystem is running and prevents any user from issuing the <var>PROCEDURE</var>, <var>DELETE PROCEDURE</var>, or <var>RENAME PROCEDURE</var> commands. Procedures cannot be updated with the editor while the subsystem is active. 

Separate locks are not required if the subsystem definition specifies locked files during processing.

Additional space might be required in the resource-locking table for running a subsystem with groups defined or files unlocked. Use the following formula as a guide:
Number of additional resource-locking entries =
Number of groups + number of procedures (if files are unlocked)


where additional resources include:
<ul>
<li>Seven additional entries for application subsystem procedures in CCASYS</li>

<li>One additional entry for each subsystem and permanent group</li>

<li>One additional entry for each subsystem procedure if LOCK FILE (or GROUP) options are chosen </li>
</ul>

===Minimum server table sizes===

Minimum server table lengths, exclusive of any application procedures, for all users invoking subsystems are:
<ul>
<li>LGTBL = 288</li>

<li>LNTBL = 50</li>

<li>LQTBL = 120</li>

<li>LSTBL = 250</li>

<li>LVTBL = 256 </li>
</ul>

During application programming, you must determine actual table lengths for specific procedures. Make adjustments to table lengths in the login procedure to ensure successful execution.

===CCATEMP space===

CCATEMP requires additional space to accommodate the compiler tables for precompiled procedures. The data stored in CCATEMP consists of a header section and the contents of GTBL, NTBL, QTBL, STBL, and VTBL.

Use the following calculation to determine the additional CCATEMP space required for one precompiled request:
94 + (32 * VTBL HWM) + (12 * NTBL HWM) + (STBL HWM)
+ NFILES + NRMTFILE + (16 * QTBL HWM)
+ (ad hoc group FTBL space)
+ ((30 + (7 + NRMTLOCS)/8) * #groups)
+ (8 * (#fields referenced in group))
+ (the sum of the length of the names of all the fields referenced in the group)
+ #screens + #images
+ (unavailable-file space) + (XVAR space)


where: 
<ul>
<li><code>HWM</code> refers to the highwater mark found in the audit trail's since-last compilation statistic for the indicated table.</li>

<li><code>ad hoc group FTBL space</code> depends on whether ad hoc scattered groups (PQO) are included. If no ad hoc groups are scattered, ad hoc group FTBL space is:
62 * (#ad hoc groups)


If some ad hoc groups are scattered, ad hoc group FTBL space is:
(62 + (#open files in ad hoc groups)) * (#ad hoc groups)
</li>

<li><code>unavailable-file space</code> is the following quantity, not knowable in advance, which you need to estimate (PQO only):
(4 + (#unavailable group files)) * (#groups with unavailable members)
</li>

<li><code>XVAR space</code> is required for these SOUL request elements: found sets, lists, and <var>FOR</var> statements with a <var>WHERE</var> clause. The number of bytes per element depends on the file or group context, as follows:
<table>
<tr class="head">
<th>Transaction context </th>
<th>Bytes required per element</th>
</tr>

<tr>
<td>Single file</td>
<td align="right">8</td>
</tr>

<tr>
<td>Ad hoc or permanent group</td>
<td>8 * (#files in group) </td>
</tr>

<tr>
<td>Temporary group</td>
<td>4 + (8 * (#files in group))</td>
</tr>
</table>
</li>
</ul>

The number of additional CCATEMP pages required is:
The result of the above calculation / (PAGESZ - 40)


===SPCORE size===

Control blocks are allocated from spare core for use by active subsystems. Use the following calculation to determine the number of bytes required for one subsystem. The calculation includes PQO remote file subsystem members:
228 + NRMTFILE + NFILES + (40 * SCLASSes) + NRMTLOCS
+ (93 * filemembers)
+ ((36 + (7 + SCLASSes) / 8) * (procedures + 1))
+ 40 bytes for each stopped file or group


Where: 
<ul>
<li><var>NRMTFILE</var> and <var>NRMTLOCS</var> are CCAIN parameters that apply to Parallel Query Option/204.</li>

<li><code>filemembers</code> are the files that belong to the subsystem. </li>

<li><code>SCLASSes</code> is the number of subsystem user privilege classes.</li>

<li><code>procedures</code> is the number of precompiled procedures used by the subsystem.
</li>

<li><code>40 bytes for each stopped file or group</code> is the number of bytes returned to spare core if the subsystem is stopped or the file or group is started.</li>
</ul>

==Subsystem operating options==

Subsystem operating options consist of commands entered on the command line, the <var>[[AUTOSYS parameter|AUTOSYS]]</var> parameter entered on user lines in CCAIN, and values entered on screens provided by the Application Subsystem. Options can be entered on the command line only if the subsystem is already started or if the subsystem is defined with the Auto Start option. A summary of the available options is given in the following table.

More detailed information about the operating options follows the table.
Options entered through interface screens are discussed throughout this article.
<table>
<caption>Summary of subsystem operating options</caption>
<tr class="head">
<th>Option</th>
<th>Method of entry</th>
<th>Purpose</th>
</tr>

<tr>
<td>Auto Commit</td>
<td nowrap>Operational Parm screen</td>
<td>Controls automatic <var>COMMIT</var>s at the <var>END</var> of each procedure</td>
</tr>

<tr>
<td>Auto Start</td>
<td>Operational Parm screen</td>
<td>Automatically starts the subsystem when the first user logs in</td>
</tr>

<tr>
<td>Automatic Login (Log user in...) </td>
<td>Operational Parm screen</td>
<td>Logs the user in to the subsystem with an account value of the subsystem name</td>
</tr>

<tr>
<td>Automatic Logout (Log user out...)</td>
<td>Operational Parm screen</td>
<td>Controls user logout from <var class="product">Model 204</var></td>
</tr>

<tr>
<td>AUTOSYS</td>
<td>CCAIN user line</td>
<td>Invokes the specified subsystem for individual users upon <var class="product">Model 204</var> login</td>
</tr>

<tr>
<td colspan="3">Commands</td>
</tr>

<tr>
<td>DEBUG SUBSYSTEM</td>
<td>Command line</td>
<td>Allows the user issuing the command to change subsystem procedures without stopping and restarting the subsystem</td>
</tr>

<tr>
<td nowrap>DISABLE SUBSYSTEM FILE</td>
<td>Command line</td>
<td>Makes a file or subsystem temporarily inaccessible</td>
</tr>

<tr>
<td>ENABLE SUBSYSTEM FILE </td>
<td>Command line</td>
<td>Makes a file available again after being disabled</td>
</tr>

<tr>
<td>START FILE</td>
<td>Command line</td>
<td>Allows a file to be opened and removes the stop flag (if any)</td>
</tr>

<tr>
<td>START SUBSYSTEM</td>
<td>Command line</td>
<td>Activates the subsystem, opens files, and performs subsystem startup</td>
</tr>

<tr>
<td>STOP FILE</td>
<td>Command line</td>
<td>Prevents opening a specified file or permanent group</td>
</tr>

<tr>
<td>STOP SUBSYSTEM</td>
<td>Command line</td>
<td>Stops the subsystem</td>
</tr>

<tr>
<td>TEST</td>
<td>Command line</td>
<td>Creates a single user test environment</td>
</tr>

<tr>
<td>File/Group</td>
<td>Command line</td>
<td>Specifies the name and attributes of
files and groups used by the subsystem</td>
</tr>

<tr>
<td colspan="3">Global variables</td>
</tr>

<tr>
<td>Communication</td>
<td>Procedure Spec screen</td>
<td>Specifies the variable name of the next procedure to be executed</td>
</tr>

<tr>
<td>Exit Value</td>
<td>Procedure Spec screen</td>
<td>Specifies the communication variable setting for exiting the subsystem</td>
</tr>

<tr>
<td>Error Variable</td>
<td>Procedure Spec screen</td>
<td>Names the variable containing the error code</td>
</tr>

<tr>
<td>Iterations</td>
<td>Operational Parm screen</td>
<td>Specifies the maximum number of times a procedure can execute consecutively</td>
</tr>

<tr>
<td>Lock File/Groups</td>
<td>Operational Parm screen</td>
<td>Controls outside user access to subsystem files when the subsystem is active</td>
</tr>

<tr>
<td colspan="3">Message display</td>
</tr>

<tr>
<td>Disconnect</td>
<td>Operational Parm screen</td>
<td>Controls disconnect message display</td>
</tr>

<tr>
<td>Informational</td>
<td>Operational Parm screen</td>
<td>Controls the display of informational messages</td>
</tr>

<tr>
<td>Error</td>
<td>Operational Parm screen</td>
<td>Controls error message display</td>
</tr>

<tr>
<td>Numlk</td>
<td>File Use screen</td>
<td>Specifies the number of files participating in procedure locking </td>
</tr>

<tr>
<td colspan="3">Proc names </td>
</tr>

<tr>
<td>Initialization</td>
<td>Procedure Spec screen</td>
<td>Names the first procedure used upon subsystem startup</td>
</tr>

<tr>
<td>Login</td>
<td>Procedure Spec screen</td>
<td>Names the first procedure executed for each user</td>
</tr>

<tr>
<td>Error</td>
<td>Procedure Spec screen</td>
<td>Names the procedure invoked when an error occurs
</td>
</tr>

<tr>
<td colspan="3">Proc prefixes</td>
</tr>

<tr>
<td>Non-precompiled </td>
<td>Procedure Spec screen</td>
<td>Identifies the prefix used for procedures compiled each time they are invoked</td>
</tr>

<tr>
<td>Precompiled</td>
<td>Procedure Spec screen</td>
<td>Identifies the prefix used for procedures that are saved in CCATEMP for reuse</td>
</tr>

<tr>
<td>Procs</td>
<td>File Use screen</td>
<td>Names the file or group containing the subsystem procedures </td>
</tr>

<tr>
<td colspan="3">Security</td>
</tr>

<tr>
<td>Account</td>
<td>Operational Parm screen</td>
<td>Specifies an account value that overrides the login account</td>
</tr>

<tr>
<td>Account</td>
<td>Subsys Class screen</td>
<td>Specifies an account associated with a specific user class (overrides the account specified on the Operational Parameters screen)</td>
</tr>

<tr>
<td>Account</td>
<td>User Matrix screen</td>
<td>Changes an account in any subsystem user class</td>
</tr>

<tr>
<td>Command Priv.</td>
<td>Subsys Class screen </td>
<td>Specifies whether the class of users can issue the START, TEST, STOP, and DEBUG subsystem commands</td>
</tr>

<tr>
<td>File Priv.</td>
<td>Subsys Class screen </td>
<td>Specifies values for procedure, file, and field-level security parameters</td>
</tr>

<tr>
<td>Login Priv.</td>
<td>Subsys Class screen </td>
<td>Overrides privileges on entry to the subsystem and privileges specified on the Operational Parameters screen</td>
</tr>

<tr>
<td>Privileges</td>
<td>Operational Parm screen</td>
<td>Specifies user privileges independent of the <var class="product">Model 204</var> login privileges</td>
</tr>

<tr>
<td>Record Security</td>
<td>Subsys Class screen </td>
<td>Overrides the record security ID held upon entry into the subsystem</td>
</tr>

<tr>
<td>Start Login</td>
<td>Operational Parm screen</td>
<td>Controls login privileges while starting a subsystem</td>
</tr>

<tr>
<td>Status</td>
<td>Operational Parm screen</td>
<td>Specifies the level of availability of the subsystem to users</td>
</tr>

<tr>
<td>Sys Class</td>
<td>Subsys Class screen</td>
<td>Specifies the number and name of a subsystem user class that is assigned specific privileges</td>
</tr>

<tr>
<td>Subsys Class</td>
<td>Subsys Class Users screen</td>
<td>Specifies subsystem class changes for individual users</td>
</tr>

<tr>
<td>Subsys Class</td>
<td>Userdef screen</td>
<td>Identifies a group of subsystem users and specifies the command privilege level applicable to that group</td>
</tr>
</table>

===Subsystem commands===

The following list summarizes commands relating to a subsystem.

<ul>
<li><var>[[DEBUG command|DEBUG SUBSYSTEM]]</var> allows login to a specified subsystem with the <var>DEBUG</var> and <var>STATS</var> options of the <var>[[TEST command|TEST]]</var> command. Individual programmer changes to subsystem procedures can be made without stopping and restarting the subsystem. Changes are limited to the programmer issuing the <var>DEBUG SUBSYSTEM</var> command. More than one user can execute the <var>DEBUG</var> command against the same subsystem at the same time.

<var>DEBUG SUBSYSTEM</var> displays the value of the communications global variable and since-last statistics. Prompts are issued for changes to the variable.

<var>DEBUG</var> is limited to users with either <var>TEST</var> or <var>DEBUG</var> privileges. The <var>DEBUG</var> privilege does not entitle use of the <var>TEST</var> command.</li>

<li><var>[[DISABLE command|DISABLE SUBSYSTEM FILE]]</var> makes a file or the subsystem to which it belongs inaccessible for a short period of time without shutting down the subsystem by using the <var>STOP SUBSYSTEM</var> command. </li>

<li><var>[[ENABLE command|ENABLE SUBSYSTEM FILE]]</var> makes a file marked as disabled to the subsystem available again.</li>

<li><var>START FILE</var> removes the <var>OPEN</var> restriction set by the <var>STOP</var> command at the system and subsystem levels. </li>

<li><var>[[START command: Starting an application subsystem|START SUBSYSTEM]]</var> activates the subsystem and makes it available for use. <var class="product">Model 204</var> opens all the files and performs subsystem startup. </li>

<li><var>[[STOP command: Making a file or group unavailable|STOP FILE]]</var> prevents the reopening of a specified file or permanent group. Files or groups open at the time <var>STOP FILE</var> is issued are not affected until they are closed and an attempt is made to reopen them.

When the stopped file is closed by all users, all precompiled code in CCATEMP that refers to the file is discarded and pages in the temporary file are reclaimed. <var>STOP FILE</var> affects only one copy of <var class="product">Model 204</var>. Another copy of <var class="product">Model 204</var> can process the file or group. 

<var>STOP FILE</var> verifies the presence of the named file or group in any active subsystem. Files or groups not required by the subsystem become unavailable for future use.</li>

<li><var>[[STOP command: Stopping an application subsystem|STOP SUBSYSTEM]]</var> stops the subsystem and makes it unavailable for use. Files and groups are closed. Groups and procedures are released when the subsystem is completely stopped.

If <var>STOP SUBSYSTEM</var> is issued when there are active users, the system remains active until the last user disconnects (drain state).</li>

<li><var>TEST</var> creates a single user test environment. The subsystem must be stopped to enter the TEST mode and the user must have <var>TEST</var> privileges. <var>DEBUG</var> privileges are not sufficient to execute the <var>TEST</var> command.

<var>TEST</var> without the <var>DEBUG</var> option simulates execution of the subsystem. 
</li>
</ul>

===AUTOSYS parameter===

The <var>[[AUTOSYS parameter|AUTOSYS]]</var> parameter, specified on user lines in CCAIN, invokes a subsystem for individual users upon login to <var class="product">Model 204</var>. The same subsystem is generated for each subsequent user line until a different subsystem name is specified, or <var>AUTOSYS</var> is set to <code>C' '.</code> 

In the following example, all IUCV users enter the subsystem VMCFPROF whenever they log in. The AUTOSYS parameter is turned off for all other users.
IODEV=41,POLLNO=1,NOTERM=50,AUTOSYS=C'VMCFPROF'
IODEV=41,POLLNO=2
IODEV=41,POLLNO=3
.
.
.
IODEV=43,AUTOSYS=C' '
IODEV=43
IODEV=43



==Overview of the SUBSYSMGMT interface==

SUBSYSMGMT is the full-screen interface used to define user-written applications that run under the Application Subsystem facility. In addition to accessing from command line the TN3270 interface described below on this page, SUBSYSMGMT is accessible both from the [[RKTools#mainmenu|RKTools main menu]] and from the [[RKWeb#Manage|RKWeb]] browser GUI as of RKTools version 7.7. 

To issue a command from the SUBSYSMGMT screens, press the assigned PF key or enter the command on the command line (<code>===></code>). Abbreviations for commands are indicated by the uppercase portion of the command listed for PF keys. The following table describes common commands and PF keys for SUBSYSMGMT screens: 
<table>
<caption>Commands common to SUBSYSMGMT screens</caption>
<tr class="head">
<th>Command</th>
<th>PF key</th>
<th>Purpose</th>
</tr>

<tr>
<td>HELP</td>
<td>F1</td>
<td>Displays online Help text for the screen.</td>
</tr>

<tr>
<td>QUIT</td>
<td>F3</td>
<td>Terminates processing without saving screen input. QUIT returns to the previous level.</td>
</tr>

<tr>
<td>END</td>
<td>F12</td>
<td>Saves input and returns to the previous level.</td>
</tr>

<tr>
<td> </td>
<td>F11</td>
<td>Generally used to move to the next screen when adding, modifying, or browsing a subsystem. The command name depends upon the name of the screen. </td>
</tr>
</table>

Error messages are issued from all screens. Messages can be general and issued from any screen, or specific and issued from a particular screen. 

===SUBSYSMGMT facility screen summary===

The following table summarizes the SUBSYSMGMT facility screens. The screens are described in detail in the sections that follow. 
<table>
<caption>SUBSYSMGMT facility screens</caption>
<tr class="head">
<th>Screen </th>
<th>Purpose</th>
</tr>

<tr>
<td style="border-right:none">Primary screen</td>
<td style="border-left:none"> </td>
</tr>

<tr>
<td>Activity</td>
<td>Provides a menu from which to select subsystem definition activities</td>
</tr>

<tr>
<td style="border-right:none">Secondary screens</td>
<td style="border-left:none"> </td>
</tr>

<tr>
<td>Command Privileges</td>
<td>Changes the command privileges for a set of subsystems</td>
</tr>

<tr>
<td>Operational Parameters</td>
<td>Defines the subsystem operating parameters</td>
</tr>

<tr>
<td>Procedure Specifications</td>
<td>Defines subsystem procedure specifications</td>
</tr>

<tr>
<td>Subsystem File Use</td>
<td>Defines file names used by the subsystem</td>
</tr>

<tr>
<td>Subsystem Classes</td>
<td>Defines command and file privileges for each class of subsystem user</td>
</tr>

<tr>
<td>User Definitions</td>
<td>Defines the users of the subsystem when used in conjunction with the Subsystem Class User screen </td>
</tr>

<tr>
<td>Subsystem Class Users</td>
<td>Defines assignments of specific user accounts to specific user classes</td>
</tr>

<tr>
<td>User Matrix</td>
<td>Changes the definition of a single account in a user class</td>
</tr>

<tr>
<td nowrap>Subsystem Administration</td>
<td>Defines user and administrative privileges</td>
</tr>

<tr>
<td>Subsystem Trust</td>
<td>(PQO only) Views or manages trusted subsystem definitions</td>
</tr>
</table>

===Using secondary screens===

The following considerations apply to all secondary screens:
<ul>
<li>Use secondary screens in any order.</li>

<li>Use PF keys to move from screen to screen.</li>

<li>You must fill in all screens, except those for public and semi-public subsystems with only one class, to complete a subsystem definition.</li>

<li>Public and semi-public subsystems with only one class do not require the use of the User Definitions (Userdef) screen.</li>

<li>The END command (F12) stops and saves the definition when it is complete. If you use the END command with an incomplete definition, you receive a warning message. Issuing a second END command allows you to exit and you can complete the definition in another session. (Do not use an incompletely defined subsystem.) </li>
</ul>

===Sample screens and PQO===

For screens that have changed since the previous release, the sample screens shown in the following sections represent definitions for a client subsystem in a PQO application. 

PQO-specific fields are explained briefly but their use is not described in detail. Not shown here is the Subsystem Trust screen, which is specific to PQO.

For full explanations of client and server definitions in PQO applications, see [[PQO: Defining a PQO network]].

==SUBSYSMGMT Activity screen==

The Activity screen is the primary SUBSYSMGMT screen. Use it to access all SUBSYSMGMT functions.

Subsystem Activity screen
[[File:sm8-2Activity.gif|575px]] 

===Commands and options===

The F2, F4, F5, F6, F7, or F9 keys are used with Add, Modify, or Browse to specify the appropriate secondary screen. F10 invokes the PQO-specific Subsystem Trust screen. The EXPortlist option (F11) is described below in the [[#Exportlist|Exportlist]] section.

===Overview of activities===

The following options are initiated from the Activity screen and completed through the selected secondary screens:
<ul>
<li>Add a new subsystem definition</li>

<li>Modify an existing subsystem definition</li>

<li>Browse without updating an existing subsystem definition </li>
</ul>

The following options are initiated and completed from the Activity screen:
<ul>
<li>Copy an existing subsystem definition to a newly named subsystem definition</li>

<li>Rename an existing subsystem with a new, unique name</li>

<li>Delete an entire existing subsystem definition</li>

<li>Import subsystem definitions</li>

<li>Export subsystem definitions</li>

<li>Export Delete a subsystem from the D204SYS file</li>
</ul>

The ADMIN option (option 10) displays secondary screens on which the system manager can define privileges and assign and copy [[SCLASS]] membership. 

===From fields (PQO only)===

The From fields (used when defining a PQO service subsystem) specify the location of the client subsystem. If you specify a From field, you cannot leave the Subsystem Name field blank. 

The From field is prefilled on all the secondary screens and protected from input.

===Revising command privileges===

You can revise command privileges, if you have privileges to use the SUBSYSMGMT facility as well as the privileges to update the individual subsystems.

Using the main screen of the SUBSYSMGMT facility you can enter a pattern in the Subsystem Name field and select the F7 key to change the command privileges for a set of subsystems. Another screen appears where you can enter a pattern for a subsystem class along with the new command privileges for the <var>START</var>, <var>STOP</var>, <var>TEST</var>, <var>DEBUG</var>, <var>RESUME</var>, <var>SUSPEND</var>, <var>REFRESH</var> commands. You can also obtain a list of all of the subsystem classes and subsystem definitions that fit the pattern criteria.

To update the command privileges, select the 2. MODIFY option on the main menu, enter a subsystem name or pattern in the Subsystem Name field, and press F7. The COMMAND PRIVILEGES screen is displayed next. However:
<ul>
<li>If you enter a pattern in the name field, but press another function key, the pattern is treated as an individual name, not a pattern. F7 is only valid with the MODIFY option. </li>

<li>If F7 is pressed, but the MODIFY option was not specified, then the following error message is displayed:
SUMnnn: PFkey or command only valid with Modify option.
</li>

<li>If Subsystem Name is left blank, the following error message is displayed:
SUMnnn: Subsystem name or pattern is required.
</li>
</ul>

==SUBSYSMGMT Command Privileges screen==

The subsystem management command privileges screen is shown below:

Subsystem COMMAND PRIVILEGES screen
[[File:sm8-3CmdPriv.gif|532px]] 


After your screen entries are read, a list of subsystem names and subsystem classes based on the pattern criteria is displayed. The pattern criteria used for the subsystem name is the value that was specified on the main screen. The pattern criteria for the subsystem class defaults to asterisk (<tt>*</tt>) when the screen is initially read.

If any of the subsystems in the list are enqueued by other users then the command privileges for the subsystem cannot be updated. In this case, 6=DISplay appears on the screen to display the list of subsystems that are enqueued.

Choosing other classes or names

To refine the list of subsystem classes or subsystem names, enter a new pattern in the Subsystem Name or Subsystem Class field, and press F4 to view the new list.

The maximum number of subsystem classes that may be processed at one time is 1000. If the list exceeds 1000, then the following error message is displayed:
SUM096: Refine criteria: # of subsystems classes, exceeds max(1000).


===Entering changes in the COMMAND PRIVILEGES screen===

To update the command privileges for a particular subsystem class, the command privilege must be set to <code>Y</code> or <code>N</code> in one or more of the subsystem command privilege fields. In addition, the subsystem class must be selected by putting an <code>X</code> in front of the subsystem name and the class name. You can also update more than one subsystem class at a time by specifying a command privilege of one of the Change all selected columns. If the subsystem name and class are not selected, the command privileges are not updated for that particular subsystem class. 

At this point, you press F11 (UPDate priv or F12 (END) to update the command privileges for the entire set of selected subsystem classes. If a record enqueuing conflict occurs during the update process, only a partial update can be performed. If this occurs, you can press F6 (DISplay) to display the list of subsystem classes that are enqueued and cannot be updated at this time. You also can press F11 (UPDate) or F12 (END) a second time to apply the partial update, or press F3 (QUIt) to not apply the update.

Command privileges are in effect immediately after they are updated and can be changed if the subsystem is active or not.

You may also deselect particular subsystems or classes on the list by deleting the <code>X</code> that precedes the subsystem or class name. 

The following table displays the list of PF key options and commands that are alternatives that accomplish the same thing. (Commands are used with the Enter key.) Each PF key function can also be performed by adding 12 to that PF key's number and using the resulting PF key. Commands shown may be abbreviated to the first three characters, which are capitalized.

<table>
<caption>PF keys</caption>

<tr class="head">
<th>PF Key </th>
<th>Command</th>
<th>Purpose</th>
</tr>

<tr>
<td align="right">1 </td>
<td>HELp</td>
<td>Display Help information on this screen</td>
</tr>

<tr>
<td align="right">3 </td>
<td>QUIt</td>
<td>Exit from Command Privileges Screen, return to main menu for SUBSYSMGMT.</td>
</tr>

<tr>
<td align="right">4 </td>
<td>LISt</td>
<td>Displays a list of subsystems and classes based on the pattern specification in the Subsystem name and Class fields.</td>
</tr>

<tr>
<td align="right">5 </td>
<td nowrap>DESelect all 
SELect all</td>
<td>De-select all subsystem names on the list. 
Select all subsystem names on the list.

Toggles between DESelect and SELect. 
</td>
</tr>

<tr>
<td align="right">6 </td>
<td>DISplay</td>
<td>Displays a list of subsystems or classes that are enqueued by another user. The command privileges for the subsystems and classes on the list cannot be updated at this time.</td>
</tr>

<tr>
<td align="right">7 </td>
<td>BACkward</td>
<td>Scroll up on subsystem names list.</td>
</tr>

<tr>
<td align="right">8 </td>
<td>FORward</td>
<td>Scroll down on subsystem names list.</td>
</tr>

<tr>
<td align="right">11</td>
<td>UPDate</td>
<td>Update all subsystem classes with new command privilege. Only the command privileges that are changed are updated.</td>
</tr>

<tr>
<td align="right">12</td>
<td>END</td>
<td>Return to the main menu after updating the command privileges that are specified. If a particular command privilege is left blank then it is not updated.</td>
</tr>
</table>

Command privileges can be changed regardless of whether a subsystem is active or not. The new privileges are in effect immediately once they are changed.

==Operational Parameters screen==

Selecting F4 from the Activity screen brings up the Operational Parameters screen. Use it to specify the operating parameters of the subsystem. You access the [[RKWeb#Operational|RKWeb version of this screen]] by selecting <code>Manage > Subsystem Management > Operational</code>. 

On this screen, only system managers can modify Account, Privileges, and Start Login privileges fields.

Operational Parameters screen
[[File:Sm8-4OperParm.gif|561px]] 

===Commands===
<ul>
<li>F2, F6, F9 and F11 validate and save input and display other secondary screens. You must use a PF key to quit, save the input, or move to a different screen.</li>

<li>Pressing the Enter key validates screen input.</li>
</ul>

A description of each parameter follows.

===Parameter descriptions===
<ul>
<li>Status (1, 2, and 3) determines access availability:
<ul>
<li>PUBLIC (default) allows any user to access the subsystem.</li>

<li>SEMI-PUBLIC allows all users to access the subsystem, but permits different privileges for each class of users.

A semi-public subsystem generally has more than one user class. One class is designated as the default (see the [[#Subsystem Classes screen|Subsystem Classes screen]]).</li>

<li>PRIVATE requires all users to have an assigned class. No default is allowed.</li>
</ul></li>

<li>Auto Start automatically starts the subsystem when the first user enters the subsystem name. The <var>START</var> command is not required.

If <code>N</code> (the default) is specified, only a user having the appropriate privileges, as defined on the Subsystem Classes screen, can issue the <var>START</var> command to open the subsystem. 
</li>

<li>Lock File/Groups provides control for file access to users outside the subsystem.

If <code>Y</code> is specified, the subsystem files and groups are available only to users running in the subsystem after the subsystem is started.

A subsystem file can be opened by a non-subsystem user if the subsystem is not started. If any user has the file open when the subsystem is being started, the subsystem start fails.

If a group is defined, all member files of the group are locked. No explicit lock is held on the group.

If <code>N</code> (default) is specified, users outside the subsystem can open any subsystem file, but cannot <var>DELETE</var>, <var>RENAME</var>, or <var>REDEFINE</var> fields. </li>

<li>Log user into M204 controls the method of logging the user in to <var class="product">Model 204</var>.

If <code>Y</code> is specified, the user is logged out of <var class="product">Model 204</var> and then logged back in to <var class="product">Model 204</var> with the subsystem name as the user ID when entering the system.

If <code>N</code> (default) is specified, the user remains logged in under the same <var class="product">Model 204</var> account name used before subsystem processing. 
</li>

<li>Log user out of M204 controls the method of logging the user out of <var class="product">Model 204</var>.

If <code>Y</code> is specified, the user is logged out of <var class="product">Model 204</var> upon leaving the subsystem. 

If <code>N</code> (default) is specified and Log user into M204 is <code>Y</code>, the user's logon, account, and record security ID are restored to the values that were present before entering the subsystem.
</li>

<li>Auto Commit controls the issuing of <var>COMMIT</var> statements:
<ul>
<li>If <code>Y</code> (default) is specified, a SOUL <var>COMMIT</var> statement is executed by <var class="product">Model 204</var> at each procedure <var>END</var> in the subsystem during execution.</li>

<li>If <code>N</code> is specified, transactions can span request boundaries (see [[System and media recovery#Transaction boundaries|Transaction boundaries]]). The application must issue <var>COMMIT</var> statements to commit updates to the database. </li>
</ul></li>

<li>Maximum Iterations specifies the maximum number of consecutive times the subsystem allows the same procedure to be invoked before interrupting the processing. Valid values are 1 to 99999. <code>NULL</code> (default) indicates no limit. </li>

<li>Account (optional) specifies an account value other than that used at logon. As many as 10 characters can be entered. <code>NULL</code> can be used to specify the logon account value.

The original value is restored when the user exits the subsystem.</li>

<li>Privileges (in HEX) (optional) specifies a user's privileges while in the subsystem. Privileges specified before logging into the subsystem are overridden, regardless of the value of the Log user into M204 field. The original value is restored when the user exits the subsystem.

The privilege option is expressed as a hexadecimal value within the range of X'00' to X'FF', as described in [[Establishing and maintaining security#File security|File security]]. 
</li>

<li>Start Login Privileges (in HEX) specifies user login privileges for use while running the subsystem initialization procedure. If specified, Start Login Privileges in (HEX) overrides both the user's previous privileges and other privilege fields in the subsystem definition.

In the case of automatic login, the starting user's privileges are reset to those set on the Operational Parameters or Subsystem Classes screens prior to continuing execution within the subsystem. 

The privilege option is expressed as a hexadecimal value within the range of X'00' to X'FF', as described in [[Establishing and maintaining security#File security|File security]]. <code>NULL</code> indicates that other privilege specifications are not to be overridden. 
</li>

<li>Subsystem can access Remote Files pertains to PQO applications. <code>N</code> is the default. Change the value to <code>Y</code>, if you want the subsystem to access remote files. </li>
</ul>

===Message display options===

At the bottom of the screen are the message display options: 
<ul>
<li>Disconnect controls the display of subsystem disconnect messages:
<ul>
<li>If you specify <code>Y</code> (default), the subsystem disconnect message is displayed.</li>

<li>If you specify <code>N</code>, the subsystem disconnect message is suppressed.</li>
</ul></li>

<li>Informational controls the display of informational messages:
<ul>
<li>If you specify <code>Y</code> (default), <var class="product">Model 204</var> informational messages are displayed. </li>

<li>If you specify <code>N</code>, <var class="product">Model 204</var> informational messages are suppressed on the user's terminal and only subsystem messages are displayed. <var class="product">Model 204</var> messages continue to be printed on the audit trail.</li>
</ul></li>

<li>Error controls the display of error messages on the user's terminal.</li>

<li>If you specify <code>Y</code> (default), <var class="product">Model 204</var> error messages are displayed.</li>

<li>If you specify <code>N</code>, error messages are suppressed, but are still printed on the audit trail. </li>
</ul>

==Procedure Specifications screen==

Enter specifications for subsystem procedures on the Procedure Specifications screen. You access the [[RKWeb#Procedure|RKWeb version of this screen]] by selecting <code>Manage > Subsystem Management > Procedure</code>.

Procedure Specifications screen
[[File:Sm8-5Procedure.gif|564px]] 

===Commands===
<ul>
<li>F4, F6, F9, and F11 each validate, save the input, and provide the next secondary screen selection.</li>

<li>You must use a PF key to quit, save input, or move to a different screen.</li>

<li>Pressing Enter validates the screen.</li>
</ul>

===Procedure prefixes===

The PROCEDURE PREFIXES option requires each procedure used in a subsystem to have a prefix or be included in a procedure with a prefix. 

Subsystem procedures can contain <var class="product">Model 204</var> commands, requests, continued requests, or sections of SOUL code in any combination. A procedure containing commands cannot be precompiled. Procedures included in a precompiled procedure are also precompiled.
<ul>
<li>Non-precompiled specifies a prefix that identifies procedures that are compiled each time they are invoked.</li>

<li>Precompiled specifies a prefix that identifies precompiled procedures, which are included in the in-core dictionary for reuse. Precompiled procedures save CPU and elapsed time. </li>
</ul>

===Procedure names===

PROCEDURE NAMES require assigned prefixes that indicate if the procedure is or is not precompiled:
<ul>
<li>Initialization (optional) is the procedure invoked once when the subsystem is first started. </li>

<li>Login (required) is the name of the first procedure executed for every user.

<var class="product">Model 204</var> automatically includes a subsystem login procedure when a user enters a subsystem. This procedure must issue <var>UTABLE</var> commands to set compiler table sizes. 

Control must be passed to an initial main menu screen if the subsystem is an Online application. 
</li>

<li>Error (optional) is the name of the procedure invoked if an error occurs during execution of a subsystem, or if an attention interrupt occurs when no <var>ON ATTENTION</var> unit is active.

If no error procedure is supplied, <var class="product">Model 204</var> disconnects the user from the subsystem when an error occurs. </li>
</ul>

===Global variables===

GLOBAL VARIABLES enable you to pass information from one request to another and conditionally include procedures at the <var class="product">Model 204</var> command level: 
<ul>
<li>Command Line Variable specifies the name of an optional global variable containing parameter input that you can enter upon logon. The command line can contain up to 255 characters.

When a user logs in to a subsystem by entering the subsystem name followed by a number of parameters, the parameter input is placed into a global variable that is available to the subsystem procedures. If not defined, the command line is discarded.

Command line variables are not destroyed when control is transferred to another subsystem through the subsystem transfer (XFER) facility. </li>

<li>Communications variable (required) passes control from one procedure to the next. Each procedure sets the communications variable to the name of the next procedure executed in the subsystem.

You can transfer control from one procedure to another by using a user-designated global variable.

You can transfer control between subsystems by using the reserved global variable <code>XFER</code>. For more details about transferring control, see [[Application Subsystem development#Transferring control|Transferring control]].

When the application is ready to terminate, a subsystem procedure must set the communications global to the exit value.
</li>

<li>Exit Value (required) specifies the setting of the communications variable for exiting the subsystem.</li>

<li>Error Variable (required) specifies the variable in which an error code is stored. The value of the error variable, which is used by the error procedure, indicates the type of error. </li>
</ul>

==Subsystem File Use screen==

The Subsystem File Use screen defines the files, including the procedure file used by the subsystem. You access the [[RKWeb#Files|RKWeb version of this screen]] by selecting <code>Manage > Subsystem Management > Files</code>.

Subsystem File Use screen
[[File:Sm8-6FileUse.gif|537px]] 


It is useful to define a subsystem procedure file as a multiple-file procedure group. This will let you modify procedures in the group members without stopping the subsystem because of the following interactions of subsystems and procedure groups: 
<ul>
<li>All members of a procedure group are searched for subsystem procedures. The search, determined by the order in which the files were specified in the <var>[[CREATE command: Permanent group|CREATE]]</var> command that defined the group, begins with the leftmost specified member and proceeds to the right.

<li>The NUMLK parameter, on the Subsystem File Use screen, lets you determine how many and which members of a procedure group are locked (a member in which procedures cannot be modified). The locked members
are the Procs NUMLK number of consecutive members beginning with the rightmost member of the group and counting to the left. </li>

<li>You can add new procedures to any member of a procedure file group, but only procedures added to unlocked members are visible to the subsystem without restarting the subsystem.</li>
</ul>

A consequence of the above-listed factors is that you can
copy a procedure from a locked member to a (further-to-the-left) unlocked member designated for this purpose, modify that procedure copy, then let future APSY <var>INCLUDE</var> commands use that copy instead of the version in the locked member.

For example, the search for procedures in the group defined by the following <var>CREATE</var> command always starts with the leftmost file, <code>TESTPROC</code>, and proceeds to the right:
CREATE PERM GROUP PROCGRUP FROM TESTPROC, DEVPROC, QAPROC1, QAPROC2, PROD1, PRODPROC
PARAMETER PROCFILE=*
END CREATE


If the Subsystem File Use screen value of NUMLK is 3, procedures (with names starting with the pre-compiled prefix) in the three consecutive files beginning with the rightmost file, <code>PRODPROC</code>, are locked and cannot be modified
while their subsystem is active. But a procedure that is a member of <code>PROD1</code>, for example, can be copied, modified, added to <code>TESTPROC</code> and then included in the subsystem while it is still running.

For more information about the <var>PROCFILE</var> option, see its description in the <var>[[CREATE command: Temporary group#Temporary group parameters|CREATE TEMP GROUP]]</var> command.

Note: Procedures found in unlocked members are always recompiled on each include, imposing a significant performance penalty. That performance penalty can be eliminated by setting the <var>[[SIRAPSYF parameter|SIRAPSYF]]</var> parameter to X'03'. 

The in-core procedure dictionary is built during initialization by searching the locked members of a procedure file group for procedures with the precompiled prefix. If a subsystem procedure is present in more than one locked member of the procedure group, only the first procedure located in a left-to-right search of the locked members is included in the in-core procedure dictionary.


For further information, see also: 
<ul>
<li>[[Application Subsystem development#Permanent vs. temporary groups in subsystem definitions|Substituting a temporary group for the permanent group defined to the subsystem]]</li>

<li>Defining a multiple procedure file to the <var>[[$LstProc]]</var> function </li>

<li>[[Application Subsystem development#Guidelines and restrictions|Restrictions on using certain commands with multiple procedure files]] </li>
</ul>
Note: Non-system managers can add files to a subsystem if they have been assigned modify privileges (see [[#Administrative Privileges screen|Administrative Privileges screen]]).

===Commands===
<ul>
<li>F4, F5, F9, and F11 each validate, save the input, and provide the next secondary screen selection.</li>

<li>You must use a PF key to quit, save input, or move to a different screen.</li>

<li>F7 and F8 provide scrolling to and from the first to last Subsystem File Use screen when more than one is used. Input is validated before the screen scrolls.</li>

<li>Pressing Enter validates the screen.</li>

<li>You must issue the <code>TOP</code>, <code>BOTTOM</code>, and <code>MAXIMUM</code> commands on the command line. These commands have no corresponding PF keys.
<ul>
<li><code>TOP</code> scrolls to the first file.</li>

<li><code>BOTTOM</code> and <code>MAXIMUM</code> scroll to the last file.</li>

<li><code>MAXIMUM</code> used with F7 and F8 is equivalent to <code>TOP</code> and <code>BOTTOM</code>, respectively.</li>
</ul></li>
</ul>

===File specifications===
<ul>
<li>You must specify file or group names in the column labeled File/Group Name.

When using a group procedure file, the name specified must correspond to the permanent group. Note that an individual user can create or open a temporary group having the same name as the permanent group defined to the subsystem. If the temporary group is open before login to the subsystem, the subsystem uses the temporary group instead of the defined permanent group.

The following restrictions apply to the use of temporary groups as application subsystem procedure files:
<ul>
<li>TEST or DEBUG privilege is required.</li>

<li>The last files of the permanent group must correspond exactly to the last files of the temporary group. The number of files used in both groups is specified on the NUMLK parameter. </li>
</ul></li>

<li>File Location (PQO only) specifies the location of each file. If this field is omitted, the file is assumed to be local. Specify location only for client subsystems.</li>

<li>Group Y/N indicates whether or not the data file is a group. The default is <code>N</code>.</li>

<li>Auto Y/N indicates automatic members (opened automatically at subsystem startup). </li>

<li>Mandatory Y/N indicates mandatory members (which must be open to access the subsystem).</li>

<li>Procs specifies the name of the procedure file or group for the subsystem. You can use up to eight characters for each entry.

NUMLK specifies the number of files in a group that participate in procedure locking. Valid values are between 0 and 255, but must be less than the number of files in the group. 

If Group is <code>N</code>, the value of NUMLK must be <code>NULL</code>. If Group is <code>Y</code>, NUMLK must be given a value. </li>

<li>Deferred Name specifies an optional deferred update data set that can be a z/OS ddname, a z/VSE DLBL name, or a CMS FILEDEF name. If a deferred name is specified, the file is opened in deferred update mode when the subsystem is started. </li>

<li>Ordered-Index Deferred Name specifies an optional Ordered Index deferred update data set that can be a z/OS ddname, a z/VSE DLBL name, or a CMS FILEDEF name. If an ordered-index deferred name is specified, the file is opened in deferred update mode when the subsystem is started. </li>
</ul>

==Subsystem Classes screen==

Define command and file privileges for each class of subsystem users on the Subsystem Classes screen. You access the [[RKWeb#System_Classes|RKWeb version of this screen]] by selecting <code>Manage > Subsystem Management > System Classes</code>. 

Each class of user requires a separate screen. User class privileges defined to the subsystem override settings for <var>OPENCTL</var> and file privileges that reside in the password table.

Only the system manager can update the Logon Privilege, Record Security ID, and Account fields.

Subsystem Classes screen
[[File:Sm8-7SysClass.gif|559px]] 

===Commands===
<ul>
<li>F2, F4, F5, and F9 each validate, save the input, and provide the next secondary screen selection.</li>

<li>Use a PF key to quit, save input, or move to a different screen.</li>

<li>F6 displays current <var>PRIVDEF</var> parameter settings and lists options, described in [[#<Security specifications|Security specifications]], below.</li>

<li>F7 and F8 provide backward and forward scrolling when the list of files or groups exceeds one page. Input is validated before the screen scrolls.</li>

<li>F10 returns to the previous subsystem class. Input is validated and saved before moving to a different class.</li>

<li>F11 moves to the next subsystem class. Input is validated and saved before moving to a different class.</li>

<li>Pressing Enter validates the screen.</li>

<li>You must issue the TOP, BOTTOM, and MAXIMUM commands on the command line. These commands have no corresponding PF keys:
<ul>
<li><code>TOP</code> scrolls to the first file in this class.</li>

<li><code>BOTTOM</code> scrolls to the last file in this class.</li>

<li><code>MAXIMUM</code> used with F7 or F8 is equivalent to <code>TOP</code> or <code>BOTTOM</code>.</li>
</ul></li>
</ul>

===Subsystem name and class===
<ul>
<li>Subsystem Name specifies the name of the subsystem affected by the definitions entered on the screen.
</li>

<li>Subsystem Class is a system-assigned numeric identifier that specifies the user class being defined. As each new class is added, numeric identifiers are increased by an increment of 1.

In a semi-public subsystem, the first class is automatically assigned the class name <code>DEFAULT</code>, which you can change.
</li>
</ul>

===Security specifications===
<ul>
<li>Command Privileges determines if the user class (SCLASS) can issue the subsystem commands <var>START</var>, <var>TEST</var>, <var>STOP</var>, and <var>DEBUG</var>. The command fields take <code>Y</code> or <code>N</code>, and the default for all fields is <code>N</code>.

Debug specifies entering the subsystem in <var>DEBUG</var> mode. </li>

<li>Login Privilege (optional) specifies the user class login privileges for all, some, or none of the subsystem user classes.

Any individual user login privilege held at entry to the subsystem or specified on the Operational Parameters screen is overridden. The original value is restored when the user exits the subsystem.

The privilege option is expressed as a hexadecimal value within the range of X'00' to X'FF', as described in [[Establishing and maintaining security#PRIVDEF parameter settings|PRIVDEF parameter settings]]. 

<code>NULL</code> indicates default privileges from the Operational Parameters screen. </li>

<li>Record Security ID (optional) overrides any individual user record security ID held on entry to the subsystem. You can enter a maximum of eight characters.

<code>NULL</code> indicates the security activated on login.

The original value of the record security ID is restored when the user exits the subsystem. 
</li>

<li>Account (optional) specifies an account associated with specific user classes. Account can be specified for all, some, or none of the user classes. You can enter as many as ten characters.

Any individual value of Account held at entry to the subsystem or specified on the Operational Parameters screen is overridden. The original value is restored when the user exits the subsystem.

<code>NULL</code> indicates the user's login account or the value from the Operational Parameters screen.
</li>

<li>File/Group specifies files or groups that can be accessed by the defined class of users.

Define the set of files or groups belonging to the subsystem on the File Use screen and display them on this screen. </li>

<li>Location (PQO only) refers to the node where a file is located. </li>

<li>Prcldef specifies <var class="product">Model 204</var> procedure security. Values must be between 0 (default) and 255:
<ul>
<li>0 specifies no procedure security.</li>

<li>255 specifies the highest security. </li>
</ul></li>

<li>Privdef specifies file privileges. Values are hexadecimal 0 to X'BFFF' (default). </li>

<li>Sellvl, Readvl, Updtvl, and Addvl specify values for field-level security parameters. Values must be between 0 (default) and 255:
<ul>
<li>0 specifies all users can access field values.</li>

<li>255 restricts access of field values to users having certain privileges.</li>
</ul></li>

<li>PR specifies the name of the procedure file or group for the subsystem.</li>
</ul>

==User Definitions screen==

List user classes on the User Definitions (USErdef) screen for updating or browsing class definitions. You access the [[RKWeb#Operational|RKWeb version of this screen]] by selecting <code>Manage > Subsystem Management > Operational</code>. 

User Definitions screen
[[File:Sm8-8UserDef.gif|562px]] 

===Commands===
<ul>
<li>F2, F4, F5, and F6 display the next secondary screen.</li>

<li>F7 and F8 allow scrolling backward and forward for listing next or previous subsystem classes.</li>

<li>Pressing Enter displays the Subsystem Class Users screen for the class selected.</li>

<li>You must issue the TOP, BOTTOM, and MAXIMUM commands on the command line. These commands have no corresponding PF keys:
<ul>
<li><code>TOP</code> scrolls to the first class.</li>

<li><code>BOTTOM</code> scrolls to the last class.</li>

<li><code>MAXIMUM</code> used with F7 and F8, is equivalent to <code>TOP</code> and <code>BOTTOM</code>, respectively.</li>
</ul></li>
</ul>

===Screen specifications===
<ul>
<li>Subsystem Name specifies the applicable subsystem.</li>

<li>Subsystem Classes displays a listing, by class number and name, of the user classes defined on the Subsystem Classes screens.</li>

<li>ENTER SUBSYSTEM CLASS NUMBER accepts the number of the Subsystem Class whose user list is to be browsed/updated.</li>
</ul>

==Subsystem Class Users screen==

Define user accounts assigned to a specific class on the Subsystem Class Users screen. You access the [[RKWeb#classUsers|RKWeb version of this screen]] by selecting <code>Manage > Subsystem Management > Users</code>. 

A user can belong to only one class within a subsystem. If using more than one subsystem, the user can belong to a different class (different privileges) in each subsystem. 

Subsystem Class Users screen
[[File:Sm8-9SysClassUser.gif|531px]] 


Duplicate account entries result in the display of the class in which the original name resides.

Users can be added to a class, deleted, or replaced by entering, deleting, or typing over the individual <var class="product">Model 204</var> user account identification after the
prompt (<tt>></tt>). 

===Copy SCLASS option===

The Copy from Sclass options allow you to copy user IDs from an SCLASS already defined in one subsystem to the current SCLASS being defined. This option is not available in the RKWeb interface.

====PF keys====

The SCLASS copy options are represented by four PF key functions on the Subsystem Class Users screen: 
<ul>
<li>F4 (DELusers) deletes all users from a particular SCLASS selected from the User Definitions Screen. To execute this command, press F4. A warning message appears with the name of the SCLASS from which users are about to be deleted. Reenter the command if you are sure that you want to perform the Delete.</li>

<li>F5 (PREview) displays a list of all duplicate user IDs common to the copy-from SCLASS and any of the SCLASSes in the copy-to subsystem. The list is displayed on a separate screen, as shown in the [[#Sample Preview screen|Sample Preview screen]] section, below.</li>

<li>F10 (COPyusers) copies user IDs from the SCLASS specified in the copy-from field to the SCLASS selected from the User Definitions screen. This SCLASS is displayed on the current screen as a protected field.

When duplicate user IDs exist in another SCLASS in the copy-to subsystem, a warning message indicates that duplicates have not been copied. As with F4, reenter the command to perform the copy.
</li>

<li>F11 (CPReplace) copies user IDs as COPyusers does, but replaces duplicate user IDs. When duplicates exist, a warning message indicates that duplicates are moved from existing SCLASSes. Reenter the command to perform the copy with replacement.</li>

<li>Other PF keys function as in other secondary screens.</li>
</ul>

===Sample Preview screen===

The following screen is an example of the screen that appears when you execute the PREview command (F5) on the Subsystem Class Users screen:

Preview Duplicate USERIDS screen
[[File:8-10Preview.gif|493px]] 


This screen is purely informational. Press F3 to return to the Subsystem Class Users screen.

==Subsystem Import/Export options==

The Import and Export functions allow an authorized user to migrate subsystem definitions from one <var class="product">Model 204</var> environment to another via the migration file D204SYS, a <var class="product">Model 204</var> file created during Dictionary installation.

The Export Delete function deletes a specified subsystem from the D204SYS file. EXPortlist displays the list of subsystems that currently reside in D204SYS for which the user has <var>ALL</var> privileges (otherwise the user is not authorized to export them).

The four Import/Export options are all accessible from the Activity screen, shown earlier in [[#SUBSYSMGMT Activity screen|SUBSYSMGMT Activity screen]]. Import, Export, and Export Delete are options 7, 8, and 9, respectively. You can display an Exportlist by pressing F11, Export.

===Export===

The Export option allows authorized users to export subsystem definitions to another <var class="product">Model 204</var> Dictionary. To export a subsystem definition:
<ol>
<li>Select option 8 from the Activity screen.</li>

<li>Specify the subsystem to be exported.</li>

<li>To export SCLASS users, change the default value <code>N</code> to <code>Y</code> on the Export Users line.</li>

<li>Press Enter.</li>
</ol>

A message appears at the bottom of the screen indicating whether the Export has been successful. If the subsystem has already been exported by another user, then you cannot export it until it is deleted from D204SYS (see [[#Export Delete|Export Delete]]). 

===Import===

To import subsystem definitions, you must enter SUBSYSMGMT in the Dictionary to which the definition is to be imported. If the subsystem already exists, you must delete or rename it before importing. To import a subsystem definition:
<ol>
<li>Select option 7 from the primary menu.</li>
<li>Specify the subsystem to be imported</li>
<li>Press Enter.</li>
</ol>

A message appears at the bottom of the screen indicating whether the Import was successful. After an Import, the subsystem definitions remain in D204SYS until they are deleted.

===Export Delete===

To delete a subsystem from D204SYS:
<ol>
<li>Select option 9 from the primary menu</li>
<li>Specify the subsystem to be deleted from D204SYS</li>
<li>Press Enter.</li>
</ol>

===Exportlist===

To display the subsystems in D204SYS for which you have ALL privileges, press F11. The list displayed shows the name of each subsystem, the date and time of export, and the exporting user ID. 

===Exportable data: scope and limitations===

The Import/Export functions export all information in METADATA and DATALINK except for STAGED entities and user-defined links to the subsystem.

After an import, the LAST UPDATED field for a METADATA entry is changed to the date of import, and the UPDATED-BY field is changed to the importer's user ID. 

User SCLASSes can be imported (see [[#Export|Export]]); but administrative privileges cannot be imported.

==Subsystem Administration screen==

The Subsystem Administration screen appears when the system manager selects option 10 (ADMIN) on the SUBSYSMGMT primary menu. This option is available only to a system manager. 

Subsystem Administration screen
[[File:Sm8-12Admin.gif|513px]] 


Select Usage privileges by entering <code>U</code> on the space provided (<code>U</code> is the default). These privileges correspond exactly to the User Activity privileges in previous releases of <var class="product">Model 204</var>. Selecting <code>U</code> brings up the User Matrix screen described in [[#User Matrix screen|User Matrix screen]].

Select Administrative privileges for a User Account by entering <code>A</code>. The four Admin options are explained in the following section, [[#Admin options|Admin options]].

When setting privileges for specific users, remember that access to SUBSYSMGMT must be authorized via the DICTADMIN facility, as it is for every <var class="product">Model 204</var> Dictionary subsystem. The privileges granted here supplement but do not override general access privileges granted through DICTADMIN.

===Admin options===

The Subsystem Administration screen offers four options, described in the following sections.

====1. Define Privileges====

The Define Privileges option lets the system manager grant administrative privileges to specific users for specific subsystems. Selecting this option brings up the [[#Administrative Privileges screen|Administrative Privileges screen]]. To execute Define Privileges, enter <code>1</code> at the selection number prompt, specify the user ID to be assigned privileges in the User Account field, and press Enter.

====2. Copy====

The Copy option duplicates a user's administrative privileges to another user ID. To execute Copy, enter <code>2</code> at the selection number prompt, specify the user ID to be copied in the User Account field, specify the name of the user ID to be copied to in the Copy/Rename field, and press Enter. 

====3. Rename====

The Rename option changes a user ID associated with a given set of administrative privileges. To execute Rename, enter <code>3</code> at the selection number prompt, specify the user ID to be renamed in the User Account field, specify the new name in the Copy/Rename field, and press Enter. 

====4. Delete====

The Delete option takes away all administrative privileges associated with a specific user ID. To execute Delete, enter <code>4</code> at the selection number prompt, specify the user ID in the User Account field, and press Enter.

===Subsystem pattern field===

The Subsystem pattern field applies to all options in both Usage and Admin modes. You can leave it blank, enter a single subsystem name, or enter a pattern: 
<ul>
<li>If you leave this field blank, the next screen displays all subsystems. </li>

<li>If you select a pattern following the [[Record retrievals#Pattern matching|standard pattern specifications]],
the found set of subsystems are displayed on the next screen — the User Matrix screen, if in Usage mode; the Administrative Privileges screen, if in Admin mode.</li>
</ul>

==Administrative Privileges screen==

The Define Privileges option selected in Admin mode displays the Administrative Privileges screen. To create or delete privileges, type or space over <code>X</code>s in the appropriate spaces. 
Note:
Take care when granting All and Modify privileges. A user with these privileges can update subsystem file use data.

Administrative Privileges screen
[[File:Sm8-13AdminPriv.gif|535px]] 

===Hierarchy of privileges===

The ALL SUBSYS row on this screen grants the account the selected privileges for all subsystems: All, Modify, Browse, Udef.

If both ALL SUBSYS and specific subsystem privileges are granted, the higher privilege takes precedence. 

For Import, Add, and Copy privileges, a user must also be a member of the ADDPRIV SCLASS, described in [[#ADDPRIV SCLASS and Add Privileges|ADDPRIV SCLASS and Add Privileges]].

===PF keys===
<ul>
<li>F1 (HELp) displays Help text for the screen.</li>

<li>F2 (TOP) scrolls to the top of the display.</li>

<li>F3 (QUIt) returns the user to the Admin Screen without saving changes. Before exiting, warning messages are displayed indicating that changes have not been saved.</li>

<li>F5 (LOCate) locates a specified subsystem on the display list. Specify the name on the command line before pressing F5. If the subsystem name is found, it is highlighted and displayed at the top of the list. If it is not found, the display is unchanged.</li>

<li>F7 (BACkward) scrolls backward through the list of subsystems specified. A maximum of ten subsystems are displayed on the screen at once. </li>

<li>F8 (FORward) scrolls forward through the list of subsystems specified. </li>

<li>F12 (END) saves all screen changes and returns the user to the Admin Screen.</li>

<li>The Enter key has no effect on this screen.</li>
</ul>

===ADDPRIV SCLASS and Add Privileges===

To give a user Add, Copy, or Import privileges, the system manager must add the appropriate user ID to a new SCLASS called ADDPRIV. Do this as shown in [[#User Matrix screen|User Matrix screen]], or in [[#User Definitions screen|User Definitions screen]].

==Summary of subsystem privileges==

The "Summary of subsystem privileges" table shows how the system of assigned privileges relates to the ten functions displayed on the [[#SUBSYSMGMT Activity screen|Subsystem Management Facility screen]]. The columns are privileges granted, including general system manager privileges. The rows are SUBSYSMGMT functions. 
<table>
<caption>Summary of subsystem privileges</caption>
<tr class="head">
<th>Option</th>
<th colspan="6"> Assigned privilege</th>
</tr>

<tr>
<td> </td>
<td>ALL</td>
<td>Modify</td>
<td>Browse</td>
<td>Udef</td>
<td>ADDPRIV member</td>
<td>System manager</td>
</tr>

<tr>
<td>
Add
</td>
<td> </td>
<td> </td>
<td> </td>
<td> </td>
<td>X</td>
<td>X</td>
</tr>

<tr>
<td>
Modify
</td>
<td>X</td>
<td>X</td>
<td> </td>
<td>X</td>
<td> </td>
<td>X</td>
</tr>

<tr>
<td>
Browse
</td>
<td>X</td>
<td>X</td>
<td>X</td>
<td> </td>
<td> </td>
<td>X</td>
</tr>

<tr>
<td>
Copy
</td>
<td>X</td>
<td> </td>
<td> </td>
<td> </td>
<td>X</td>
<td>X</td>
</tr>

<tr>
<td>
Rename
</td>
<td>X</td>
<td> </td>
<td> </td>
<td> </td>
<td> </td>
<td>X</td>
</tr>

<tr>
<td>
Delete
</td>
<td>X</td>
<td> </td>
<td> </td>
<td> </td>
<td> </td>
<td>X</td>
</tr>

<tr>
<td>
Import
</td>
<td> </td>
<td> </td>
<td> </td>
<td> </td>
<td>X</td>
<td>X</td>
</tr>

<tr>
<td>
Export
</td>
<td>X</td>
<td> </td>
<td> </td>
<td> </td>
<td> </td>
<td>X</td>
</tr>

<tr>
<td>
Export Delete
</td>
<td>X</td>
<td> </td>
<td> </td>
<td> </td>
<td> </td>
<td>X</td>
</tr>

<tr>
<td>
Admin
</td>
<td> </td>
<td> </td>
<td> </td>
<td> </td>
<td> </td>
<td>X</td>
</tr>
</table>
Note: Copy privileges require both ALL and ADDPRIV SCLASS membership. A user assigned Udef privileges can update only the Userdef screens.

==User Matrix screen==

To change a single account in any class of a subsystem, use the User Matrix screen. Access the User Matrix screen by selecting the ADMIN option (number 10) on the Activity screen, then selection 1 under the Usage options. 

User Matrix screen
[[File:Sm8-14Matrix.gif|533px]] 

===Commands===
<ul>
<li>F7 and F8 provide scrolling to and from the first to last Subsystem Class Users screen when more than one screen is required.</li>

<li>F10 and F11 provide scrolling to the left and to the right to locate all subsystem classes for the subsystem shown in the leftmost column. </li>
</ul>

===Specifications===
<ul>
<li>Subsystem Name specifies the subsystem in which the user account is defined.</li>

<li>Account Exists In specifies the class in which the account is defined.</li>

<li>Subsystem Classes commands are entered in a one-character input field that precedes each class displayed:
<ul>
<li><code>A</code> adds the current account to the class in the subsystem shown.</li>

<li><code>C</code> changes the class in the subsystem to which the current account belongs from the Account Exists In or default class to the class at the right of the command.</li>

<li><code>D</code> deletes the current account from the class in the subsystem shown. Note that this is one way to change an account's class from a non-default to the default class in a semi-public subsystem. </li>
</ul></li>
</ul>

==Dynamic APSY support==

An application subsystem (APSY) is comprised of <var class="product">Model 204</var> procedures executed in a logical order. You define the operation of the application using the <var class="product">Model 204</var> Subsystem Management facility (SUBSYSMGMT). The <var class="product">Model 204</var> procedures determine the contents of the application. You can dynamically modify the following aspects of an APSY, without terminating the APSY and without interrupting service to your users:
<ul>
<li>A subset of application subsystem attributes.</li>

<li>Precompiled and non-precompiled procedures in files that participate in procedure locking while the subsystem is active. </li>
</ul>

You can also save compiled procedures that contain commands by saving the commands before and after the BEGIN/END. The commands are saved on a chain of CCATEMP pages in the form of a temporary procedure. The temporary procedure contains pointers to these pages. These temporary procedures are not the user-accessible temporary procedures (0, -1, and so on) and do not interfere with their operation.

===Changing APSY subsystem attributes===

Subsystem attribute modifications are saved to the permanent subsystem definition in the CCASYS file as well as to the active in-core subsystem definition without interrupting service to the subsystem user.

====Updating an active subsystem via SUBSYSMGMT====

The SUBSYSMGMT subsystem maintains all subsystem definitions. You can modify various attributes of a subsystem through a variety of screens provided by SUBSYSMGMT. Once you are satisfied with the modifications that are made, press F12 to end the updates and to save the definition to disk.
SUBSYSMGMT checks to see if the subsystem is currently active:
<ul>
<li>If the subsystem is not active, you return to Subsystem Management Facility screen. </li>

<li>If the subsystem is active, the following Active Subsystem Update screen is displayed:
<table>
<tr><td>
SUBSYSMGMT Active Subsystem Update

Subsystem: MCC1

is currently active.

Would you like to update the active subsystem definition?

PF3 to QUIT/Not update the active subsystem definition
PF12 to END/Update the active subsystem definition

===>

1=HELp 2= 3=QUIt 4= 5= 6=
7= 8= 9= 10= 11= 12=END
</td></tr>
</table>
</li>
</ul>

At this point, the permanent definition in the CCASYS file has been updated. Your response to this screen determines whether the subsystem will be dynamically updated.
<ul>
<li>To update the active subsystem definition, press F12. </li>

<li>To keep the active in-core definition unchanged, press F3. </li>
</ul>

Only the F1 (HELp), F3 (QUIt), and F12 (END) function keys are active at this time. 

====Using Active Subsystem Help====

If you press F1 while in the Active Subsystem Update screen, the following Active Subsystem Help screen is displayed: 
<table>
<tr><td>
SUBSYSMGMT Active Subsystem Help

Use this screen to update the active subsystem definition. If the subsystem
has been started and is currently active then the user has the option of
refreshing the subsystem definition that is currently running. Only the
following fields are supported for active update at this time:
. Log user into M204
. Log user out of M204
. Auto Commit
. Maximum Iterations
. Account
. Disconnect
. Informational
. Error
. Login Procedure
. Error Procedure
In order to update APSY fields that are not supported for active update,
the user must stop and restart the subsystem.
Use the PF key below to move to the next screen:
PF 3 = QUIT Does NOT UPDATE active subsystem definition.
Returns to Subsystem Management primary screen.
PF12 = END Updates active subsystem definition.
Returns to Subsystem Management primary screen.
</td>
</tr>
</table>

====Leaving the active subsystem unchanged====

If you press F3 or enter <code>QUIT</code> in the Active Subsystem Update screen, you leave the active subsystem unchanged and return to the Subsystem Management Facility screen. The changes you made go into effect the next time the subsystem is started

====Updating the active subsystem====

Press F12 or enter <code>END</code> to update the active subsystem definition. The changes to the dynamic attributes go into effect immediately. Non-dynamic changes do not take effect until the next time the subsystem is started. 
<ul>
<li>If the update is successful, you are returned to SUBSYSMGMT main menu screen without any confirmation messages displayed.</li>

<li>If the update is unsuccessful, one of the following messages is displayed on the main menu screen:
SUM014 Unable to update active definition for subsystem: name
SUM015 Unable to update active definition, name is no longer active
</li>
</ul>

====Understanding the Dictionary/204 data definition errors====

<code>SUM014</code> is displayed if an error occurs while attempting to update the active definition. The reason for the error can be found on the audit trail with one of the following errors: 
M204.1457 UNABLE TO SCAN LIST OF SUBSYSTEM names

M204.1685 SUBSYSTEM name DOES NOT EXIST

M204.2253 SUBSYSTEM name, record type - RECORD CONTAINS INVALID DATA

M204.2391 SUBSYSTEM name, record type - TRANSLATION FAILED FOR FIELD fieldname

M204.2395 SUBSYSTEM name, record type - RECORD MISSING


<code>SUM015</code> is displayed if the subsystem is stopped while attempting to update the active definition. The following error message is generated on the audit trail:
M204.2647 UNABLE TO UPDATE ACTIVE DEFINITION, <name> IS NO LONGER ACTIVE.


====Limits to dynamic subsystem attribute changes====

The following table lists the subsystem attributes that you can change. You can make changes on the Operational Parameters screen in SUBSYSMGMT: 
<table class="thJustBold">
<caption>Operational Parameters you can change</caption>

<tr class="head">
<th>Operational Parameter </th>
<th>Specifies</th>
</tr>

<tr>
<th>Log user into M204 </th>
<td>The user is logged into <var class="product">Model 204</var> with the subsystem name as the USERID</td>
</tr>

<tr>
<th>Log user out of M204 </th>
<td>The user is logged out upon leaving subsystem </td>
</tr>

<tr>
<th>Auto Commit </th>
<td> A User Language COMMIT/RELEASE statement is run at the end of each procedure</td>
</tr>

<tr>
<th>Maximum Iterations </th>
<td>Maximum number of consecutive times you can invoke the same procedure before the ERROR procedure is invoked</td>
</tr>

<tr>
<th>Account </th>
<td>The account value other than the one used at logon</td>
</tr>

<tr>
<th>Disconnect </th>
<td>Whether to display a system disconnect message</td>
</tr>

<tr>
<th>Informational </th>
<td>Whether to display <var class="product">Model 204</var> informational messages</td>
</tr>

<tr>
<th>Error </th>
<td>Whether to display <var class="product">Model 204</var> error messages</td>
</tr>
</table>

You can change the following on the Procedure Specifications screen in SUBSYSMGMT:
<table class="thJustBold">
<tr class="head"><th>Procedure </th>
<th>Description</th>
</tr>

<tr>
<th>Login </th>
<td>First procedure that is invoked for every user</td>
</tr>

<tr>
<th>Error </th>
<td>Procedure that is invoked if an error occurs when a subsystem is running</td>
</tr>
</table>

If you dynamically change the name of the Login procedure or the Error procedure, the new name must be defined in the in-core procedure dictionary. You cannot add new procedures to a subsystem procedure file that participates in procedure locking once the subsystem has been started and have those procedures included by the subsystem. Therefore, if you change the name of the login or error procedure that resides in a file that participated in procedure locking, then that procedure must have existed when the subsystem was started. 

===Dynamically refreshing procedure compilation with the REFRESH SUBSYSPROC command===

The <var>[[REFRESH SUBSYSPROC command|REFRESH SUBSYSPROC]]</var> command discards the existing precompilation and precompiles the first time through for each SYSCLASS. Once a procedure is refreshed, the subsystem includes the new version of the procedure the next time that procedure is invoked.
The newer version of the procedure is compiled and saved in CCATEMP for subsequent execution. 

The <var>REFRESH SUBSYSPROC</var> command optionally copies a procedure from an open file (or group) into another open subsystem file (or group) and updates the APSY in-core procedure dictionary with the new procedure text page. In group context, the <var>REFRESH SUBSYSPROC</var> command replaces and refreshes only procedures that participate in procedure locking, based on the <var>NUMLK</var> parameter. 

====Generating success messages====

Successful execution of the <var>REFRESH SUBSYSPROC</var> command generates the following confirmation messages:
M204.2665 procname REFRESHED IN SUBSYSTEM subsystem-name


If a <var>FROM</var> clause is specified, the following message is produced:
M204.2666 procname REPLACED IN FILE filename [IN GROUP groupname]


====Generating error messages====

The <var>REFRESH SUBSYSPROC</var> command may fail under the following circumstances:
<ul>
<li>If you do not have Refresh privileges to issue the command, the command fails, the procedure is not refreshed, and the following message is generated:
M204.0930 REQUIRES SUBSYSTEM COMMAND PRIVILEGE
</li>

<li>If the procedure is not defined in an active subsystem, the command fails, the procedure is not refreshed, and the following message is generated:
M204.2668: procname NOT FOUND IN ANY ACTIVE SUBSYSTEM
</li>

<li>If a procedure is not found in the file named in the <var>FROM</var> clause, or if the user does not have appropriate file privileges to copy procedures, the following message is generated:
M204.1158: CAN'T COPY PROCEDURE: procname
</li>

<li>If the subsystem file (or group) is out of space to copy the procedure, the command fails, the procedure is not refreshed, and the following message is generated:
M204.1483: NOT ENOUGH TABLED SPACE TO STORE PROCEDURE
</li>

<li>If another user is processing the procedure, the following message is generated:
M204.2669: PROCEDURE procname IS IN USE BY SUBSYSTEM subsys-name
</li>
</ul>

====Understanding REFRESH SUBSYSPROC command privileges====

Privileges to issue the <var>REFRESH SUBSYSPROC</var> command are set on the SUBSYSMGMT [[#Subsystem Classes screen|Subsystem Classes screen]] using the Refresh field on the Command Privileges line. The input to this field is either <code>Y</code> or <code>N</code>, where <code>N</code> is the default. To issue the <var>REFRESH SUBSYSPROC</var> command, set the Refresh value to <code>Y</code>.

====Subsystem processing====

When you refresh an active subsystem procedure, the following occurs:
<ul>
<li>Precompiled procedures are recompiled for each SCLASS.</li>

<li>While a procedure is being refreshed, the procedure is locked. While a procedure is locked, other users cannot access it. The length of time that the procedure is stopped is as short as possible.

However, if a subsystem attempts to include a procedure that is in the process of being refreshed, the APSY tries to invoke the procedure a few times before giving up. If the APSY fails to invoke the procedure, then the subsystem error procedure is invoked with the error global set to <code>RFR</code>. 

You must write an error procedure instructing your subsystem how to respond to various errors.
</li>
</ul>

====Handling a blocked refresh for a subsystem procedure====

If an APSY subsystem procedure with the subsystem precompile prefix is compiled, and the procedure is found in an unlocked subsystem procedure file, the following message is generated:
M204.0468: COMPILATION NOT SAVED - INCLUDE FROM UNLOCKED FILE


====Using the SUSPEND SUBSYSTEM command====

Rocket Software recommends that you issue the <var>[[SUSPEND SUBSYSTEM command|SUSPEND SUBSYSTEM]]</var> command and wait for the active users to exit. If you do not wait, you could have the following problem. The subsystem, which has logically related procedures, is suspended and a user invokes a procedure whose higher-level or lower-level procedure has not been updated and refreshed yet.



Privileges to issue the <var>SUSPEND SUBSYSTEM</var> command are set in the SUBSYSMGMT "Subsystem Classes" screen: 
<table>
<tr class="head">
<th>If you issue a SUSPEND SUBSYSTEM command when... </th>
<th>The subsystem is set to...</th>
</tr>

<tr>
<td>No active users are in the application subsystem </td>
<td>Suspended state.</td>
</tr>

<tr>
<td>Active users are in the subsystem </td>
<td>Suspending state. Current, active users continue to use the subsystem, but new users cannot enter it. After all users exit the subsystem, it is set to the Suspended state.</td>
</tr>
</table>

====Monitoring the subsystem====

You can issue a <var>MONITOR SUBSYSTEM</var> command to check the status — such as Drain or Suspend — of the subsystem, as well as the number of users still running. Once a subsystem is fully suspended and the number of users is zero (0), you can safely refresh a set of logical procedures.

If you suspend a subsystem that still has active users, the <var>STATUS</var> option from the <var>MONITOR SUBSYSTEM</var> command is set to <var>SUSPENDING</var>. When a subsystem is fully suspended with no active users, the <var>STATUS</var> option from the <var>MONITOR SUBSYSTEM</var> command is set to <var>SUSPENDED</var>. 

If the subsystem is in the process of suspending, the following message is generated:
M204.2659 subsys-name SET TO SUSPEND, REMAINING USERS=n


====SUSPEND SUBSYSTEM command messages====

The <var>SUSPEND SUBSYSTEM</var> command may produce the following messages:
<ul>
<li>When a subsystem is successfully suspended, the following message is generated:
M204.2661 SUBSYSTEM subsys-name SUSPENDED
</li>

<li>When there are still active users in the subsystem, the following message is generated:
M204.2659 subsys-name SET TO SUSPEND, REMAINING USERS = <n>
</li>

<li>If you issue the <var>SUSPEND SUBSYSTEM</var> command without Subsystem Suspend privileges defined for your SCLASS, the following message is generated:
M204.0930 REQUIRES SUBSYSTEM COMMAND PRIVILEGE
</li>

<li>The <var>SUSPEND SUBSYSTEM</var> command is valid against only an active subsystem. If the subsystem has not been started, the following message is generated:
M204.1126 SUBSYSTEM name MUST BE STARTED
</li>

<li>If the subsystem is in <var>TEST</var> mode, it is locked from other users, so the following message is generated:
M204.0448 SUBSYSTEM TEST IN PROGRESS, COMMAND REJECTED
</li>

<li>If a subsystem is in the process of starting, but not yet fully active, the following message is generated:
M204.2311 SUBSYSTEM subsys-name IS BEING STARTED
</li>

<li>If the subsystem was set to Stop and is waiting for all active users to quit, the following message is generated:
M204.0446 SUBSYSTEM subsys-name IS TEMPORARILY DISABLED
</li>

<li>If the subsystem requires users to log into <var class="product">Model 204</var> and you are not logged in, the following message is generated:
M204.1031 PLEASE LOGIN
</li>

<li>If an error prevents the subsystem from being suspended, the following message is generated. The preceding message states the cause of the error.
M204.2656 UNABLE TO SUSPEND SUBSYSTEM subsys-name
</li>
</ul>

<div id="resume subsystem"></div>
====Using the RESUME SUBSYSTEM command====

When you have completed refreshing a suspended subsystem, you can reactivate it with a <var>[[RESUME SUBSYSTEM command|RESUME SUBSYSTEM]]</var> command.


Privileges to issue the <var>RESUME SUBSYSTEM</var> command are set in the SUBSYSMGMT "Subsystem Classes" screen.

The <var>RESUME SUBSYSTEM</var> command may generate the following messages:
<ul>
<li>When a subsystem successfully resumes, the following message is generated:
M204.2657 SUBSYSTEM subsys-name RESUMED
</li>

<li>If you issue the <var>RESUME SUBSYSTEM</var> command without Subsystem Resume privileges defined for your SCLASS, the following message is generated:
M204.0930 REQUIRES SUBSYSTEM COMMAND PRIVILEGE
</li>

<li>The <var>RESUME SUBSYSTEM</var> command is valid against only a suspended subsystem. If the subsystem was not suspended, the following message is generated:
M204.2658 SUBSYSTEM subsys-name NOT IN SUSPEND STATE
</li>

<li>The <var>RESUME SUBSYSTEM</var> command is valid against only a suspended subsystem. If the subsystem has not been started, the following message is generated:
M204.1126 SUBSYSTEM subsys-name MUST BE STARTED
</li>

<li>If the subsystem is in Test mode, it is inactive for other users, so the following message is generated:
M204.0448 SUBSYSTEM TEST IN PROGRESS, COMMAND REJECTED
</li>

<li>If a subsystem is in the process of starting, but not yet fully active, the following message is generated:
M204.2311 SUBSYSTEM subsys-name IS BEING STARTED
</li>

<li>If the subsystem was set to stop and is waiting for active users to quit, the following message is generated:
M204.0446 SUBSYSTEM subsys-name TEMPORARILY DISABLED
</li>

<li>If the subsystem requires users to be logged in to <var class="product">Model 204</var> and you are not logged in, the following message is generated:
M204.1031 PLEASE LOGIN
</li>

<li>If an error prevents the subsystem from resuming processing, the following message is generated. The previous message states the cause of the error.
M204.2655 UNABLE TO RESUME SUBSYSTEM subsys-name
</li>
</ul>

===Using precompilable procedures with commands===

If you want to conditionally compile and save a SOUL request through the use of dummy string comments, then you must ensure that the value of the dummy string is the same for all SOUL statements for that request. Otherwise, unpredictable results occur. 

In addition, the loading user will invoke the request that was conditionally compiled by the compiling user. This behavior is simply noted as a reminder.

If a precompiled procedure issues the <var>INCLUDE</var> command to compile and run a SOUL request, the <var>INCLUDE</var> command is saved, not the compilation of the request that was included.

Dummy string substitution does not take place when saving commands that contain dummy strings. Instead, when the saved commands are loaded and executed, the current value of the dummy string is used. For example, if you include the following command in a precompiled procedure, whatever is currently in the global <code>COMMAND</code> is executed.
?&COMMAND


Procedures that include multiple <var>BEGIN</var>/<var>END</var> blocks are not eligible for precompilation.

===Handling subsystem error procedures===

If a subsystem error procedure is cancelled due to attempted terminal I/O, and the return code is one of the following — <code>CAN</code>, <code>HNG</code>, <code>HRD</code>, or <code>SFT</code> — the error procedure cannot attempt to issue any of the following SOUL statements:
<ul>
<li>PRINT</li>

<li>READ</li>

<li>READ MENU</li>

<li>SCREEN</li>

<li>SKIP</li>

<li>$$ prompts</li>

<li>$Read</li>

<li>Or any other statement that writes to the user's terminal</li>
</ul>

All other SOUL statements are permitted.

</div> 

[[Category:System management]]
[[Category:Model 204 operational issues]]

Tracking system activity (CCAJRNL, CCAAUDIT, CCAJLOG)

2024-09-10T21:14:45Z

JDamon: /* Searching multiple tapes for journal and off load data */

<div class="toclimit-3">
==Overview of the journal data sets==

This topic discusses the journal data sets you can create and use in <var class="product">Model 204</var>, how to manage them, and the utilities you can use to report on and analyze the <var class="product">Model 204</var> information collected. The system manager can set up the following journal data sets, which are not part of <var class="product">Model 204</var> installation.

The data sets are CCAJRNL, CCAAUDIT, and CCAJLOG. You set each up as:
<ul>
<li>A ddname in z/OS</li>

<li>A FILEDEF in z/VM</li>

<li>A DLBL in z/VSE</li>
</ul>

===CCAJRNL===

The complete repository of <var class="product">Model 204</var> system activity and data that would be used in recovery is CCAJRNL. The CCAJRNL file collects all update information used to reconstruct the database during recovery and all other activity history, such as messages and statistics, in an unformatted, therefore unreadable, binary format.

===CCAAUDIT and CCAJLOG===

You can also create a CCAAUDIT and/or a CCAJLOG file to track information. CCAAUDIT and CCAJLOG are comprised of the same <var class="product">Model 204</var> audit trail data, however, differently. The activity history or audit trail is comprised of:
<ul>
<li>Important characteristics of a run</li>

<li>All error messages encountered during a run</li>

<li>All communications with the operator's console</li>

<li>Input lines from Online terminals</li>

<li>HLI calls</li>

<li>Utilization statistics</li>

<li>Information specifically directed to the journal/audit trail by users </li>
</ul>

====Watching your system in action: CCAAUDIT====

The CCAAUDIT file, also known as the audit trail, logs information about a <var class="product">Model 204</var> run and prints the information in readable format for the terminal screen while processes are running or to paper.

====Improving recovery performance: CCAJLOG====

The CCAJLOG file off loads the audit trail information into itself, so that the CCAJRNL contains only the information required for RESTART recovery. Recovery performance is improved, because the audit trail information does not have to be read and rejected for recovery.

===Version-specific journals===

Journals created by <var class="product">Model 204</var> prior to V7R1.0 cannot by processed in V7R1.0. The reverse is also true: journals created in V7R1.0 cannot be processed by an earlier version of <var class="product">Model 204</var>.

==Using Model 204 journal files==

<var class="product">Model 204</var> system managers and file managers use the journal files in some of the following ways:
<table>
<tr class="head">
<th>Task </th>
<th>Journal used </th>
<th>Utility/command used</th>
</tr>

<tr>
<td>Generate an audit trail that can be viewed during processing </td>
<td>CCAAUDIT</td>
<td> </td>
</tr>

<tr>
<td>Generate an audit trail for printing out later </td>
<td nowrap>CCAJRNL, CCAJLOG </td>
<td>Audit204 utility</td>
</tr>

<tr>
<td>Regenerate a file to complete media recovery</td>
<td>CCAJRNL (ddname CCAGEN) </td>
<td>REGENERATE command</td>
</tr>

<tr>
<td>Recover <var class="product">Model 204</var> following a system failure </td>
<td>CCAJRNL (ddname CCARF) </td>
<td>RESTART command</td>
</tr>

<tr>
<td>Extract a report </td>
<td>CCAJRNL</td>
<td>UTILJ utility</td>
</tr>

<tr>
<td>Performance tuning by analyzing statistics </td>
<td>CCAJRNL</td>
<td>Audit204 utility or site written analysis program</td>
</tr>
</table>

The <var class="product">Model 204</var> system manager is expected to create the CCAJRNL file at their site for recovery purposes. The <var class="product">Model 204</var> file manager may be responsible for using the CCAJRNL file to regenerate data files.

==Creating and generating CCAJRNL==

A journal is generated if: 
<ul>
<li>The <var>SYSOPT</var> parameter includes the 128 specification.

You must set <var>BLKSIZE</var> for CCAJRNL to not less than 6749 on up to 32K. Buffers are written to CCAJRNL either when a transaction is committed or when the buffer fills. Frequent commits may result in many short blocks/buffers being written to CCAJRNL.
</li>

<li>A CCAJRNL is defined with BLKSIZE set to the minimum, 6749, for:
<ul>
<li>z/OS, a DD statement</li>

<li>z/VM, a FILEDEF</li>
</ul></li>
</ul>

Statistics generated in an audit trail line are presented in [[Using system statistics#User statistics entries (Type 9)|User statistics entries (Type 9)]]. 

The use of CCAJRNL in recovery procedures is explained in [[System and media recovery#Recovery data sets and job control|Recovery data sets and job control]]. 

How to use CCAJRNL to regenerate a data set is discussed
in [[Media recovery]].

CCAJRNL may take multiple extents and may span multiple volumes, since it is read forward-only. Its size cannot be limited in a way similar to the CHKPOINT data set (see [[Checkpoints: Storing before-images of changed pages#Limiting the size of CHKPOINT|Limiting the size of CHKPOINT]]), because CCAJRNL records all update activity in an Online, which may be required in a subsequent REGENERATE or RESTART process.

===CCAJRNL as single data set or stream===

You can define CCAJRNL as a single data set or as a stream. Using a <var>[[DEFINE STREAM command|DEFINE STREAM]]</var> command, you incorporate multiple journal data sets. 
<ul>
<li>For parallel and ring structures, see [[Configuring checkpoint and journal data streams#Example 1: Ring/parallel journal stream|Example 1: Ring/parallel journal stream]].</li>

<li>For GDG structure, see [[Configuring checkpoint and journal data streams#Perpetual journaling for z/OS|Perpetual journaling for z/OS]]. </li>
</ul>

==SWITCH STREAM command==

The <var>[[SWITCH STREAM command|SWITCH STREAM]]</var> command switches a stream to the next member of a parallel, ring, concatenated, or Generation Data Group (GDG) stream. You can issue the <var>SWITCH STREAM</var> command for the following streams: CCAJLOG, CCAJRNL, CHKPOINT, or CHKPNTS. 

===Using the SWITCH STREAM command===

When the <var>SWITCH STREAM</var> command is issued, the following messages are produced:
M204.2712: STREAM streamname IS BEING SWITCHED
M204.2712: STREAM streamname SWITCHED VIA COMMAND

<ul>
<li>When switching a journal stream, CCAJRNL or CCAJLOG, the currently active data set in that stream is closed. The next data set defined to the stream is opened when the next write to that stream is required. </li>

<li>When switching a checkpoint stream, CHKPOINT or CHKPNTS, the currently active data set in that stream is closed after the next record is written to that data set.</li>
</ul>

If not in an extended quiesce, Rocket Software recommends that you follow a <code>SWITCH STREAM CCAJRNL</code> command with a <var>CHECKPOINT</var> command to ensure that you have a checkpoint in the current journal. 

The <var>SWITCH STREAM command</var> is sometimes useful for CCAJLOG and rarely required for CHKPOINT or CHKPNTS.

===Journal block header information for SWITCH STREAM===

Some journal analysis utilities require additional journal information at sites that embrace GDG streams and the <var>SWITCH STREAM</var> command as a means to keep their Onlines up for long periods. <var class="product">Model 204</var> includes this additional information in the header for each journal block. 

To ensure that the required information is present in the first block of each journal data set created by the <var>SWITCH STREAM</var> command, the header has been expanded. This expansion makes the journal up to 4% larger than in previous releases.
Note: Due to these changes in journal record layouts, CCAJRNL and CHKPOINT/CHKPNT data sets are not compatible with previous releases of <var class="product">Model 204</var>.

For the complete description of the header entry formats in the journal block, see [[Using system statistics#Header entries (Type 0)|Header entries (Type 0)]].

In pre-7.4.0 versions of Rocket <var class="product">Model 204</var>, each Online environment might produce a single merged journal daily. If an Online was bounced during the day, then the various journals for the day were merged into a single daily journal. Usually the daily merged journal contained records from only one run. The single merged journal could be used to automate media recovery, rather than manually assemble the recovery job journal concatenation.

Using the <var>SWITCH STREAM</var> command, a site can still prepare a daily merged journal. However, when the <var>SWITCH STREAM</var> command is used, each journal merged does not begin with the initialization of the Online. This means that no Type 12 records or M204.0061 initialization messages are included. Although <var class="product">Model 204</var> recovery, including media recovery, can successfully process these merged journals, various journal analysis utilities cannot.

===Using a SWITCH STREAM CCAJRNL command during extended quiesce===

In pre-7.1.0 releases, if you used the checkpoint quiesce feature, a switch to the next journal member at checkpoint quiesce could occur only when CCAJRNL was defined as a ring stream.

However, a switch at checkpoint quiesce may be desirable for all stream configurations of CCAJRNL: ring, parallel, concatenated, and GDG. The switch marks the point where the CCAJRNL data collected thus far is not needed in subsequent <var>REGENERATE</var> processing against files backed up during the quiesce. If file backups or dumps are taken during the checkpoint quiesce, only CCAJRNL data collected after checkpoint quiesce is useful for <var>REGENERATE</var> processing against those files.

A checkpoint is automatically taken if you issue a <code>SWITCH STREAM CCAJRNL</code> command while you are in extended quiesce, as shown in the following table:
<table>
<caption>SWITCH command within extended quiesce</caption>

<tr class="head">
<td>Step </td>
<td>Command issued </td>
<td>Purpose</td>
</tr>

<tr>
<td align="right">1 </td>
<td>CHECKPOINT SET EXTENDED QUIESCE </td>
<td>Enables extended quiesce</td>
</tr>

<tr>
<td align="right">2 </td>
<td>CHECKPOINT or automated checkpoint</td>
<td>

The next checkpoint, automated or command initiated, begins the extended quiesce

When the checkpoint is successful, the extended quiesce is entered. While in extended quiesce, you cannot issue a <var>CHECKPOINT</var> command. However, you can issue a <var>SWITCH STREAM</var> command, such as the following:
</td>
</tr>

<tr>
<td align="right">3</td>
<td>SWITCH STREAM CCAJRNL </td>
<td>When the checkpoint is successful, extended quiesce processing can begin for backups, SnapShots, or any activity that does not involve updating.</td>
</tr>

<tr>
<td align="right">4</td>
<td nowrap>CHECKPOINT END EXTENDED QUIESCE</td>
<td>Concludes extended quiesce. Should recovery be required due to a failure during extended quiesce, journals created prior to the <var>SWITCH STREAM</var> command will not be required, as the last checkpoint resides in the current CCAJRNL member.</td>
</tr>
</table>

This automated checkpoint functionality of <var>SWITCH STREAM CCAJRNL</var> applies only during checkpoint quiesce. The automated checkpoint functionality is not supported for CCAJLOG, CHKPOINT, or CHKPNTS.

===SWITCH STREAM limitations===

In order for a stream to be switched, there must be a target data set to switch to. If there is no target data set, the following message is issued:
M204.2712: MEMBER membername IS INELIGIBLE FOR SWITCHING


Consider the following example:
DEFINE STREAM CCAJRNL WITH SCOPE=SYSTEM PARALLEL=(JRNL1,JRNL2) MINAVAIL=2
DEFINE DATASET JRNL1 WITH SCOPE=SYSTEM DSN=CCAJRNL.JRNL1 OLD
DEFINE STREAM JRNL2 WITH SCOPE=SYSTEM GDG=J2 CONTROL=J2CTL
DEFINE DATASET J2 WITH SCOPE=SYSTME DSN=CCAJRNL.GDGBASE.JRNL2 CATALOG -
GEN=+1 CYL PRI 500
DEFINE DATASET J2CTL WITH SCOPE=SYSTEM DSN=CCAJRNL.GDGBASE.JRNL2.CTL OLD


Since data set <code>JRNL1</code> has no target data set for a switch, when the <code>JRNL1</code> data set is marked full, the number of available parallel stream members (<var>MINAVAIL</var>) drops to one, since only <code>JRNL2</code> now has space available. Since the number of available members is now less than <var>MINAVAIL</var>, the Online would stop with a "CCAJRNL full" message.

If before <code>JRNL1</code> fills, a <code>SWITCH STREAM CCAJRNL</code> command were issued, the following messages would be produced:
M204.2712: MEMBER JRNL1 IS INELIGIBLE FOR SWITCHING
M204.2712: STREAM JRNL2 IS BEING SWITCHED
M204.2712: STREAM CCAJRNL - NOT ALL MEMBERS SWITCHED


Member <code>JRNL1</code> was not switched. However, if <code>JRNL1</code> has not filled, the parallel stream will remain open because the number of available members (<var>MINAVAIL</var>) is still 2. Stream <code>JRNL2</code> always has a target data set to switch to since it is a GDG. Nevertheless, whenever <code>JRNL1</code> fills, the minimum available members will be less than <var>MINAVAIL</var>, the stream will be closed, and the run will terminate.

Because stream members are not locked before switch processing, and because all members are not switched at exactly the same time, the number of records in individual data sets of a parallel stream may not be identical. This is of no consequence to recovery or <var>REGENERATE</var>, but should be noted. However, the total number of records in each member is identical. 

Previously, you had to concatenate all journals into one data set or specify a concatenated <code>CCAGEN DD</code> statement.

===SWITCH STREAM command for concatenated streams===

The same limitation exists for the last member in a concatenated stream. Since there is no additional member to switch to, the following message is issued:
M204.2712: STREAM streamname IS INELIGIBLE FOR SWITCHING


If all members of a stream are switched, the following message is issued:
M204.2712: STREAM CCAJRNL SWITCHED VIA COMMAND


===Handling streams without records===

You cannot switch a stream member that contains no records. So in the previous case, if the first G1 stream member has just become full and the newly opened (second) GDG member contains zero records, then a <code>SWITCH STREAM CCAJRNL</code> command is not processed.

Since <code>J1</code> is ineligible, and <code>G1</code> (second member) is empty, no switch occurs. The messages issued are:
M204.2712: MEMBER J1 IS INELIGIBLE FOR SWITCHING
M204.2712: MEMBER G1 IS EMPTY AND CANNOT BE SWITCHED
M204.2712: SWITCH WAS UNSUCCESSFUL


===Recovery parameters===

Use the following recovery parameters when generating a journal:
<table>
<tr class="head">
<th>Parameter </th>
<th>Set </th>
<th>Specifies...</th>
<th>Comments</th>
</tr>

<tr>
<td>FRCVOPT </td>
<td>During file creation or with the <var>RESET</var> command </td>
<td>File recovery options</td>
<td>If the file is included in system or media recovery, do not use <code>FRCVOPT=X'04'</code>, which suppresses roll forward logging. </td>
</tr>

<tr>
<td>RCVOPT </td>
<td>On the JCL EXEC parameter or on User 0's parameter line </td>
<td>Type of information written to the journal</td>
<td>

X'08' writes the roll forward information that is required for system and media recovery to CCAJRNL.

X'09' also causes preimages to be written to the CHKPOINT data set for roll back recovery. Use this setting if you want to enable full recovery.
</td>
</tr>
</table>

===Writing error messages to the journal data set===

You can control which error messages or classes of error messages to store in CCAJRNL, CCAAUDIT, or CCAJLOG using <var>[[MSGCTL command|MSGCTL]]</var> command parameters.

===ERRMSGL: Setting the length of saved error messages===

The <var>[[ERRMSGL parameter|ERRMSGL]]</var> parameter provides the ability to set the number of bytes to use for saved error messages — messages returned by <var>[[$Errmsg]]</var> and <var>[[$Fsterr]]</var>. You can set <var>ERRMSGL</var> to any value from 80 to 256 — that length includes a count byte. The value is rounded up to an 8-byte multiple. For example, if you set <code>ERRMSGL=99</code>, it will be rounded to 104, that value is reduced by 1 for the count byte, thus allowing up to 103 characters of an error message to be saved.


====Server size requirements for saved error messages====

Increasing <var>ERRMSGL</var> increases the requirement of the fixed table size of a server. This may necessitate an increase in you <var>SERVSIZE</var> settings. The size requirement for <var>ERRMSGL</var> is:
3 * (ERRMSGL - 80)


For example, increasing <var>ERRMSGL</var> to its maximum of 256 would increase the fixed server requirement by <code>(3 * (256-80) -1)</code>, or 527 bytes. 

For a full update to the <var>SERVSIZE</var> formula, see [[Defining the runtime environment (CCAIN)#Calculating fixed table size|Calculating fixed table size]].

==Using the CCAJRNL data set==

During a production Online run, roll forward recovery information is written to the CCAJRNL data set. Additionally, a substantial amount of unformatted audit trail data is also written. When recovery is required and after roll back recovery has completed, that data set (during recovery its ddname is CCARF) is read and the roll forward information is extracted and used to reapply all committed updates up to the time of the system failure.

CCAJRNL collecting all roll forward and audit information
[[File:SM13ccaprint1_sep05.gif|468px]] 

==Performance efficiencies using CCAJRNL==

===Choosing whether to define CCAAUDIT===

<var class="product">Model 204</var> operates more efficiently using CCAJRNL without CCAAUDIT, because it is not also generating a separate audit trail. If you need printed information and your site does not maintain CCAAUDIT, you can extract the audit trail from CCAJRNL in a separate step using AUDIT204. 

If you need printed run information immediately upon completion of the job and you also need Roll Forward or Accounting facilities, create both the journal (CCAJRNL) and the audit trail (CCAAUDIT). 

You can use CCAJRNL in place of CCAAUDIT when you do not need audit trail data immediately following run termination.

===Allocating multiple journal buffers===

Setting <var>NJBUFF</var> to a value (<code>NSERVS + NSUBTKS + 1</code>) allocates multiple journal buffers and ensures that a free buffer is always available for the journal. In z/VM, the <var>NJBUFF</var> parameter is stacked in the EXEC that issues all the FILEDEFs.

===Using the CCAJLOG data set===

If you allocate CCAJLOG, the unformatted audit trail data is written to it and only roll forward recovery data is written to CCAJRNL. Reducing the number of records written to CCAJRNL improves recovery performance and also reduces the likelihood of filling CCAJRNL, which would result in run termination.
<ul>
<li>The number of buffers allocated for CCAJLOG is determined by the parameter, <var>[[NLBUFF parameter|NLBUFF]]</var>, which defaults to five. Only full blocks/buffers are written to CCAJLOG.</li>

<li>The size of these buffers is determined by the <var>BLKSIZE</var> parameter defined for the CCAJLOG data set which may be as large as 32K.</li>
</ul>

You can produce a formatted CCAAUDIT report from CCAJLOG using the AUDIT204 utility. In this case, the CCAJLOG is referenced via the ddname CCAJRNL. 

CCAJRNL collecting roll forward data; CCAJLOG collecting audit trail data
[[File:SM13ccaprint2_sep05.gif|466px]] 

====Defining the CCAJLOG stream====

You can define a CCAJLOG using any of the stream definitions: concatenate, parallel, ring, or GDG; see [[DEFINE STREAM command]].

===M204JLOG assembler exit===

The assembler exit, M204JLOG, can be invoked if linked in. This exit is initiated when a <var>SWITCH</var> command is issued against a CCAJLOG GDG stream. The exit may be any AMODE and need not be reentrant.

====Coding considerations====

On entry, the registers contain:

:R4 = A(GDG LIOD)
:R9 = A(new switch control record) (see CRD dsect)
:R13 = A(OSW save area)
:R14 = return address
:R15 = base address

<var class="product">Model 204</var> expects no output from the exit. All registers must be restored before return. If any <var class="product">Model 204</var> data structures are modified by the exit, unpredictable results may occur.
<blockquote class="note">
Note: If the user exit abends, <var class="product">Model 204</var> issues an error and produces a snap. This leaves <var class="product">Model 204</var> waiting for the switch to complete. At that point the switch will never complete, no further Online activity is possible, and the Online must be cancelled.

In addition, while the M204JLOG user exit is running, <var class="product">Model 204</var> cannot continue normal processing until a return from the exit is accomplished. For this reason, WAITs and I/Os inside the exit are strongly discouraged.
</blockquote>

====Sample M204JLOG Assembler exit====
M204JLOG CSECT
M204JLOG AMODE 31
M204JLOG TITLE 'TEST THE MODEL 204 CCAJLOG USER EXIT'
X10 EQU 10
X11 EQU 11
X12 EQU 12
X13 EQU 13
X14 EQU 14
X15 EQU 15
STM X14,X12,12(X13) SAVE CALLERS REGISTERS
LR X12,X15 ESTABLISH BASE REGISTER
USING M204JLOG,X12
LA X10,SAVEAREA GET A(LOCAL REGISTER SAVEAREA)
ST X10,8(,X13) CHAIN OUR SAVEAREA TO CALLERS
ST X13,SAVEAREA+4 CHAIN CALLERS SAVEAREA TO OURS
LA X13,SAVEAREA SET A(OUR SAVEAREA)
WTO 'M204JLOG EXIT INVOKED, DOING SOMETHING'
* ******************************************************************* *
* * CUSTOMERS MAY PLACE CODE HERE TO DO WHATEVER THEY DESIRE. * *
* ******************************************************************* *
WTO 'M204JLOG EXIT ENDING'
L X13,4(,X13) RESTORE CALLERS SAVEAREA ADDRESS
ST X10,16(X13) SET RETURN CODE (R15)
LM X14,X12,12(X13) RESTORE CALLERS REGISTERS
BR X14 RETURN TO CALLER
DS 0D
SAVEAREA DS 18F REGISTER SAVE AREA
LTORG
END


===Model 204 roll forward recovery with CCAJLOG===

<var class="product">Model 204</var> operates more efficiently during roll forward recovery, if you have defined CCAJLOG. This is because CCAJRNL now contains only roll forward recovery data; CCAJLOG contains unformatted CCAAUDIT data, which does not have to be read and ignored during the roll forward recovery since it has been removed from CCAJRNL.

===Separating transaction (CCAJRNL) and auditing (CCAJLOG) information===

Splitting audit trail records — messages and statistics — out from CCAJRNL and writing them to CCAJLOG improves recovery performance by reducing the size of CCAJRNL. This also reduces the likelihood of filling CCAJRNL. However, it does shift the possibility to CCAJLOG and if either CCAJRNL or CCAJLOG fills, the run comes down.

===Regenerating files using CCAJRNL and CCAJLOG===

Sending audit trail data to CCAJLOG also speeds up the <var>REGENERATE</var> processing, if that is required.

===Considerations for CCAJLOG===

By specifying CCAJLOG in the JCL or dynamically at the start of CCAIN, all messages and statistics are written to CCAJLOG. All recovery-type records are written to CCAJRNL. 
<ul>
<li>If you do not specify CCAJLOG, a CCAJRNL is maintained that collects recovery records, messages, and statistics. </li>

<li>If CCAJLOG is specified but the open fails, the run terminates initialization.</li>

<li>If CCAJLOG fills during a run, the run is terminated.</li>
</ul>

Set the <var>[[NLBUFF parameter|NLBUFF]]</var> parameter to specify the number of buffers to use for CCAJLOG. If you do not specify a value for <var>NLBUFF</var>, a default value of five is allocated. 

===Using the journals correctly===

If you create both a CCAJRNL file and a CCAJLOG file, you must use the CCAJLOG file as input to AUDIT204. And, you must continue to use the CCAJRNL file as input to <var>REGEN</var> and <var>RESTART</var> commands; otherwise, <var class="product">Model 204</var> issues one of the following messages:
M204:2515: CCAJRNL DATASET IS INVALID FOR AUDIT 204
M204:2515: CCAJLOG DATASET IS INVALID FOR {REGEN | RESTART}


If you create both a CCAJLOG and CCAJRNL and you use the CCAJRNL as input to AUDIT204, AUDIT204 issues the following message and stops processing:
NON-MESSAGE DATASET IS INVALID FOR CCAJRNL


Although UTILJ can handle a CCAJLOG data set, the utility will, of course, find only message and statistics type records in CCAJLOG. So, if you ask for recovery journal entries, type 1-6, the output is empty, since they do not exist on the CCAJLOG.

Because audit trail information is stored in CCAJLOG, if you have written a custom application for statistics reports, use CCAJLOG for input.

==CCAJRNL data set record layout==

The journal data set is composed of variable length records. Each record consists of a header, one or more journal entries, and a trailer. The format of the journal data set is subject to change with each release of <var class="product">Model 204</var>. 

===Journal entry format===

Journal entries contain audit trail, statistical, and control information, or information used for recovery. Statistics are recorded in the journal as fullword hexadecimal counters. Space is allocated in a given journal statistics entry for all possible statistics, even if they are not being kept. The values for statistics that are not maintained, or do not have relevance to the current configuration of <var class="product">Model 204</var>, are represented as hexadecimal zeros.

Each entry has the same general format: 
<table>
<tr class="head">
<th>Bytes</th>
<th>Contents</th>
</tr>

<tr>
<td align="right"> 0-1</td>
<td>Length</td>
</tr>

<tr>
<td align="right"> 2</td>
<td>Entry type</td>
</tr>

<tr>
<td> 3-n</td>
<td>Data</td>
</tr>
</table>

Offset 0 is a 2-byte hexadecimal field containing the length of the entry. (The only exception to this rule is the header entry, where the length is the length of the entire journal block.)

Offset 2 is a 1-byte field, which identifies the type of the entry: file, system, or user.

Offset 3 is a variable-length data portion. The size and layout depends upon the type of entry.

The following table summarizes the journal entry types, including formatting layouts and statistical information. Use the layout and statistics tables in [[Using system statistics]] for developing customized software to extract particular information from the journal data set. 
<table>
<caption>Summary of journal entry types</caption>
<tr class="head">
<th>Type</th>
<th>Journal record</th>
</tr>

<tr>
<td align="right"> X'00' </td>
<td>Header/Trailer</td>
</tr>

<tr>
<td align="right"> X'01' </td>
<td>Recovery entry</td>
</tr>

<tr>
<td align="right"> X'02' </td>
<td>Recovery entry</td>
</tr>

<tr>
<td align="right"> X'03' </td>
<td>Recovery entry</td>
</tr>

<tr>
<td align="right"> X'04' </td>
<td>Recovery entry</td>
</tr>

<tr>
<td align="right"> X'05' </td>
<td>Recovery entry</td>
</tr>

<tr>
<td align="right"> X'06' </td>
<td>Recovery entry</td>
</tr>

<tr>
<td align="right"> X'07' </td>
<td>Unused</td>
</tr>

<tr>
<td align="right"> X'08' </td>
<td>System statistics</td>
</tr>

<tr>
<td align="right"> X'09' </td>
<td>User statistics</td>
</tr>

<tr>
<td align="right"> X'0A' </td>
<td>File statistics</td>
</tr>

<tr>
<td align="right"> X'0B' </td>
<td>Discontinued audit trail text</td>
</tr>

<tr>
<td align="right"> X'0C' </td>
<td>Initialization entry</td>
</tr>

<tr>
<td align="right"> X'0D' </td>
<td>Possibly continued audit trail text</td>
</tr>

<tr>
<td align="right"> X'0E' </td>
<td>Timestamp</td>
</tr>

<tr>
<td align="right"> X'0F' </td>
<td>Merged journal brackets</td>
</tr>
</table>

===Number of lines in the journal data set===

The number of lines in the journal are controlled by the <var>CAUDIT</var>, <var>LAUDIT</var>, and <var>SYSOPT</var> parameters. 

====CAUDIT parameter====

The <var>[[CAUDIT parameter|CAUDIT]]</var> parameter controls physical input lines from a terminal, procedure, some IFAM arguments, or full-screen input. <var>CAUDIT</var> operates at physical line (card) level. It controls the auditing of input lines after line editing has been performed, but before line continuation is interpreted. 

<var>CAUDIT</var> is set on any user parameter line at the beginning of CCAIN, and can be reset by a user with system manager privileges who logs in with that user number. (<var>CAUDIT</var> is generally used only by Technical Support staff in special instances.)

====LAUDIT parameter====

The <var>[[LAUDIT parameter|LAUDIT]]</var> parameter controls logical input lines from a terminal or procedure, some IFAM arguments, and full screen information. <var>LAUDIT</var> is useful in reconstructing events that lead to a system crash. 

Set <var>LAUDIT</var> on any user parameter (<var>IODEV</var>) line or at the beginning of CCAIN. For example:
PAGESZ=6184,NUSERS=1,NSERVS=1,NFILES=20,
LENQTBL=15,LAUDIT=5, ...


<var>LAUDIT</var> can be reset by a user with system manager privileges who logs in with that user number.


====SYSOPT parameter====

The <var>[[SYSOPT parameter|SYSOPT]]</var> 32 option controls output of information that relates to system initialization or to an IFAM function call.


===Sizing the journal buffer===

In z/OS and z/VM only, you can specify the <var>NJBUFF</var> parameter on the EXEC statement to make journal entries of one user without interrupting other current users. Valid settings are the default <code>NJBUFF=1</code> or, to ensure the availability of a free buffer:
NJBUFF = NSERVS + NSUBTKS + 1


In z/OS only, if the setting of the NJBUFF parameter is greater than 1, the setting is automatically recalculated using the previous formula and the initial value of <var>NJBUFF</var> is used to define the number of concurrent I/O operations (NCP) for the journal data set. Sizing <var>NJBUFF</var> to the value calculated in the formula guarantees the optimal number of Network Control Programs (NCP) for the journal data set.

If you use the <var>NJBUFF</var> option, specify <code>BLKSIZE=6749</code> as the minimum journal buffer size to allow a full page to be written to a single journal buffer. The contents of a buffer are automatically written to CCAJRNL before the buffer is completely full.

Messages giving the number of journal buffers and the number of bytes allocated to the buffers are displayed at the end of the run.

===Managing space requirements for all operating systems===

The space requirement for CCAJRNL is reduced, if CCAJLOG is enabled. However, CCAJRNL must still be sized to prevent B37, D37, or E37 abends, which will terminate the run and require recovery to get files to a state of logical and physical consistency. The same applies to CCAJLOG: If it fills, the run terminates and recovery is required. Generous secondary extents allocated to these data set also help avoid overflow problems.

====Additional managing space requirement on z/OS====

At a z/OS site, the most comprehensive way to avoid data set full problems is to define both CCAJRNL and CCAJOG as generation data groups (GDGs). See [[Configuring checkpoint and journal data streams#Perpetual journaling for z/OS|Perpetual journaling for z/OS]].

==Model 204 statistics==

A statistic is written to CCAAUDIT only if its value is nonzero. However, all statistics, even those with zero values, are written to CCAJRNL (or CCAJLOG). 

===Audit trail and journal statistics lines===

The statistics generated on audit trail lines are valuable in a study of the performance of an individual user or of the <var class="product">Model 204</var> system as a whole. The effect of configuration changes within <var class="product">Model 204</var> and with other jobs in the operating system can be determined by comparing statistics gathered in <var class="product">Model 204</var> runs.
<ul>
<li>Statistics described as percentages are multiplied by 10 (a value printed as 1000 represents 100 percent). </li>

<li>Statistics described as averages are multiplied by 1000 (1000 represents 1.000).</li>
</ul>

===Output lines===

Statistics for each user and file active during a particular run are written to the journal and audit trail files in output lines that begin with <code>ST $$$</code>. The output lines are written in groups of related lines that include: 
<ul>
<li>User lines, which you can monitor to identify active users and to help determine if individual applications are efficiently implemented</li>

<li>File lines</li>

<li>System lines, which you can watch — together with file lines — to signal shifting loads on the CPU, disks, and terminals </li>
</ul>

The type of line written — user, file, or system — is specified by the value of the first parameter after the journal header.

===Identifying subtypes===

The subtype — final, partial, performance, or since-last — within each type is specified by the value of the second parameter after the journal header. In the audit trail, the subtype is indicated by <code>USERID=user-id</code> (user statistics), <code>FILE=filename</code> (file statistics), and <code>SYSTEM=Model-204-version</code> (system statistics). 

Within each major type of statistics line, subtypes are produced under specified conditions: some are always produced, others are optional. Optional subtypes are produced if the appropriate parameters are set during system initialization. See [[Tracking system activity (CCAJRNL, CCAAUDIT, CCAJLOG)#Setting the NSUBTKS parameter|Setting the NSUBTKS parameter]]. 

==Monitoring statistics==

The <var class="product">Model 204</var> statistics that you can monitor are introduced in [[Using system statistics]]. The statistics are presented in alphabetical order with their stated purpose, followed by tables that identify their position in various layouts.

You can monitor statistics using one or more of the following methods: 
<ul>
<li>Print out the audit trail. </li>

<li>View formatted or unformatted displays of all nonzero cumulative statistics for active users — individual, specified groups, and all users — and system activities.</li>

<li>Use the AUDIT204 or UTILJ utility program to extract and summarize statistics lines from the journal data set. See [[#AUDIT204 utility|the AUDIT204 utility]] and [[System and media recovery#Using the UTILJ utility|Using the UTILJ utility]]
</li>

<li>Write optional records to the System Management Facilities (SMF) data set; see [[Using system statistics#System Management Facilities|System Management Facilities]]. </li>
</ul>

===Setting the NSUBTKS parameter===

Gathering partial or performance statistics lines requires a <var class="product">Model 204</var> pseudo subtask. <var class="product">Model 204</var> uses pseudo subtasks to perform actions that must be done regularly but that cannot be assigned to a specific user. To accommodate partial and performance statistics lines you might need to increase the <var>NSUBTKS</var> parameter on User 0's parameter line, which controls the maximum number of [[Controlling system operations (CCAIN)#Pseudo subtasks|pseudo subtasks]] that can be allocated. 

===Setting parameters to collect certain statistics===

You must set various parameters to collect certain statistics. The following table lists the statistics and the corresponding parameter(s):
<table>
<caption>Parameters to set to collect certain statistics</caption>
<tr class="head">
<th>Statistic </th>
<th>Parameter to set to nonzero</th>
</tr>

<tr>
<td>BLKCFRE </td>
<td>CFRJRNL and CFRLOOK</td>
</tr>

<tr>
<td>BLKI</td>
<td>RPTCNT and SMPLTIM</td>
</tr>

<tr>
<td>BLKO</td>
<td>RPTCNT and SMPLTIM</td>
</tr>

<tr>
<td>BLKRLK </td>
<td>CFRJRNL and CFRLOOK</td>
</tr>

<tr>
<td>LONGUPDTIME(MS)</td>
<td>MAXUD</td>
</tr>

<tr>
<td>LONGUPDTS</td>
<td>MAXUD</td>
</tr>

<tr>
<td>PNDGTIME</td>
<td>DKUPDTWT</td>
</tr>

<tr>
<td>REDY </td>
<td>RPTCNT and SMPLTIM</td>
</tr>

<tr>
<td>RUNG </td>
<td>RPTCNT and SMPLTIM</td>
</tr>

<tr>
<td>SMPLS</td>
<td>RPTCNT and SMPLTIM</td>
</tr>

<tr>
<td>SWPG</td>
<td>RPTCNT and SMPLTIM</td>
</tr>

<tr>
<td>USRS</td>
<td>RPTCNT and SMPLTIM</td>
</tr>

<tr>
<td>WTCFR </td>
<td>CFRJRNL and CFRLOOK</td>
</tr>

<tr>
<td>WTRLK </td>
<td>CFRJRNL and CFRLOOK</td>
</tr>

<tr>
<td>WTSV </td>
<td>RPTCNT and SMPLTIM</td>
</tr>
</table>

==Audit trail format==

Whether printed to CCAAUDIT, either directly from ONLINE/BATCH204 (with two exceptions), or from AUDIT204,
the format of an audit trail line is shown below. The two exceptions are:

<ul>
<li>
The YEARFORM 4 parameter is not available in ONLINE/BATCH204; it is only available in AUDIT204.
This means that a 4-digit year cannot be printed in a CCAAUDIT generated by ONLINE/BATCH204.
</li>
<li>
The TIMEHH parameter is not available in ONLINE/BATCH204; it is only available in AUDIT204.
This means that the time stamp with hundredths of a second cannot be printed in a CCAAUDIT generated
by ONLINE/BATCH204.
</li>
</ul>

yydddhhmmss seq sssss uuuuu tt audit-trail-text ...
or
yydddhhmmsshu seq sssss uuuuu tt audit-trail-text ... '''(if TIMEHH was specified)'''


Where:
<ul>
<li><var class="term">yyddd</var> is the Julian year and day.</li>

<li><var class="term">hhmmss</var> is the time of day in hours, minutes, and seconds.</li>
<li><var class="term">hhmmsshu</var> is the time of day in hours, minutes, seconds, hundredths.</li>

<li><var class="term">seq</var> sequence number is a counter to distinguish lines produced in the same second.
</li>

<li><var class="term">sssss</var> is the 5-digit server number the user is currently using. (Leading zeros are suppressed.)</li>

<li><var class="term">uuuuu</var> is the 5-digit user number. (Leading zeros are suppressed.)</li>

<li><var class="term">tt</var> is code for the type of audit trail line. The tt codes are shown in the
"Types of audit trail lines" table, below.</li>
</ul>

====Example 1, CCAAUDIT output direct from ONLINE====

'''COLUMN: These three lines'''
'''2 15 18 23 25 are not present'''
'''DATE/TIME SEQ# S# USR# TYPE in actual output'''

23256145406 0 0 0 RK ... START VERSION =7.8.0A SMF SYSTEM ID = RS26 XX-
23256145406 1 0 0 XX
23256145406 2 0 0 AD /// **************************************************************************
23256145406 3 0 0 AD /// * Model 204 is proprietary to and a registered trademark of Rocket *
23256145406 4 0 0 AD /// * Software, Inc. All title, copyright and other proprietary rights shall *
23256145406 5 0 0 AD /// * be retained by Rocket Software, Inc. Model 204 has been licensed by *
23256145406 6 0 0 AD /// * this customer and the use and protection of Model 204 is governed by *
23256145406 7 0 0 AD /// * the license agreement between the customer and Rocket Software, Inc. *
23256145406 8 0 0 AD /// * *
23256145406 9 0 0 AD /// * Copyright (C) 2016 Rocket Software, Inc. *
23256145406 10 0 0 AD /// * or its affiliates *
23256145406 11 0 0 AD /// **************************************************************************
23256145406 12 0 0 AD /// M204.0060: Model 204 initialization. Version = 7.8.0A 2020/03/06 14.12, RSQL level = 7.8.0A 2020/02/-
23256145406 13 0 0 XX 12 08.14
23256145406 14 0 0 AD /// M204.0061: SMF system ID = RS26, job name = PSTPC780, step name = TPCBV780, job step = , JES ID = J-
23256145406 15 0 0 XX 0130887
23256145406 16 0 0 AD /// M204.0062: Execute parameters: RCVOPT=9,NJBUFF=115,SYSOPT=139,SYSOPT2=64,LIBUFF=6000,XMEMOPT=3,SIRFU-
23256145406 17 0 0 XX NC=1


====Example 2, CCAAUDIT output from AUDIT204====

AUDIT204 Utility - Version 7.8.0A, Assembly date/time: 20200229 22.08
Date/time of run: 09/07/2023 12:56:01
CCAJRNL or CCAJLOG version: 7.8.0A
Zaps: 78Z7759 78Z7891 78Z7973 78Z7975 78Z8066 78Z8075

'''COLUMN: These three lines'''
'''2 18 24 30 32 are not present '''
'''DATE/TIME SEQ# SERV# USER# TYPE in actual output'''

'''FORMAT TIMEHH'''
2216613441420 0 0 0 RK ... START VERSION =7.8.0A SMF SYSTEM ID = RS26 XX-
2216613441420 1 0 0 XX
2216613441420 2 0 0 AD /// **************************************************************************
2216613441420 3 0 0 AD /// * Model 204 is proprietary to and a registered trademark of Rocket *
2216613441420 4 0 0 AD /// * Software, Inc. All title, copyright and other proprietary rights shall *
2216613441420 5 0 0 AD /// * be retained by Rocket Software, Inc. Model 204 has been licensed by *
2216613441420 6 0 0 AD /// * this customer and the use and protection of Model 204 is governed by *
2216613441420 7 0 0 AD /// * the license agreement between the customer and Rocket Software, Inc. *
2216613441420 8 0 0 AD /// * *
2216613441420 9 0 0 AD /// * Copyright (C) 2016 Rocket Software, Inc. *
2216613441420 10 0 0 AD /// * or its affiliates *
2216613441420 11 0 0 AD /// **************************************************************************
2216613441420 12 0 0 AD /// M204.0060: Model 204 initialization. Version = 7.8.0A 2020/03/06 14.12, RSQL level = 7.8.0A 2-
2216613441420 13 0 0 XX 020/02/12 08.14
2216613441420 14 0 0 AD /// M204.0061: SMF system ID = RS26, job name = PSTPC780, step name = TPCBV780, job step = , JES-
2216613441420 15 0 0 XX ID = J0536896
2216613441420 16 0 0 AD /// M204.0062: Execute parameters: RCVOPT=9,NJBUFF=115,SYSOPT=139,SYSOPT2=64,LIBUFF=6000,XMEMOPT=-
2216613441420 17 0 0 XX 3,SIRFUNC=1


====Example 3, CCAAUDIT output from AUDIT204====

AUDIT204 Utility - Version 7.8.0A, Assembly date/time: 20200229 22.08
Date/time of run: 09/07/2023 14:09:46
CCAJRNL or CCAJLOG version: 7.8.0A
Zaps: 78Z7759 78Z7891 78Z7973 78Z7975 78Z8066 78Z8075

'''COLUMN: These three lines'''
'''2 18 24 30 32 are not present '''
'''DATE/TIME SEQ# SERV# USER# TYPE in actual output'''

'''FORMAT'''
'''YEARFORM 4'''
2022166134414 0 0 0 RK ... START VERSION =7.8.0A SMF SYSTEM ID = RS26 XX-
2022166134414 1 0 0 XX
2022166134414 2 0 0 AD /// **************************************************************************
2022166134414 3 0 0 AD /// * Model 204 is proprietary to and a registered trademark of Rocket *
2022166134414 4 0 0 AD /// * Software, Inc. All title, copyright and other proprietary rights shall *
2022166134414 5 0 0 AD /// * be retained by Rocket Software, Inc. Model 204 has been licensed by *
2022166134414 6 0 0 AD /// * this customer and the use and protection of Model 204 is governed by *
2022166134414 7 0 0 AD /// * the license agreement between the customer and Rocket Software, Inc. *
2022166134414 8 0 0 AD /// * *
2022166134414 9 0 0 AD /// * Copyright (C) 2016 Rocket Software, Inc. *
2022166134414 10 0 0 AD /// * or its affiliates *
2022166134414 11 0 0 AD /// **************************************************************************
2022166134414 12 0 0 AD /// M204.0060: Model 204 initialization. Version = 7.8.0A 2020/03/06 14.12, RSQL level = 7.8.0A 2-
2022166134414 13 0 0 XX 020/02/12 08.14
2022166134414 14 0 0 AD /// M204.0061: SMF system ID = RS26, job name = PSTPC780, step name = TPCBV780, job step = , JES-
2022166134414 15 0 0 XX ID = J0536896
2022166134414 16 0 0 AD /// M204.0062: Execute parameters: RCVOPT=9,NJBUFF=115,SYSOPT=139,SYSOPT2=64,LIBUFF=6000,XMEMOPT=-
2022166134414 17 0 0 XX 3,SIRFUNC=1


====Example 4, CCAAUDIT output from AUDIT204====

AUDIT204 Utility - Version 7.8.0A, Assembly date/time: 20200229 22.08
Date/time of run: 09/13/2023 13:34:45
CCAJRNL or CCAJLOG version: 7.8.0A
Zaps: 78Z7759 78Z7891 78Z7973 78Z7975 78Z8066 78Z8075

'''COLUMN: These three lines'''
'''2 20 26 32 34 are not present '''
'''DATE/TIME SEQ# SERV# USER# TYPE in actual output'''

'''FORMAT TIMEHH'''
'''YEARFORM 4'''
202216613441420 0 0 0 RK ... START VERSION =7.8.0A SMF SYSTEM ID = RS26 XX-
202216613441420 1 0 0 XX
202216613441420 2 0 0 AD /// **************************************************************************
202216613441420 3 0 0 AD /// * Model 204 is proprietary to and a registered trademark of Rocket *
202216613441420 4 0 0 AD /// * Software, Inc. All title, copyright and other proprietary rights shall *
202216613441420 5 0 0 AD /// * be retained by Rocket Software, Inc. Model 204 has been licensed by *
202216613441420 6 0 0 AD /// * this customer and the use and protection of Model 204 is governed by *
202216613441420 7 0 0 AD /// * the license agreement between the customer and Rocket Software, Inc. *
202216613441420 8 0 0 AD /// * *
202216613441420 9 0 0 AD /// * Copyright (C) 2016 Rocket Software, Inc. *
202216613441420 10 0 0 AD /// * or its affiliates *
202216613441420 11 0 0 AD /// **************************************************************************
202216613441420 12 0 0 AD /// M204.0060: Model 204 initialization. Version = 7.8.0A 2020/03/06 14.12, RSQL level = 7.8.0A-
202216613441420 13 0 0 XX 2020/02/12 08.14
202216613441420 14 0 0 AD /// M204.0061: SMF system ID = RS26, job name = PSTPC780, step name = TPCBV780, job step = , J-
202216613441420 15 0 0 XX ES ID = J0536896
202216613441420 16 0 0 AD /// M204.0062: Execute parameters: RCVOPT=9,NJBUFF=115,SYSOPT=139,SYSOPT2=64,LIBUFF=6000,XMEMOP-
202216613441420 17 0 0 XX T=3,SIRFUNC=1



The following table lists the code and purpose of the audit trail lines:

<table>
<caption>Types of audit trail lines</caption>
<tr class="head">
<th>Code</th>
<th>Displays...</th>
</tr>

<tr>
<td>AD</td>
<td>Special information about the run, job step return code, status of <var class="product">Model 204</var> files, user or the password table, the SNA Communications Server (formerly VTAM) Interface, or messages sent from an HLI program via the IFERR call.</td>
</tr>

<tr>
<td>CI</td>
<td>Physical input line from a user's terminal or some IFAM arguments.</td>
</tr>

<tr>
<td>CP</td>
<td>Physical input line from a procedure.</td>
</tr>

<tr>
<td>CS</td>
<td>Physical line of full-screen input (see LS below).</td>
</tr>

<tr>
<td>ER</td>
<td>Error message sent to the user.</td>
</tr>

<tr>
<td>LI</td>
<td>Logical input line from a user's terminal or some HLI arguments.</td>
</tr>

<tr>
<td>LP</td>
<td>Logical input line from a procedure.</td>
</tr>

<tr>
<td>LR</td>
<td>Read images from a terminal.</td>
</tr>

<tr>
<td>LS</td>
<td>Full-screen information. For a screen, each line lists one input value. For a menu, the line provides the menu selection number.</td>
</tr>

<tr>
<td>MS</td>
<td>Informational message sent to the user (not an error).</td>
</tr>

<tr>
<td>OI</td>
<td>Input line from the operator's console.</td>
</tr>

<tr>
<td>OO</td>
<td>Message sent to the operator's console.</td>
</tr>

<tr>
<td>RK</td>
<td>Special information that relates to system initialization or to the record of a call to the following types of function:
<ul>
<li>Connect★</li>

<li>HLI</li>

<li>MQ/204</li>

<li>PQO</li>

<li>SQL</li>

<li>UL/DB2</li>
</ul>
</td></tr>

<tr>
<td>QT</td>
<td>Lines of SQL statement level processing </td>
</tr>

<tr>
<td>ST</td>
<td>Utilization statistics (see [[Using system statistics]]).</td>
</tr>

<tr>
<td>US</td>
<td>Line of special information directed to the audit trail by means of the SOUL <var>Audit</var> statement.</td>
</tr>

<tr>
<td>XX</td>
<td>Continuation of the previous line.</td>
</tr>
</table>

==Generating an audit trail==

===Overview of audit trail parameters===

An audit trail is generated if: 
<ul>
<li>The <var>SYSOPT</var> parameter includes the 128 specification</li>

<li>CCAAUDIT DD statement</li>
</ul>

The <var>[[LAUDPROC parameter|LAUDPROC]]</var> parameter controls the length of procedure names that appear in since-last statistic lines of the audit trail. You can reset <var>LAUDPROC</var> to a low or high value. A low value conserves memory. A high value captures long procedure names. 

===z/VSE and the audit trail===

In a z/VSE environment, activate the audit trail by incorporating the following specifications into the JCL:
<ul>
<li>You must set UPSI to <code>1xxxxxxx</code> (<code>SYSOPT=128</code>).</li>

<li>You must write the audit trail file to either a disk device or a print device:
<ul>
<li>Assign a disk device using a DLBL and EXTENT statement for file name <code>CCAUDIT</code> (retention 0 is recommended).</li>

<li>Assign a print device using symbolic unit <code>SYS008</code>. (You cannot assign <code>SYS008</code> to the same physical device as SYSLST.)

If the DLBL and EXTENT for CCAUDIT are provided in the JCL, the audit trail is written to disk regardless of the assignment of <code>SYS008</code>.</li>
</ul></li>
</ul>

The following example shows a job stream for an <var>ONLINE</var> configuration with the audit trail on disk:
// JOB ONLINE
...
// DLBL CCAUDIT,'audit trail file-id',0
// EXTENT SYSnnn,balance of extent information
// ASSGN SYSnnn,X'cuu'
...
// UPSI 10000000
// EXEC ONLINE, SIZE=AUTO
...
/&


After the audit trail has been written to disk, you can print it using the UTLA utility program supplied with the <var class="product">Model 204</var> DBMS.

Use the following JCL:
// JOB UTLA PRINT MODEL 204 AUDIT TRAIL
// DLBL M204LIB,'M204.PROD.LIBRARY'
// EXTENT SYSnnn,...
// LIBDEF PHASE.SEARCH=M204LIB.V411
// DLBL CCAUDIT,'audit trail file-id'
// EXTENT SYSnnn,balance of extent information
// ASSGN SYSnnn,X'cuu'
// ASSGN SYS005,SYSLST
// EXEC UTLA,SIZE=AUTO
/&


===z/VM and the audit trail===

In the z/VM/CMS environment, define CCAAUDIT as one of the following:
<ul>
<li>CMS file:
FILEDEF CCAAUDIT DISK ONLN CCAAUDIT A</li>

<li>Service machine virtual printer:
FILEDEF CCAAUDIT PRINTER</li>
</ul>

==AUDIT204 utility==

The AUDIT204 utility program produces the following reports, all of which are written to CCAAUDIT:
<ul>
<li>Complete or partial audit trail from a journal — CCAJRNL or CCAJLOG, as ddname CCAJRNL — produced by a <var class="product">Model 204</var> run</li>

<li>Report based on statistics that appear on user logout and partial lines or file closed and partial lines</li>

<li>Statistical analysis of the evaluation of SOUL requests </li>
</ul>

The format of AUDIT204 reports is determined by AUDIT204 commands and parameters you enter in:
<ul>
<li>z/OS CCAIN data stream</li>

<li>z/VM (CMS) AUDIT204 CCAIN file</li>

<li>DOS SYSIPT statement</li>
</ul>

The basic AUDIT204 input commands are:
<table>
<tr class="head">
<th>AUDIT204 command </th>
<th>For... </th>
</tr>

<tr>
<td>ANALYZE </td>
<td>Statistical analysis of the evaluation of User Language requests </td>
</tr>

<tr>
<td>FORMAT </td>
<td>Printed audit trail</td>
</tr>

<tr>
<td>REPORT </td>
<td>Breakdown of user and file statistics lines containing optional price calculations</td>
</tr>
</table>

===Input to AUDIT204===

Input to AUDIT204 is free form, located in columns 1-71. The following rules apply:
<ul>

<li>The command line may have one parameter and its subparameters.</li>

<li>Type each subsequent parameter on a separate line.</li>

<ul>
<li>Use blanks to separate subparameters.</li>
</ul>

<li>You can type parameters for a single command in any order.</li>

<li>You can add subparameters for some parameters (PRICE and RENAME) by naming the subparameters in the form of character strings:
<ul>
<li>If a name contains a blank or a single quotation mark, you must enclose the name in single quotation marks.</li>

<li>Use double quotation marks within the name.</li>

<li>Use blanks around the equal signs in the PRICE and RENAME parameters.</li>

<li>Use blanks to separate subparameters.</li>

<li>If more than one line is required for the subparameters, place a nonblank character in column 72 or repeat the parameter on a new line. </li>
</ul></li>

<li>Any characters appearing in columns 73-80 are ignored. </li>

<li>You can repeat any parameter. </li>

<li>Precede each comment by an asterisk (<tt>*</tt>) in column 1.</li>

<li>The effect of parameters containing lists of subparameters is cumulative. </li>

<li>The last value of parameters without subparameter lists is the value used. </li>
</ul>

===ANALYZE command===

The <var>ANALYZE</var> command produces a statistical analysis report on the evaluation of SOUL requests. The complete report comprises an analysis for each individual account and the system as a whole. 

Since-last evaluation lines calculate the mean and standard deviation for each since-last statistic:
<table>
<tr class="head">
<th>Measure </th>
<th>Represents... </th>
</tr>

<tr>
<td>Mean </td>
<td>Center of a set of data points (usually referred to as the average value of the set), obtained by summing the values and dividing by the number of values.</td>
</tr>

<tr>
<td nowrap>Standard deviation </td>
<td>How spread out the data is around the center. In particular, it is useful to know whether the data is tightly clustered around the mean, or more dispersed.

A small standard deviation indicates that any given value is likely to be close to the mean, and a large standard deviation implies that a value is more likely to be far away from the mean. 
</td>
</tr>
</table>

You can obtain more information about the mean and the standard deviation from any standard statistics textbook.

====Syntax====

Use the following syntax for the <var>ANALYZE</var> command:
ANALYZE [USERID | NOUSERID] [USERIDS userid1...useridn]


or
ANALYZE [ACCOUNT | NOACCOUNT] [ACCOUNTS account1...accountn]
[parameters]


Where:

Use the following parameters with the <var>ANALYZE</var> command:
<table>
<tr class="head">
<th>Parameter </th>
<th>Specifies...</th>
</tr>

<tr>
<td><var>ACCOUNT</var>
or <var>NOACCOUNT</var></td>
<td>Whether or not to do an individual account analysis. The <var>ACCT</var> or <var>NOACCT</var> parameters are equivalent to <var>ACCOUNT</var> or <var>NOACCOUNT</var>, respectively. </td>
</tr>

<tr>
<td><var>ACCOUNTS</var> </td>
<td>Login account name(s) to list in the analysis report.

Reports are produced only for the specified accounts and only the since-last evaluation lines for those accounts that are included in the systemwide report.

Specifying <var>ACCOUNTS</var> sets the <var>ACCOUNT</var> parameter when neither <var>ACCOUNT</var> nor <var>NOACCOUNT</var> was specified.
</td>
</tr>

<tr>
<td><var>OMIT name1 name2...</var> </td>
<td>Since-last statistic(s) to list, but omit from the analysis report. The report contains all since-last statistics that are not explicitly omitted. Specifying file or user statistics will generate an error message and terminate the ANALYZE.</td>
</tr>

<tr>
<td nowrap><var>RENAME name=newname</var> </td>
<td>New names to since-last statistics as column headings for an analysis report.</td>
</tr>

<tr>
<td><var>TIME [yydddhhmmss / yydddhhmmss | cyydddhhmmss / cyyddhhmmss]</var></td>
<td>Time range from which since-last evaluation lines are taken.</td>
</tr>

<tr>
<td><var>SYS</var> (the default)
 or <var>NOSYS</var> </td>
<td>Whether or not to do a systemwide analysis using since-last evaluation lines of accounts for which an individual analysis is done. </td>
</tr>

<tr>
<td><var>USERID</var> (the default)
 or <var>NOUSERID</var> </td>
<td>Performing or suppressing an individual user ID analysis. Totals for a systemwide analysis are still accumulated if <var>NOUSERID</var> is specified.</td>
</tr>

<tr>
<td><var>USERIDS</var> </td>
<td>User(s) for which analysis is requested.

The <var>USERIDS</var> keyword is required in addition to the <var>USERID</var> keyword. If neither <var>USERID</var> nor <var>NOUSERID</var> has been specified, specifying <var>USERIDS</var> sets the <var>USERID</var> parameter.

Reports are produced only for the specified users and only the since-last evaluation lines for those users who are included in the systemwide report. 

AUDIT204 uses the values specified in the <var>USERID</var> parameter as a pattern and finds all values that match. For example, <code>USERIDS NANCY KATHY</code> is equivalent to <code>REPORT USERID USERIDS NANCY* KATHY*</code>.</td></tr>
</table>

===FORMAT command===

<var>FORMAT</var> prints an audit trail (CCAAUDIT) from CCAJRNL or CCAJLOG. 

====Syntax====
FORMAT TIME {yydddhhmmss/yydddhhmmss | cyydddhhmmss/cyydddhhmmss}
TIMEHH
TYPE type1
USER usernum
USERID userid
YEARFORM {2 | 4}


Where:

You use the following parameters with the <var>FORMAT</var> command:
<table>
<tr class="head">
<th>Parameter </th>
<th>Specifies...</th>
</tr>

<tr>
<td><var>TIME</var> </td>
<td>Time range to print. The format of the time specification corresponds to the time stamp printed with each audit trail line.

You can specify start and end times in either order. If either time is out of the range covered by the journal, it is corrected to match the actual start or end of the journal. 

If both specified times are before and after the period covered by the journal, nothing is printed.
<ul>
<li><var class="term">yyddd</var> is the year and Julian date; <var class="term">cyyddd</var> is the century, year and Julian date (0=20th century, 1=21st century).</li>

<li><var class="term">hhmmss</var> is time based on a 24-hour clock. </li>
</ul>
NOTE: TIME may be specified with no time range or with a time range in the form noted above. No time range selects the entire journal/jlog for printing.
</td></tr>

<tr>
<td><var>TIMEHH</var> </td>
<td>Indicates that timestamps, printed at the beginning of each line of output, should include hundredths of a second. Requires no other arguments.
NOTE: This parameter and the 78 version of AUDIT204 may be used against a 77 or 78 CCAJRNL or CCAJLOG.
NOTE: TIMEHH may be specified with no time range or with a time range in the form noted above. No time range selects the entire journal/jlog for printing.
</td>
</tr>

<tr>
<td><var>TYPE</var> </td>
<td>Type of lines to print, such as AD or MS (see the [[#Example|"Types of audit trail lines" table]]).</td>
</tr>

<tr>
<td><var>USER</var> </td>
<td>User for whom the printed audit trail lines are generated. Specify user numbers with or without leading zeros. </td>
</tr>

<tr>
<td><var>USERID</var> </td>
<td>One- to ten-character name that identifies the <var class="product">Model 204</var> user about whom the printed audit trail lines are generated.</td>
</tr>

<tr>
<td><var>YEARFORM</var></td>
<td>Two- or four-digit year output. The default is 2.</td>
</tr>
</table>

====Example====

The options specified in the following example restrict the printing of the audit trail to <code>MS</code> (message) lines for <code>USER 01</code> created on September 22, 1998 between 10:41 A.M. and 10:45 A.M.:
FORMAT TYPE MS, ER
TIME 98265104100/98265104500
USER 01


====Usage====

The <var>FORMAT</var> command can be used against a CCAJRNL or CCAJLOG data set. Examine the code examples that begin in [[#Samples of a z/OS job stream|Samples of a z/OS job stream]]. 

===REPORT command===

The <var>REPORT</var> command prints user and file statistics in a tabular format and computes costs by account or by file for billing purposes. AUDIT204 reports have a two-line header, as shown in the following example, that reflect the circumstances of your site. 
AUDIT204 UTILITY - VERSION 7.6.0D
DATE/TIME OF RUN: 10/11/2016 12:25:50


====Syntax====
REPORT type [parameters]


Where:
<ul>
<li><var class="term">type</var> is a subcommand that specifies the type of report to print:
<table>
<tr class="head">
<th>Subcommand </th>
<th>Specifies printing a report from...</th>
</tr>

<tr>
<td><var>ACCOUNT</var> </td>
<td>User statistics for all accounts </td>
</tr>

<tr>
<td><var>ACCOUNTS</var> account1 account2 ...</td>
<td>User statistics for specified accounts</td>
</tr>

<tr>
<td><var>USERID</var> </td>
<td>User statistics for all users</td>
</tr>

<tr>
<td><var>USERID USERIDS user1 user2 ...</var> </td>
<td>User statistics for users listed</td>
</tr>

<tr>
<td><var>FILE</var> </td>
<td>File statistics for all files</td>
</tr>

<tr>
<td><var>FILE FILES fname1 fname2 ...</var> </td>
<td>File statistics for files listed</td>
</tr>

</table></li>

<li><var class="term">parameters</var> is one or more of
the following, which can be used with <var>USERID</var>, <var>ACCOUNT</var>, or <var>FILE</var>:
<table>
<tr class="head">
<th>Parameter </th>
<th>Specifies...</th>
</tr>

<tr>
<td><var>IND</var> (the default)
 or <var>NOIND</var> </td>
<td>Printing or not printing individual lines. Totals are still accumulated if <var>NOIND</var> is specified.</td>
</tr>

<tr>
<td><var>OMIT</var> </td>
<td>Statistic(s) to omit from the report. You must enter the actual name of the statistic, not what appears in a column header in a report. Only file statistics are valid for FILE reports and only since-last and logout stats are valid for USERID reports. See [[Using system statistics#Description of statistics|Description of statistics]] for an alphabetical listing of statistics.</td>
</tr>

<tr>
<td><var>PARTIAL</var>
 or <var>NOPARTIAL</var> </td>
<td>Generation of partial or complete statistics lines. Use:
<ul>
<li><var>PARTIAL</var> when a report is generated from a journal that did not terminate successfully.</li>

<li><var>NOPARTIAL</var> to avoid processing overhead, when a complete journal is available.</li>
</ul>
</td></tr>

<tr>
<td><var>PRICE</var> </td>
<td>Dollar charge up to five decimal places to any statistic. Decimal point, and leading and trailing zeros are optional. For example:
PRICE CPU=0.05 DKRD=.03 DKWR=.035
</td></tr>

<tr>
<td><var>RENAME</var> </td>
<td>Column heading names up to nine characters without truncation. The new name completely replaces the old name and must be used if name is specified on other parameters.</td></tr>

<tr>
<td><var>TIME</var> </td>
<td>Time range for statistics line reporting. One of the following formats is required:
<ul>
<li><var class="term">yydddhhmmss</var><tt>/</tt><var class="term">yydddhhmmss</var> </li>

<li><var class="term">cyydddhhmmss</var><tt>/</tt><var class="term">cyydddhhmmss</var> </li>
</ul>
</td></tr>

<tr><td nowrap><var>TOTAL</var> (the default)
 or <var>NOTOTAL</var> </td>
<td>Totalling or suppression of totalling for individual statistics and costs. </td>
</tr>
</table></li>
</ul>

====Example====

Totals are printed after individual statistics lines if both <var>IND</var> and <var>TOTAL</var> are in effect. Each line must contain only one parameter, as in the following examples:
REPORT USERID NOIND
PARTIAL
TIME yydddhhmmss/yydddhhmmss
RENAME name=newname
NOTOTAL
USERIDS account

REPORT FILE FILES fname1 fname2 fname3 ...
OMIT statistic
PRICE statistic=xx.xx


The subkeywords <var>ACCOUNTS</var>, <var>FILES</var>, and <var>USERIDS</var> can be used with <var>REPORT</var> subcommands <var>ACCOUNT</var>, <var>FILE</var>, and <var>USERID</var> as in the following examples:
REPORT USERID USERIDS JAMES STEVE SANDRA
ACCOUNT ACCOUNTS JAMES STEVE SANDRA
FILE FILES CLIENTS VEHICLES DAILY

Note: The <var>REPORT</var> command for AUDIT204 can process only a single journal: CCAJRNL. You cannot use against a CCAJOG file.

==Using the AUDIT204 utility==

===CCAJRNL and CCAJLOG data sets as input to utilities===

When you need a CCAAUDIT report, use the CCAJLOG data set as input to the AUDIT204 utility, under the ddname of CCAJRNL. You can also use CCAJLOG as input to the UTILJ utility, again under the ddname of CCAJRNL; however, the only useful report produced is a histogram of the number of blocks and block sizes that were written to the CCAJLOG data set.

CCAJRNL is the input data set provided to roll forward recovery (ddname=CCARF), media recovery (ddname= CCAGEN), and UTILJ (ddname=CCAJRNL).

Utilities using CCAJLOG and CCAJRNL data sets as input
[[File:SM13ccaprint3_sep.gif|457px]] 

===Journal stream configurations===

AUDIT204 can process only basic journal streams (single data sets). Members of concatenated, parallel, ring, or GDG streams must be processed one at a time.

If there is a wraparound during the output processing of a ring stream, use the offload stream as input to AUDIT204. You can also use regular z/OS concatenation to print the contents of a concatenated stream.

===z/OS JCL for AUDIT204===

The following considerations apply to z/OS JCL for AUDIT204:
<ul>
<li>Use a SORTLIB DD statement to identify the library in which the sort program is stored, if necessary.</li>

<li>You might need sort work (SORTWKxx) data sets.</li>

<li>SORTIN, SORTOUT, and SYSOUT statements are necessary only for statistical reports. A sort program must be available:
<ul>
<li>SORTIN contains all the user and file statistics entries extracted from the journal. The size of the data set depends on the number of statistics entries extracted. Each user statistics entry is 198 bytes long. Each file entry is 82 bytes long. Partial statistics entries are not copied to SORTIN.</li>

<li>SORTOUT contains the sorted statistics entries from SORTIN. SORTOUT and SORTIN must be the same size.</li>

<li>SYSOUT is the SORT message data set.</li>
</ul></li>

<li>STATIN, STATOUT, and SYSOUT statements are necessary only for statistical analysis reports:
<ul>
<li>STATIN contains all the since-last evaluation statistics entries extracted from the journal. The size of the data set depends on the number of since-last evaluation statistics extracted. Each since-last evaluation statistics entry is 188 bytes long.</li>

<li>STATOUT contains the sorted statistics entries from STATIN. STATOUT and STATIN must be the same size. </li>

<li>Statistics work (STATWKxx) data sets might be needed when using the ANALYZE command, depending on the amount of data generated.</li>
</ul></li>

<li>CCAJRNL describes the data set containing the journal produced by a <var class="product">Model 204</var> run.</li>

<li>AUDIT204 does not support streams. </li>

<li>CCAAUDIT contains the audit trail, statistics report, and statistical analysis report. If you request both the audit trail and statistics, the audit trail appears first.

The value of the BLKSIZE parameter in the CCAAUDIT DD statement is truncated at 4 more than a multiple of 137. A BLKSIZE value of 141 is the default and minimum value.

Any LRECL and RECFM specifications are ignored; these parameter values are forced to be 137 and VBA, respectively.</li>
</ul>

===Samples of a z/OS job stream===

The following sample job streams run AUDIT204, These examples differ in the use of the journal processed, CCAJRNL or CCAJLOG, and the presence or absence of AUDIT204 commands: <var>ANALYZE</var>, <var>FORMAT</var>, and <var>REPORT</var>.

====Where only CCAJRNL is defined, all AUDIT204 commands are valid====
 //AUDIT EXEC PGM=AUDIT204
//STEPLIB DD DSN=M204.LOADLIB,DISP=SHR
//SYSUDUMP DD SYSOUT=A
//CCAJRNL DD DSN=M204.CCAJRNL,DISP=SHR
//CCAAUDIT DD SYSOUT=A
//SORTIN DD DSN=&&SORTIN,UNIT=SYSDA,SPACE=(TRK,nn),
// DISP=(NEW,DELETE)
//SORTOUT DD DSN=*.SORTIN,VOL=REF=*.SORTIN,DISP=(OLD,PASS)
//STATIN DD DSN=&&STATIN,UNIT=SYSDA,SPACE=(TRK,nn),
// DISP=(NEW,DELETE)
//STATOUT DD DSN=*.STATIN,VOL=REF=*.STATIN,DISP=(OLD,PASS)
//SYSOUT DD SYSOUT=A
//CCAIN DD *
FORMAT
ANALYZE
REPORT ACCOUNT
.
. ---- user options
.
/*


====Where CCAJLOG is defined and you want to extract CCAAUDIT====
 //AUDIT EXEC PGM=AUDIT204
//STEPLIB DD DSN=M204.LOADLIB,DISP=SHR
//SYSUDUMP DD SYSOUT=A
//CCAJRNL DD DSN=M204.CCAJLOG,DISP=SHR
//CCAAUDIT DD SYSOUT=A
//SORTIN DD DSN=&&SORTIN,UNIT=SYSDA,SPACE=(TRK,nn),
// DISP=(NEW,DELETE)
//SORTOUT DD DSN=*.SORTIN,VOL=REF=*.SORTIN,DISP=(OLD,PASS)
//STATIN DD DSN=&&STATIN,UNIT=SYSDA,SPACE=(TRK,nn),
// DISP=(NEW,DELETE)
//STATOUT DD DSN=*.STATIN,VOL=REF=*.STATIN,DISP=(OLD,PASS)
//SYSOUT DD SYSOUT=A
//CCAIN DD *
FORMAT
.
. ---- user options
.
/*


====Where both CCAJRNL and CCAJLOG are defined and you want a statistical analysis====
 //AUDIT EXEC PGM=AUDIT204
//STEPLIB DD DSN=M204.LOADLIB,DISP=SHR
//SYSUDUMP DD SYSOUT=A
//CCAJRNL DD DSN=M204.CCAJRNL,DISP=SHR
//CCAAUDIT DD SYSOUT=A
//SORTIN DD DSN=&&SORTIN,UNIT=SYSDA,SPACE=(TRK,nn),
// DISP=(NEW,DELETE)
//SORTOUT DD DSN=*.SORTIN,VOL=REF=*.SORTIN,DISP=(OLD,PASS)
//STATIN DD DSN=&&STATIN,UNIT=SYSDA,SPACE=(TRK,nn),
// DISP=(NEW,DELETE)
//STATOUT DD DSN=*.STATIN,VOL=REF=*.STATIN,DISP=(OLD,PASS)
//SYSOUT DD SYSOUT=A
//CCAIN DD *
ANALYZE
REPORT
.
. ---- user options
.
/*


===z/VSE JCL for AUDIT204===

The following considerations apply to z/VSE: 
<ul>
<li>Under z/VSE, output is sent to SYSLST. </li>

<li>CCAJRNL can be on tape or disk. If CCAJRNL is on tape, SYS004 must be assigned to a tape drive.</li>

<li>Running AUDIT204 might require two sorts:
<ul>
<li><var>REPORT</var> command requires a SORTIN and a SORTOUT data set.</li>

<li><var>ANALYZE</var> command requires a STATIN and a STATOUT data set. </li>
</ul></li>

<li>SORTIN, SORTOUT, STATIN, and STATOUT are work files and must be on disk. </li>

<li>SORTWK1 data set is required.</li>

<li>Statistics work (STATWK1) data set might be needed when using the <var>ANALYZE</var> command, depending on the amount of data generated. </li>
</ul>

===Sample z/VSE job stream===

The following sample job stream runs AUDIT204:
// JOB AUDIT204
// DLBL M204LIB,'M204.PROD.LIBRARY'
// EXTENT SYSnnn,...
// LIBDEF PHASE.SEARCH=M204LIB.V210
// DLBL CCAJRNL,'CCAJRNL' Note 1
// EXTENT SYSnnn,...
// DLBL SORTIN,'AUDIT204.SORTIN',0 Note 2
// EXTENT SYSnnn,...
// DLBL SORTOUT,'AUDIT204.SORTOUT',0 Note 2
// EXTENT SYSnnn,...
// DLBL STATIN,'AUDIT204.STATIN',0 Note 3
// EXTENT SYSnnn,...
// DLBL STATOUT,'AUDIT204.STATOUT',0 Note 3
// EXTENT SYSnnn,...
// DLBL SORTWK1,'SORTWK1',0 Note 4
// EXTENT SYSnnn,...

// EXEC AUDIT204,SIZE=(AUTO,xxK) Note 5
INCLUDE IFYLSQRT
* Insert AUDIT204 CCAIN commands here
FORMAT
REPORT ACCOUNT
REPORT FILE
REPORT ACCOUNT ACCOUNTS MAGGIE MARY DAVE
/*
/&


====Usage notes====
<ul>
<li>If you use tape instead of the DLBL and EXTENT for CCAJRNL, use the following JCL:
// TLBL CCAJRNL
// ASSGN SYS004,X'cuu'
</li>

<li>DLBL and EXTENT are necessary if you use either the <var>REPORT</var> or the <var>ANALYZE</var> command.</li>

<li>You must specify a SIZE parameter in the EXEC statement with AUTO and you need some additional storage for the sort program. To determine the amount of additional storage needed for the sort program, refer to IBM's <var class="book">SORT/MERGE Programmer's Guide</var>.</li>
</ul>

===(z/VM) CMS JCL for AUDIT204===

The CMS AUDIT204 utility program prints a <var class="product">Model 204</var> journal file and produces a statistical report from information in a journal file:
<ul>
<li>If a statistics report is produced, a SORT utility that can be invoked dynamically must be available for use.</li>

<li>AUDIT204 output is produced either as a printer spool file or in a CMS disk file. </li>
</ul>

The following EXEC initiates AUDIT204:

AUDIT204 [datasetname] [filename filetype] filemode


Where:
<ul>
<li><var class="term">datasetname</var> specifies the name of the journal data set on a variable-format disk, with the qualifiers separated by blanks. If no data set name is specified, it is presumed that the name of the journal data set is <code>M204.JOURNAL</code>.</li>

<li><var class="term">filename</var> and <var class="term">filetype</var>
specify the name and type of the journal file on a CMS-format, or a variable format for z/OS and z/VSE, disk.</li>

<li><var class="term">filemode </var> specifies the mode of the disk holding the journal file to be processed. The input to AUDIT204 contains the commands selected from those described earlier and is included in the AUDIT204 CCAIN. </li>
</ul>

===Searching multiple tapes for journal and off load data===

When a journal or offload data set is on multiple tapes, you do not need to mount all of them for AUDIT204 processing. You can process a subset of the tapes, as long as you mount them in the order in which they were originally generated.

For example, suppose that your CCAJRNL data set consists of five tapes labeled <code>TAPE01</code> through <code>TAPE05</code>. You are sure that the information you want to analyze begins on the third tape or later. In this case you can save processing time by specifying only <code>TAPE03</code>, <code>TAPE04</code>, and <code>TAPE05</code> in the DD statement for the CCAJRNL data set.
</div> 

[[Category:System management]]
[[Category:Auditing and problem determination]]
===AUDIT204 Return Codes===
The following return codes may be issued by AUDIT204 upon completion.
<table>
<tr class="head">
<th>Return Code</th>
<th>Meaning</th>
</tr>

<tr>
<td>0</td>
<td>Normal completion</td>
</tr>

<tr>
<td>8</td>
<td>I/O error reading CCAJRNL or CCAJLOG</td>
</tr>

<tr>
<td></td>
<td>Out of sequence journal block</td>
</tr>

<tr>
<td></td>
<td>Zero length journal block or journal record</td>
</tr>

<tr>
<td>12</td>
<td>Invalid parameter - various errors with CCAIN input parameters</td>
</tr>

<tr>
<td>16</td>
<td>CCAAUDIT open failed</td>
</tr>

<tr>
<td>20</td>
<td>CCAJRNL or CCAJLOG open failed</td>
</tr>

<tr>
<td>24</td>
<td>SORTIN open failed</td>
</tr>

<tr>
<td>28</td>
<td>STATIN open failed</td>
</tr>

<tr>
<td>32</td>
<td>CCAIN open failed</td>
</tr>

<tr>
<td>36</td>
<td>Operating system does not support Z-architecture</td>
</tr>

LOGCTL command: Modifying group entries in the password table

2024-06-13T20:21:11Z

JDamon: Removed an incorrect note.

==Summary==
<dl>
<dt>Privileges
<dd>System manager
<dt>Function
<dd>Adds, deletes, or changes group entries in the password table
</dl>

==Syntax==
LOGCTL {A | D | C} ,groupname [index]


Where:
<table>
<tr>
<th>groupname</th>
<td> is the name of the group entry to be added, deleted, or changed (1 to 8 characters). A comma must precede the group name.</td>
</tr>

<tr>
<th>index</th>
<td> is a single character indicating which file entry is being modified, and is either a digit 0-9 or a letter A-Z; index must be specified if the file has more than one password.</td>
</tr>
</table>

==Example==
LOGCTL C ,PRMGROUP


==Usage notes==
<ul>
<li>The <var>LOGCTL</var> command adds, deletes, or changes group entries in the password table. If add (<var>A</var>) or change (<var>C</var>) is specified, <var class="product">Model 204</var> prompts for information as shown in the dialog below.

The system manager can change any of the following specifications in a group entry: 
<ul>
<li>Password</li>

<li>Privileges</li>

<li>User class</li>

<li>Field level security levels</li>

<li>Terminal list</li>
</ul></li>

<li>Upon entry of the <var>LOGCTL</var> command, the system responds with a prompt in the following form:
*** M204.0374: ENTER FILE/GROUP PASSWORD, PRIVILEGES, CLASS, SELECT, READ, UPDATE, ADD password, X'pppp', ccc, sss, rrr, uuu, aaa


Where:
<table>
<tr>
<th>password</th>
<td>The user's password (1 to 8 characters). It cannot contain blanks, commas, or colons.</td>
</tr>

<tr>
<th>pppp</th>
<td>The two-byte representation of the group privileges. (See [[PRIVDEF parameter|PRIVDEF: Default user privileges]].)</td>
</tr>

<tr>
<th>ccc</th>
<td>The procedure user class.</td>
</tr>

<tr>
<th>sss</th>
<td>The [[Model 204 security features#Field-level security|field-level security]] SELECT level.</td>
</tr>

<tr>
<th>rrr</th>
<td>The field-level security READ level.</td>
</tr>

<tr>
<th>uuu</th>
<td>The field-level security UPDATE level.</td>
</tr>

<tr>
<th>aaa</th>
<td>The field-level security ADD level. </td>
</tr>
</table>

When a group entry is being added, the password is required and all other specifications are optional. <var class="product">Model 204</var> supplies default values of zero.
When a group entry is being changed, all specifications are optional. If the system manager does not supply a specification in the command, the existing specification in the password table is preserved, as described for login user IDs.

==See also==
<ul>
<li>[[LOGCTL command: Modifying file entries in the password table]] </li>
<li>[[LOGCTL command: Modifying user ID entries in the password table]] </li>
</ul>

[[Category: System manager commands]]
[[Category:Commands]]

Model 204 security features

2023-11-17T19:20:25Z

JDamon: /* Multi-factor Authentication - MFA */

<div class="toclimit-3">

==Overview==

A variety of security features provide <var class="product">Model 204</var> users with protection against unauthorized use of their account names, files, groups, records, fields, procedures, and terminals. This section describes the role of the file manager in maintaining <var class="product">Model 204</var> security. 

===Additional documentation on security features===
<ul>
<li>System manager responsibilities are described in detail in [[Storing security information (CCASTAT)#Overview|Storing security information (CCASTAT)]].</li>

<li>Rocket Software has add-on interfaces between <var class="product">Model 204</var> and a number of security products. These security interfaces are described in the [[:Category:Security interfaces|Security interfaces]] pages.</li>

<li>SSL/TLS security features for Janus products are described in [[Janus Network Security]]. </li>
</ul>

===Using the Model 204 password table===

The <var class="product">Model 204</var> password table is the backbone to the security features in <var class="product">Model 204</var>. The user must enter a valid password to access the <var class="product">Model 204</var> Online, files, groups of files, and subsystems, which in turn affects access to records. The security feature in <var class="product">Model 204</var> is not based on a hierarchy, but rather on direct password validation.

The password table, CCASTAT, is set up by the system manager. When the file manager determines which users or groups of users can have access to what data, then the file manager works with the system manager to correctly set up the password table and file access. 

===Types of security===

All <var class="product">Model 204</var> security features are optional. A site can support any combination of features. The file manager is primarily responsible for file, group, record, field, and procedure security. Both system and file managers handle terminal security. The file manager's responsibilities are described in this topic. 
<table>
<tr class="head">
<th>Type of security</th>
<th>Function</th>
</tr>

<tr>
<td>Login (System manager)</td>
<td>Limits access to the <var class="product">Model 204</var> system by requiring an individual user to enter a password when logging in. Only users who enter a valid password can gain access to the system. When a user successfully logs in, specified privileges are granted.
See [[Storing security information (CCASTAT)#Login security|Login security]] and the <var>[[LOGCTL command (user ID entries)|LOGCTL]]</var> command for modifying user ID entries.
</td>
</tr>

<tr>
<td>[[#File security|File]] (File manager)</td>
<td>Protects certain types of files by requiring a user to specify a valid file password in the OPEN command or OPEN statement. After successfully opening a file, a user is granted particular privileges pertaining to the data and procedures in that file, as well as a user class number for procedure security, and field-level security access levels. </td>
</tr>

<tr>
<td>[[#Group security|Group]] (File manager) </td>
<td>Protects certain types of file groups by requiring a user to specify a valid group password in the OPEN command or OPEN statement. When a user successfully opens a permanent group, the user is granted specified privileges that pertain to the files in the group. When opening a temporary group, the user is granted the privileges that all the member files have in common. </td>
</tr>

<tr>
<td>[[#Record security|Record]] (File manager) </td>
<td>Limits access to particular records in a <var class="product">Model 204</var> file. When record security is in effect, a user can retrieve and update only those records stored by the user's login ID or records that other users have agreed to share. </td>
</tr>

<tr>
<td>[[#Field-level security|Field-level]] (File manager) </td>
<td>Protects sensitive fields in a <var class="product">Model 204</var> file. Field-level security levels are granted when opening a file or group, and they indicate the type of access (for example, READ, UPDATE) to the field that the user is allowed. </td>
</tr>

<tr>
<td>[[#Procedure security|Procedure]] (File manager) </td>
<td>Limits access to the procedures in a file. It indicates whether a user is authorized to access particular procedures and specifies the type of access (for example, DEFINE, DELETE) that the user is allowed in secured procedures. </td>
</tr>

<tr>
<td>[[#Subsystem security|Subsystem]] (System manager) </td>
<td>Controls the privileges that are assigned to users who enter a subsystem. The system manager assigns users subsystem command privileges and privileges for each file and group in the subsystem. </td>
</tr>

<tr>
<td nowrap>[[#Terminal security|Terminal]] (File and system managers) </td>
<td>Allows specified login user IDs and specified files and file groups to be accessed only from certain hard-wired terminals. </td>
</tr>
</table>

===Multi-factor Authentication - MFA===
<tr>
<td>
Support for logon with Multi-factor authentication (MFA) is also provided with no updates or parameter changes required to Model 204. MFA does require that one of the three security interfaces, listed below, be linked into the Model 204 nucleus. Once a userid is provisioned under MFA, the user acquires a token from a client, e.g. IBM Security Verify, installed on the user's mobile device. That token is then concatenated, with a password or passphrase, to logon to Model 204. For example: token:password or token:passphrase, where colon (:) is the concatenating character. That string is passed, unmodified, to the security interface for verification.
<ul>
<li>ACF2
<li>RACF
<li>TopSecret
</ul>
</td>
</tr>

==File security==

<var class="product">Model 204</var> file security features allow you to restrict access to particular files to designated users, as well as to limit the operations that can be performed on those files. Although you are primarily responsible for determining the file security scheme in a <var class="product">Model 204</var> system, you can allow users to change a password for a file if you provide them with the appropriate login privileges. 

Security for files opened in a subsystem operates differently. See [[#Subsystem security|Subsystem security]] for more information.

===File manager's responsibilities===

Ordinarily, the file manager determines which files and file parameters to protect from unauthorized access and determines the initial passwords and associated privileges for the files. It is then the system manager's responsibility to add entries for these files to the password table. The password table contains password and privilege information for files, file groups, and login user IDs.
Maintaining this table is discussed in [[Storing security information (CCASTAT)#Password table data set|Password table data set]]. 

====Defining access levels for files====

The file manager is responsible for defining the default access levels for public and semipublic <var class="product">Model 204</var> files. You are also responsible for determining the four access levels that belong with each file or group password. These levels are then added by the system manager.

===File privileges===

File privileges determine the type of operations that the user is authorized to perform on the file that is being opened. The types of files are:
<table>
<tr class="head">
<th>If the file is...</th>
<th>Then Model 204...</th>
</tr>

<tr>
<td>Public</td>
<td>Opens the file without asking for a file password and grants the user default file privileges as specified by the <var>PRIVDEF</var> parameter.</td>
</tr>

<tr>
<td>Semipublic</td>
<td>Prompts the user to enter a valid password:
<ul>
<li>If the user enters a valid password, the user is given the privileges associated with that password. </li>

<li>If the user does not know the password or enters an incorrect password, the file is still opened but the user is granted the default file privileges associated with the file.</li>
</ul>
</td>
</tr>

<tr>
<td>Private</td>
<td>Prompts the user to enter a valid password:
<ul>
<li>If the user enters a valid password, the file is opened and the user is granted the privileges associated with that password. </li>
<li>If the user does not know the password or enters an invalid password, the file is not opened. </li>
</ul>
</td>
</tr>
</table>

====OPEN command and OPEN statement====

For a discussion of the <var>OPEN</var> command and the way in which a user specifies a password when opening different types of files,
refer to [[OPEN FILE command]] and also see [[Files, groups, and reference context#OPEN statement and OPENC_statement|OPEN statement and OPENC statement]]. 

===Creating files with file security===

When a file is first created with the CREATE command, you can limit access to the file by setting two system parameters, <var>OPENCTL</var> and <var>PRIVDEF</var>, and by asking the system manager to enter one or more file passwords in the password table. Also, the <var>OPENCTL</var> and <var>PRIVDEF</var> parameters can be reset at a later time.

The following sections provide a further description of file passwords and privileges, as well as the <var>OPENCTL</var> and <var>PRIVDEF</var> parameters. 

===File passwords and privileges===

You can define several passwords for a file. Each password can have a different set of privileges associated with it. These privileges determine what operations can be performed on the file by the user who opens the file with that password.

If you do not specify values for <var>OPENCTL</var> and <var>PRIVDEF</var> when you create the file, the file is assumed to be a public file that has a full set of default file privileges. This implies that any user can open the file using the <var>OPEN</var> command or <var>OPEN</var> statement without having to enter a file password, and can then retrieve and update data, define and run procedures, or access file parameters.

====Creating passwords====

Passwords can be up to eight characters long and cannot contain blanks, commas, or colons. 

===OPENCTL parameter===

The <var>OPENCTL</var> parameter determines whether or not a user must enter a file password when opening the file. Except as specified in the following table, <var>OPENCTL</var> settings can be added together. The first three settings are mutually exclusive and one of them must be included in your <var>OPENCTL</var> specification. The remaining settings in the table are options that you can add to one of the first three settings. 
<table>
<tr class="head">
<th>Setting</th>
<th>Means file is...</th>
<th>Password handling</th>
</tr>

<tr>
<td align="right">X'80'</td>
<td>Public</td>
<td>

Password is not requested and the file is opened with default privileges. 

This setting cannot be combined with X'40'.
</td>
</tr>

<tr>
<td align="right">X'40'</td>
<td>Semipublic</td>
<td>

User is asked for a password. For a valid password, the user is given the associated privileges. Otherwise, the user is granted default file privileges. 

This setting cannot be combined with X'80'.
</td>
</tr>

<tr>
<td align="right">X'00'</td>
<td>Private</td>
<td>Without a valid password the file is not opened.</td>
</tr>

<tr>
<td align="right">X'20'</td>
<td>Using record security</td>
<td>

No effect.

The user must have a security level that permits some type of access.
</td>
</tr>

<tr class="head">
<th colspan="3">Additional options for Parallel Query Option (PQO)</th>
</tr>

<tr>
<td align="right">X'08'</td>
<td>Accessible remotely without a valid password </td>
<td>

For a public file, no password is requested and the file is opened with default privileges.

For a semipublic file, a password is requested. If the password is missing or invalid, the user is granted default file privileges.

For a private file, or a semipublic file that a remote user presents a valid password for, the file is opened if X'02' is set. 
</td>
</tr>

<tr>
<td align="right">X'04'</td>
<td>Accessible remotely as a permanent group member</td>
<td><var class="product">Model 204</var> permanent group security is in effect. Password handling for local users is unaffected.</td>
</tr>

<tr>
<td align="right">X'02'</td>
<td>Accessible remotely with a valid password</td>
<td>For a private file, or a semipublic file that a remote user presents a valid password for, the file is opened. </td>
</tr>

<tr>
<td align="right">X'00'</td>
<td>Accessible remotely through APSY</td>
<td>For any file, no password is requested and the file cannot be opened remotely, except within a trusted subsystem.</td>
</tr>
</table>

For PQO sites, the OPENCTL parameter determines how a file can be accessed remotely. The PQO remote access settings have no meaning for local files. For more information about PQO remote files, see [[PQO: Remote files and scattered groups]].

===PRIVDEF parameter and file privileges===

The PRIVDEF parameter summarizes the default file privileges that are assigned when a public file is opened, or when a semipublic file is opened without a password or with an invalid password. Privileges can be set to any combination of the following bit settings. These privileges are identical to the privileges that can be specified for an individual file password in the password table. 
<table>
<tr class="head">
<th>Bit</th>
<th>User can...</th>
</tr>

<tr>
<td align="right"> X'8000'</td>
<td>Issue file manager privileged commands such as INITIALIZE, SECURE, and DESECURE. The file manager can also reset file parameters, provided that ad hoc update privileges (X'2000') are obtained. </td>
</tr>

<tr>
<td align="right"> X'4000'</td>
<td>Override record security; see [[#Record security|Record security]].</td>
</tr>

<tr>
<td align="right"> X'2000'</td>
<td>Update data with ad hoc requests or host language programs. </td>
</tr>

<tr>
<td align="right"> X'1000'</td>
<td>Make changes to internal procedures, that is, procedures defined in the same file as the data, but cannot delete them.</td>
</tr>

<tr>
<td align="right"> X'0800'</td>
<td>Update data using internal procedures. </td>
</tr>

<tr>
<td align="right"> X'0400'</td>
<td>Retrieve data with ad hoc requests or host language programs.</td>
</tr>

<tr>
<td align="right"> X'0200'</td>
<td>Display, echo, and copy internal procedures.</td>
</tr>

<tr>
<td align="right"> X'0100'</td>
<td>Retrieve data with internal procedures.</td>
</tr>

<tr>
<td align="right"> X'0080'</td>
<td>Update data using external procedures, that is, procedures defined in a different file from the data.</td>
</tr>

<tr>
<td align="right"> X'0040'</td>
<td>Retrieve data using external procedures.</td>
</tr>

<tr>
<td align="right"> X'0020'</td>
<td>Include internal procedures.</td>
</tr>

<tr>
<td align="right"> X'0010'</td>
<td>Define internal procedures.</td>
</tr>

<tr>
<td align="right"> X'0008'</td>
<td>Delete internal procedures.</td>
</tr>

<tr>
<td align="right"> X'0001'</td>
<td>Access file related parameters. The affected parameters are described in [[ FPARMS and TABLES file parameters#Setting file parameters|Setting file parameters]].</td>
</tr>
</table>

====PRIVDEF default setting====

The default value for the PRIVDEF parameter is X'BFFF', that is, all privileges except the ability to override record security.

====Combining PRIVDEF settings====

Update privileges, for example, update using ad hoc requests, do not imply corresponding retrieval privileges. Thus, a user who has only the ability to update using ad hoc requests (X'2000' bit set) cannot find any records to update. A user must be given both update and retrieval privileges (X'2400') to update data effectively.

Similarly, privileges for data retrieval using internal procedures (X'0100') do not imply that the user can include a procedure from the file. The X'0020' privilege is required for this.

If procedure security is desired, you must relate procedure class numbers to the procedures stored in the file. Also, determine the field-level security levels for any fields in the file that are particularly sensitive and need to be protected against unauthorized access. Field and procedure security features are discussed in [[#Field-level security|Field-level security]] and [[#Procedure security|Procedure security]].

===Resetting PRIVDEF or OPENCTL===

When the OPENCTL parameter is reset to X'80' (public), the assigned privileges are those of the current value of the PRIVDEF parameter. This means that if OPENCTL is reset to X'80' while PRIVDEF is set to less than full file manager privileges, you cannot update the file or reset any file parameters. This can also occur if you reset PRIVDEF while OPENCTL is set to X'80'.

To avoid this problem, use the VIEW PRIVDEF command to ensure that you have appropriate PRIVDEF privileges before you reset OPENCTL to X'80'. Be very careful about resetting PRIVDEF for a public file.

====Regaining access====

If you do accidently lock yourself out of a file, you can regain access as follows:
<ol>
<li>Have the system manager create a permanent private group that contains the locked file.</li>
<li>Have the system manager add a group password (and tell you that password) to the password table, CCASTAT, with the privileges X'BFFF'.</li>
<li>Then, open the private group and issue one of the following commands:

IN FILE name RESET OPENCTL=X'40'

or:
IN FILE name RESET PRIVDEF=X'BFFF'

where <var class="term">name</var> is the name of the locked file. </li>
</ol>

===Securing and desecuring a file===

====Making files secure====

Securing a file ensures that a user cannot access a file illegally by running a <var class="product">Model 204</var> program with a different password table. A special key in the password table serves as the key for securing a file. The key can be changed by the system manager with the LOGKEY command. When a secured file is opened, <var class="product">Model 204</var> compares the key to a copy placed in the file by the SECURE command. The file is opened if the two fields match. If the fields do not match, the user is logged out and an error message is displayed on the operator's console. 

The SECURE command, which can be issued only by a file manager, provides additional file protection by securing the currently open file. This form of the command is issued without arguments:
SECURE


====Desecuring a file====

To desecure a previously secured file, issue the command:
DESECURE


For a description of using the SECURE and DESECURE commands with procedures, refer to [[#Procedure security|Procedure security]]. 

==Group security==

The <var class="product">Model 204</var> group security features allow access to particular file groups to be limited to certain users.The file manager is primarily responsible for group security and for the file security features discussed in the preceding section. 

===Group passwords===

Ordinarily, the file manager determines which groups to protect from unauthorized access, and indicates the passwords and associated privileges for these groups. It is then
the system manager's responsibility to add entries for these groups to the password table and recommend group parameter settings. The system manager, however, is the only user authorized to create permanent groups.
This is done with the CREATE command, as described in [[Storing and using file group definitions (CCAGRP)#Creating file groups|Creating file groups]].

====Opening permanent file groups====

If passwords are required for a permanent file group, only users who know one of the group passwords can open the group. As with file security, the group password determines the types of operations that the user is authorized to perform on the group that is being opened. The privileges associated with the password determine the extent of these operations. Group security operates differently under the Subsystem Management facility. See [[#Subsystem security|Subsystem security]]. 

====Opening temporary file groups====

Opening a temporary group is functionally equivalent to opening a series of files. Only the user who creates a temporary group can open it. To open a temporary group, the user must be able to open each file in the group individually.

====Group file privileges====

The types of permanent groups are:
<ul>
<li>Public</li>
<li>Semipublic</li>
<li>Private </li>
</ul>

These types are the same as described in [[#File manager's responsibilities|File manager's responsibilities]].

When a user opens a semipublic or private group, <var class="product">Model 204</var> requests that the user enter the password. When the group is opened, the user is granted either the privileges associated with the group password or the default privileges for the group, depending on the password supplied. Default privileges are also supplied when a public group is opened.

===Group passwords and privileges===

A permanent group can have several passwords defined for it. Like a file password, a group password can have up to eight characters and cannot contain blanks, commas, or colons. Each password can have a different set of privileges associated with it. These privileges determine what operations can be performed on the group by the user who opens the group with that password. Privileges are expressed as two hexadecimal bytes, as discussed in [[#PRIVDEF parameter and group privileges|PRIVDEF parameter and group privileges]]. 

===PRIVDEF parameter and group privileges===

If a value for PRIVDEF and a PUBLIC, SEMIPUB, or PRIVATE specification is not specified at the time that the group is created, the group is assumed to be a PUBLIC group that has default privileges of X'3FFF'. The PRIVDEF parameter, which summarizes the default privileges for a group, provides all the privileges shown for files, plus the two group privileges summarized here. These privileges are identical to the privileges that can be specified for an individual group password in the password table. The X'8000' privilege has no meaning for groups, although it can be important for individual references to member files. 
<table>
<tr class="head">
<th>Bit</th>
<th>User can...</th>
</tr>

<tr>
<td align="right"> X'0004'</td>
<td>Update data through procedures from the procedure file.</td>
</tr>

<tr>
<td align="right"> X'0002'</td>
<td>Retrieve data through procedures from the procedure file.</td>
</tr>
</table>

When a group is created, one of its member files can be designated as the procedure file. This is the file in which procedures for the group are stored and from which procedures are retrieved or deleted. 

In a group context, internal means that a file is a member of the group, while external means that a file is not a member of the group.

===Determining file and group privileges===

When a command or a SOUL statement refers to a file or group, <var class="product">Model 204</var> checks the file and group privileges to ensure that the operation is allowed. <var class="product">Model 204</var> must determine whether a file has been opened as an individual file, as a member of a permanent or temporary group, or as both.

The privileges associated with individual files and groups can be granted and combined in different ways, depending upon the [[Files, groups, and reference context#Reference context|reference context]], as shown in the following table. 
<table>
<tr class="head">
<th>Referring to...</th>
<th>User's privileges are...</th>
</tr>

<tr>
<td>Individual file</td>
<td>Same as those granted by <var class="product">Model 204</var> when the file was opened. These privileges are associated with the specified file password or, if no password is required or is incorrectly specified, the default file privileges.</td>
</tr>

<tr>
<td>Temporary or ad hoc group</td>
<td>Intersection of the individual privileges associated with the files that make up the group. <var class="product">Model 204</var> compares the privileges of all of the member files; only privileges that are common to every file are granted. </td>
</tr>

<tr>
<td>Permanent group</td>
<td>Same as those granted by <var class="product">Model 204</var> when the group is opened. These are the privileges associated with the specified group password or, if no password is required or is incorrectly specified, the default group privileges.</td>
</tr>

<tr>
<td nowrap>Member of a permanent group (<var class="term">not</var> opened individually)
</td>
<td>Those granted for the group.

If the file is opened individually, its privileges remain those granted when the file was individually opened.
</td>
</tr>

<tr>
<td>Two permanent groups (<var class="term">not</var> opened as individual files)</td>
<td>Union of the privileges associated with the groups. <var class="product">Model 204</var> combines the privileges of all open groups of which the file is a member. Any privileges specified for any of the groups are granted.</td>
</tr>

<tr>
<td>File open as both an individual and a group</td>
<td>Privileges associated with the file, not the group. No open group has an effect on the file privileges. </td>
</tr>
</table>

==Record security==

In addition to protecting an entire file or group from unauthorized access, you can also protect individual records in a file. When record security is in effect for a particular <var class="product">Model 204</var> file, each user can be allowed to retrieve and update only records stored in the file with that user's ID or records that other users have agreed to share. The user does not know that any other records exist. 

Record security can be in effect for one or more of the files in a group, but not for the group as a whole. Access to a single record depends on only the record security field defined for the record's file.

===Record security and login security===

<var class="product">Model 204</var> record security can be considered as an extension to login security and cannot be used unless the login security feature is in effect at an installation. Login security is primarily the system manager's responsibility, and it is discussed in detail in [[Storing security information (CCASTAT)#Login security|Login security]]. 

===File manager responsibilities===

Record security usually is the responsibility of the file manager. To initiate record security, set the <var>[[OPENCTL parameter|OPENCTL]]</var> parameter in the <var>CREATE</var> command to indicate that record security is in effect and describe the special record security field in the <var>INITIALIZE</var> command, which is discussed in [[Initializing files#Initializing record security files|Initializing record security files]]. You can turn off record security by using the appropriate <var>OPENCTL</var> setting with the <var>RESET</var> command, but it cannot be turned on by <var>RESET</var>. The file must be defined to have record security through the <var>CREATE</var> command.

===Setting record security for remote users===

If your site has the Parallel Query Option/204 product, you can control access to remote files with record security using the <var>[[PQOSYS parameter|PQOSYS]]</var> CCAIN system parameter.
If set, <var>PQOSYS</var> creates a special record security key for remote users.
For more information about <var>PQOSYS</var>, see [[PQO: Managing files and groups#Record security for remote users: the PQOSYS parameter|Record security for remote users: the PQOSYS parameter]]. 

===Storing and retrieving records===

After a file has been initialized with a record security key, each record stored in the file with a SOUL <var>STORE RECORD</var> statement automatically has a record security field added to it, whose value is equal to the current user's login user ID. 

====Storing record security fields through File Load or the Host Language Interface====

For records stored with a Host Language Interface <var>IFBREC</var> or <var>IFSTOR</var> function or by a file load program, a record security field must be added explicitly, along with other fields, when the record is created. For example, the following file load statement adds a record security field:
LDC RECSEC=DARCY=


Refer to [[File Load utility]] for information about the File Load utility. 

Only records that have a record security field whose value is equal to the current user's login user ID are retrieved by a SOUL <var>FIND</var> statement or Host Language Interface calls that perform a find function. If the <var>FILE LOAD</var> statement shown here is executed, for example, only a user logged in under the name <code>DARCY</code> can retrieve these records. 

===Allowing multiple access===

To share a record with another user, either you or the user can add an explicit occurrence of the record security field with a value equal to the second user's login user ID. If the second user has update privileges, that user can delete the first value of the record security field, thus making the record accessible only through the second user's user ID. 

====Multiple access in 1NF files====

To allow access to record security fields in <var>1NF</var> files, you must define the record security field as <var>INVISIBLE</var> and <var>REPEATABLE</var>.

===Overriding record security===

Occasionally, it may be necessary to override the <var class="product">Model 204</var> record security scheme. To override record security, you must have the appropriate record security override privileges at login time: the X'04' bit must be set. When the file is opened, the X'4000' bit must be set. 

If both privileges have been granted, you can retrieve all records, regardless of the record security key value associated with them. However, if you store records from User Language at this time, they still have the record security field with the value of your login ID added to them automatically.

If record security was specified for a file in a permanent group, you can override record security for the file if login and group privileges (X'4000') allow it. 

For further information regarding login security bit settings, see [[Establishing and maintaining security#File security|File security]]. 

==Field-level security==

Field-level security (FLS) provides an additional level of protection for a user's data by controlling access to the individual fields of a <var class="product">Model 204</var> file. It involves a comparison of the user's predetermined numeric access level for a field with the field's own predetermined level, for each of four types of access. Field-level security specifications are put into effect only if access to a data record has been allowed by previous file-level and record-level security checks. The following paragraphs describe in detail how field-level security operates. 

In addition to field-level access for each field, each file has a default access level (that is, all fields within the file are automatically assigned access levels).

The following parameters determine the default field access:
<table>
<tr class="head">
<th>This parameter</th>
<th>Provides this default field access...</th>
</tr>

<tr>
<td>SELLVL</td>
<td>SELECT </td>
</tr>

<tr>
<td>READLVL</td>
<td>READ </td>
</tr>

<tr>
<td>UPDTLVL</td>
<td>UPDATE </td>
</tr>

<tr>
<td>ADDLVL</td>
<td>ADD </td>
</tr>
</table>

Like PRIVDEF, these parameters can be set when a file is created, or they can be reset later. If not explicitly specified, all of these parameters are set to zero, which allows a user to access only unsecured fields (that is, fields with access levels of 0). The same four parameters can be set for a permanent group when it is created by the system manager.

===File manager responsibilities===

The file manager is responsible for determining the desired field-level security scheme and for assigning security levels to fields that are to be protected. The LEVEL option allows you to indicate the security level for the field. 

For example, if the following command is issued, only users who have access levels of 70 or greater are allowed to access the PERFORM field, which might contain an employee's performance evaluation code:
DEFINE FIELD PERFORM WITH LEVEL 70


===Types of field access===

By using the <var class="product">Model 204</var> field-level security scheme, you can protect particularly sensitive data fields from unauthorized access. A field can be accessed in several different ways.

Field-level security features limits access to a field to any combination of the following access types: 
<table>
<tr class="head">
<th>This access type</th>
<th>Allows you to...</th>
</tr>

<tr>
<td>SELECT</td>
<td>Use the field in a SOUL FIND statement or in an IFFIND call.</td>
</tr>

<tr>
<td>READ</td>
<td>Examine the value of a field, for example, in a SOUL PRINT or assignment statement or an IFGET call. </td>
</tr>

<tr>
<td>UPDATE</td>
<td>Change the value of a previously stored occurrence of a field. This type of access can be granted without a corresponding READ access, which precludes updates of the form shown below:
CHANGE fieldname = value TO value
</td>
</tr>

<tr>
<td>ADD</td>
<td>Add new occurrences of a field, including those added by a STORE RECORD statement. This type of access allows data entry clerks or other personnel to add new field occurrences or records without being able to change existing occurrences, or possibly even to examine them.

This type of access can also provide a user with the ability to add occurrences of the record security field without altering existing occurrences.
</td>
</tr>
</table>

Field-level security controls only explicit field references. Implicit references, such as retrieving a record security field with a FIND statement or adding a record security key value with STORE RECORD, are not controlled. 

===Field levels===

Every field definition can have a security level associated with it. Security levels are numbered from 0 to 255. 0 implies no security for the field; 255 implies the highest security. 

====Field-level security and field ordering====

In the <var class="product">Model 204</var> field-level security scheme, fields can be assigned security levels in a hierarchical fashion. The fields can be ordered in view of the sensitivity of the data that they contain. An example of such an ordering is shown in [[#Field levels|Field levels]], the fields being listed in order of increasing sensitivity.
<table>
<caption>Field-level ordering example</caption>
<tr class="head">
<th>Field </th>
<th>FLS READ level</th>
</tr>

<tr>
<td>Last name</td>
<td align="right">0</td>
</tr>

<tr>
<td>First name</td>
<td align="right">0</td>
</tr>

<tr>
<td>Employee number</td>
<td align="right">0</td>
</tr>

<tr>
<td>City</td>
<td align="right">10</td>
</tr>

<tr>
<td>State</td>
<td align="right">10</td>
</tr>

<tr>
<td>Zip code</td>
<td align="right">10</td>
</tr>

<tr>
<td>Street address</td>
<td align="right">20</td>
</tr>

<tr>
<td>Position</td>
<td align="right">30</td>
</tr>

<tr>
<td>Telephone number</td>
<td align="right">40</td>
</tr>

<tr>
<td>Salary</td>
<td align="right">60</td>
</tr>

<tr>
<td>Performance evaluation</td>
<td align="right">70</td>
</tr>
</table>

In [[#Field levels|Field levels]], performance evaluation is considered to be the most sensitive field in the record, followed by salary, and so on. Last name, first name, and employee number have not been assigned field-level security numbers. However, file, record, and procedure security features still can be used to control access to those fields.

===User levels===

Each user has four field-level security access levels associated with each file and group opened. These correspond to the four field access levels defined previously: SELECT, READ, UPDATE, and ADD. User levels also range from 0 to 255.

When a user attempts to access a field in a particular way, <var class="product">Model 204</var> compares the user's access level with the level assigned for the field. If the user's level for the desired type of access, for example, READ, is greater than or equal to the field's FLS level, the particular type of field access is allowed. 

====User-level security example====

For example, a user who has a READ level of 30 is permitted to print any field that has a READ level between 0 and 30, but cannot print a field that has a higher READ level. Thus, when using the file described above, a user who has a READ level of 30 can print an employee's position (and all fields that have lower FLS fields), but not the employee's telephone number, salary, or performance evaluation. An example of a possible set of access levels at an installation is shown below: 
<table>
<caption>User access levels example</caption>
<tr class="head">
<th>Employee category</th>
<th>SELECT</th>
<th>READ</th>
<th>UPDATE</th>
<th>ADD</th>
</tr>

<tr>
<td>Data entry clerks</td>
<td align="right">0</td>
<td align="right">0</td>
<td align="right">0</td>
<td align="right">60</td>
</tr>

<tr>
<td>Personnel department clerks</td>
<td align="right">50</td>
<td align="right">50</td>
<td align="right">40</td>
<td align="right">0</td>
</tr>

<tr>
<td>Personnel department supervisor</td>
<td align="right">70</td>
<td align="right">70</td>
<td align="right">70</td>
<td align="right">0</td>
</tr>

<tr>
<td>Other employees (for example, telephone operators)</td>
<td align="right">0</td>
<td align="right">10</td>
<td align="right">0</td>
<td align="right">0</td>
</tr>

<tr>
<td>Employee supervisor</td>
<td align="right">0</td>
<td align="right">70</td>
<td align="right">0</td>
<td align="right">70</td>
</tr>
</table>

The motivations for these assignments easily can be understood in relation to the sample file. Only data entry clerks can add employee records; only supervisors can add performance evaluations; only personnel department supervisors can update salaries, and so on.

====Referring to or displaying fields====

When a user's access levels are lower than permitted for the level of a particular field, a reference to the field is treated as a reference to a nonexistent field. Furthermore, the names of such fields are excluded from the output of the DISPLAY FIELD ALL command. Thus, when using the file shown in [[#User levels|User levels]], only personnel and employee supervisors know that a performance evaluation field even exists in the file. The field is never visible to other users. 

=====Limiting access to fields=====

Access to records for particular employees can be controlled in another way. Employee supervisors usually are given a password that allows them to read or add any field in the file. However, procedure- or record-level security can be used to restrict supervisors' access to only the records of their employees.

===Determining user access levels===

The access levels assigned for a user are determined when the user opens a file or a group using the
[[OPEN FILE command]], [[OPEN PERM GROUP command]], or [[OPEN TEMP GROUP command]] or using the <var>[[Files, groups, and reference context#OPEN statement and OPENC statement|OPEN]]</var> statement.
Access level assignments are made for various types of files or groups as follows: 
<ul>
<li>If a file or a permanent group is public or semipublic and an incorrect password is specified in the OPEN, the user's four access levels are taken from the file or group defaults described in [[#Procedure security|Procedure security]]. </li>

<li>If a private or semipublic file or group is opened with a valid password, the user's four access levels are the same as those associated with the password. </li>

<li>If a temporary or ad hoc group is opened, all the member files are opened separately as individual files. Opening these individual files establishes a set of four access levels for each member file.</li>
</ul>

====Access levels for temporary or ad hoc groups====

The four access levels for a temporary or ad hoc group are formed by taking the minimum of each access level across all the member files. Suppose that <code>FILEA</code> and <code>FILEB</code> have the access levels shown in the following table.
<table>
<tr class="head">
<th>File</th>
<th>SELECT</th>
<th>READ</th>
<th>UPDATE</th>
<th>ADD</th>
</tr>

<tr>
<td>FILEA</td>
<td align="right">30</td>
<td align="right">40</td>
<td align="right">10</td>
<td align="right"> 0</td>
</tr>

<tr>
<td>FILEB</td>
<td align="right">40</td>
<td align="right">30</td>
<td align="right"> 0</td>
<td align="right">10</td>
</tr>
</table>

If a temporary group named <code>FILES</code>, consisting of <code>FILEA</code> and <code>FILEB</code>, is opened, the group is assigned the access levels:
<table>
<tr class="head">
<th>Group </th>
<th> SELECT</th>
<th>READ</th>
<th>UPDATE</th>
<th>ADD</th>
</tr>

<tr>
<td>FILES</td>
<td align="right">30</td>
<td align="right">30</td>
<td align="right"> 0</td>
<td align="right"> 0</td>
</tr>
</table>

This is equivalent to the comparison of file privileges that occurs when opening a temporary or ad hoc group; see [[#Group security|Group security]].

====Examples====

The following examples show how your user access levels for a file can change as the reference context changes. In the examples, the four user-access levels, SELECT, READ, UPDATE, and ADD, are represented by their first letters.

A field reference occurs in single file context, and the file is opened as a single file:
 S R U A
OPEN FILE FILEA 100 100 10 20
BEGIN
FPC NAME=JONES
END


The four access levels used in checking field references (100, 100, 10, 20) are those assigned when <code>FILEA</code> was opened as a single file.

A field reference occurs in group context:
 S R U A
OPEN FILE GROUPA 50 75 20 0
BEGIN
FPC NAME=JONES
END


The four access levels used for checking field references in any file of the group (50, 75, 20, 0) are the four assigned when the group was opened. All the files in a group receive the same four access levels.

A field reference occurs in single file context, but the file was opened only as a member of one or more permanent groups. <code>FILEA</code> is a member of the two groups, <code>GROUPA</code> and <code>GROUPB</code>:
 S R U A
CLOSE FILE FILEA
OPEN GROUP GROUPA 50 75 20 0
OPEN GROUP GROUPB 50 50 0 100
BEGIN
IN FILEA FPC NAME=JONES
END


The four access levels used in checking field references (50, 75, 20, 100) are formed by taking the maximum level defined for the file by every group containing the file that the user has opened. 

==Procedure security==

<var class="product">Model 204</var> procedure security limits access to a file's procedures in the following ways: 
<ul>
<li>By allowing you to specify user privileges that control the type of functions that can be performed on the procedures within a file, for example, to display, define, or delete the procedure.</li>

<li>By limiting access to a procedure to only a particular class of users. This is done by assigning a procedure class number to the procedure that is being secured and a user class to the users allowed to manipulate the procedures. </li>
</ul>

These security features are discussed in greater detail in the following sections. In addition, [[#File security|File security]] and [[#Group security|Group security]] discuss the privileges that enable users to access the data in a file or group through procedures.

===Accessing procedures===

At the time a file or group is opened, particular privileges are established that concern the text of the procedures stored in the file or group. These privileges, or access rights, enable a user to manipulate a procedure in any of the following ways: 
<ul>
<li>Use the procedure, for example, by specifying it in an INCLUDE command.</li>

<li>Display and copy the procedure. This includes echoing the procedure and using the EDIT command to display or copy it. </li>

<li>Change the procedure, usually with the Editor.</li>

<li>Define a new procedure in the file with the PROCEDURE command or the Editor. </li>

<li>Delete a procedure by means of the DELETE command. </li>
</ul>

For information about the basic procedure functions, see the $Prc* and $Proc* functions in [[List of $functions]]; and for information about procedure related commands, see [[:Category:Commands]].

===Securing procedures===

The privileges established for procedure access discussed in [[#PRIVDEF parameter and file privileges|PRIVDEF parameter and file privileges]] are used to limit the way in which the procedures associated with a file or group can be accessed. <var class="product">Model 204</var> provides an additional facility that allows particular procedures to be secured and thus protected from unauthorized access. 

===User and procedure classes===

You can limit user access to procedures by assigning user classes that have access to procedures in a particular procedure class.

User and procedure classes are usually put in place as part of the security scheme for a file or group. Although every user and procedure could have a distinct class number (UCLASS and PCLASS), this approach is too complex and cumbersome for most installations. Thus, sets of procedures and users more often are handled together. 

====User classes (UCLASS)====

Examples of typical user classes are:
<ul>
<li>All employees in a department</li>
<li>All managers, regardless of department</li>
<li>All data entry personnel </li>
</ul>

====Procedure classes (PCLASS)====

Examples of typical procedure classes include procedures that:
<ul>
<li>Display salary data</li>
<li>Update personnel records</li>
<li>Perform general utility operations</li>
<li>Access sensitive fields in files </li>
</ul>

Procedure classes and user classes are arbitrary numbers that range from 1 to 255. Their only significance is in their relationship to each other. The numbers are assigned as described in [[#User and procedure classes|User and procedure classes]].

When a user opens a file or group, the user is given the privileges and user class determined by the OPEN: 
<ul>
<li>If the file or group is opened with a password, the user class is obtained from the password table, where it is stored with the privilege bytes and field-level security levels for the password.

The user class normally is provided by the file manager and entered into the password table by the system manager, as discussed in [[Storing security information (CCASTAT)#Password table maintenance|Password table maintenance]]. 
</li>

<li>If the file or group is opened without a password, the user is granted default privileges and a default user class. This default user class is the value of the PRCLDEF system parameter, which has a default value of zero and can be set by the file manager. </li>
</ul>

====Relationship between user and procedure classes====

An access control table (ACT) stored in each file assigns to particular user classes the access rights to particular procedure classes. These mappings from user class to procedure class in the ACT are created using the SECURE command described in [[#SECURE command, definition format|SECURE command, definition format]]. 

The user class established for a group applies to all its member files. If a file is opened only as part of a permanent group, any reference to a secured procedure compares the user class specified for the group against the procedure's class to determine the available access rights. 

=====Example=====

The association of user classes and procedure classes can be explained best by an example: 

Suppose that a user whose user class is 8 includes a procedure named <code>CENTEST</code>, which has a procedure class of 20. <var class="product">Model 204</var> must determine whether users of class 8 are allowed to include procedures of class 20. 

If <var class="product">Model 204</var> checks the ACT in the file in which <code>CENTEST</code> is defined and finds that an INCLUDE is permitted, the procedure is included. If, however, INCLUDE is not permitted for users of class 8, the INCLUDE does not take place and an error message is issued. 

This mapping of user and procedure classes is discussed in greater detail in the sections that follow.

====Assigning procedure classes====

A procedure class can be specified for a procedure by the file manager or by an individual user. The class can be assigned:
<ul>
<li>By the user when defining the procedure with the PROCEDURE command</li>
<li>By the file manager when securing the procedure with the SECURE command </li>
</ul>

=====User-defined procedure classes=====

When defining a procedure, the user can specify a procedure class number in the following format:
PROCEDURE name PCLASS=n


Where:

<var class="term">n</var> is any number in the range 1 through 255.

A user's access rights to procedures are checked first at the file level and then at the procedure level. Thus, if the user is to be allowed to change a secured procedure, the user must have procedure update file privileges, and the appropriate entry must have been made in the ACT.

=====File manager-defined procedure classes=====

File manager-defined procedure classes are discussed in the following sections, in context of the commands that the file manager uses for this purpose.

===SECURE command, definition format===

If you have appropriate file manager privileges, you can use the SECURE command in the following form to:
<ul>
<li>Secure both files and procedures</li>
<li>Define privileges for procedures that already have been secured</li>
<li>Make entries in the access control table</li>
</ul>

The format is:

SECURE [PROCEDURE]
NAME=procname [,procname ...] PCLASS=pclass


Where:
<ul>
<li><var class="term">procname</var> is the name of an existing procedure to be secured.</li>
<li><var class="term">pclass</var> is the procedure class number to assign to the procedure(s); the number must be in the range 1 to 255. </li>
<li>The SECURE command must be issued in file context, that is, the current default must be a file, not a group.</li>
</ul>

====Example====

The following example is a SECURE command used to secure a procedure:
SECURE PROCEDURE NAME = PAY PCLASS = 7


After this command is issued, the procedure PAY is secured with the procedure class number 7. An entry for PCLASS=7 is made in the procedure dictionary. If PAY is currently secured, its old procedure class is changed to the new class.

===SECURE command, mapping format===

The SECURE command lets you map particular access privileges and user classes to particular procedure classes. This command creates entries in the access control table. Issue the following form of the command:

SECURE [PROCEDURE]
ACCESS = {ALL | (access [,access...]) | NONE}
UCLASS = {ALL | (uclass [,uclass...])}
PCLASS = {ALL | (pclass [,pclass...])}


Where:
<ul>
<li><var class="term">access</var> is a particular privilege associated with the procedures in the procedure class. It can be one of the following:
<table>
<tr class="head">
<th>Privilege</th>
<th>Users can...</th>
</tr>

<tr>
<td>USE </td>
<td>Include procedures.</td>
</tr>

<tr>
<td>COPY </td>
<td>Display and edit (copy only) procedures.</td>
</tr>

<tr>
<td>CHANGE </td>
<td>Edit procedures.</td>
</tr>

<tr>
<td>DEFINE </td>
<td>Create new procedures (PROCEDURE and EDIT).</td>
</tr>

<tr>
<td>DELETE </td>
<td>Delete procedures.</td>
</tr>
</table></li>
<li><var class="term">uclass</var> is the user class number whose users have access to the procedures in PCLASS; the number must be in the range 1 to 255. Parentheses are optional in the uclass definition.</li>

<li><var class="term">pclass</var> is the procedure class number to which users in UCLASS have access; the number must be in the range 1 to 255. Parentheses are optional in the pclass definition. </li>
</ul>

====Example====

In the following example, only users in the Payroll Department (user class 90) are allowed to use procedures that manipulate salary fields in a file (procedure class 20 and 30):
SECURE PROC ACCESS = (USE) UCLASS = 90 PCLASS = 20,30


The entries in the ACT do not take effect for users that have the file open when the <var>SECURE</var> command is issued until they reopen the file. This includes the user who issues the command. See [[SECURE PROCEDURE ACCESS command]] for the complete syntax and description of the <var>SECURE</var> command.

To complete procedure security implementation, the system manager updates the password table using the <var>LOGCTL</var> command to assign user classes to the appropriate passwords. 

===Procedure-related commands and required privileges===

The following list is a summary of <var class="product">Model 204</var> procedure or procedure-related commands that require particular privileges. All these commands are described in the <var class="product">Model 204</var> Parameter and Command Reference. 
<table>
<caption>Privileges for procedure or procedure-related commands</caption>
<tr class="head">
<th>Command</th>
<th colspan="2">Required privileges</th>
</tr>

<tr>
<td>INCLUDE</td>
<td>USE</td>
<td> </td>
</tr>

<tr>
<td>EDIT</td>
<td>COPY</td>
<td> </td>
</tr>

<tr>
<td>DISPLAY</td>
<td>COPY (to display text)</td>
<td> </td>
</tr>

<tr>
<td>DELETE</td>
<td>DELETE</td>
<td> </td>
</tr>

<tr>
<td>ASSIGN</td>
<td>CHANGE</td>
<td> </td>
</tr>

<tr>
<td>DEASSIGN</td>
<td>CHANGE</td>
<td> </td>
</tr>

<tr>
<td>RENAME</td>
<td>CHANGE</td>
<td> </td>
</tr>

<tr class="head">
<th>Command</th>
<th>New procedure</th>
<th>Old procedure</th>
</tr>

<tr>
<td>PROCEDURE</td>
<td>DEFINE</td>
<td>CHANGE</td>
</tr>

<tr>
<td>EDIT commands:

GO END</td>
<td>DEFINE, USE* DEFINE</td>
<td>CHANGE, USE* CHANGE</td>
</tr>

<tr>
<td></td>
<td colspan="2">*COPY privileges are required in addition to USE to echo text lines of a procedure to a journal.</td>
</tr>
</table>

===Displaying user and procedure classes===

The SECURE command constructs entries in the access control table for any user classes specified in the UCLASS clause. 
Note: It is important to display procedure security and save it before reorganizing a file, so that you can reestablish the same security. You might have to upgrade your file manager privileges to include COPY, which is not part of the default privileges of a file manager.

To determine a user's access rights for various procedure classes, issue the following form of the DISPLAY command: 

DISPLAY [PROCEDURE (PRIVILEGES [,NOUSE])
[ALL | UCLASS = <var class="term">uclass</var>[,<var class="term">uclass</var>...]]


Where:
<ul>
<li>ALL displays information for all user classes. </li>

<li><var class="term">uclass</var> displays information only for the specified classes.</li>

<li>If neither is specified, your current class and privileges are displayed.

Privileges are displayed in the following format:
UCLASS=<var class="term">u</var> PCLASS=<var class="term">pc</var>,X'<var class="term">nn</var>'
.
.
.
PCLASS=<var class="term">pc</var>,X'<var class="term">nn</var>'


Where:
<ul>
<li><var class="term">u</var> is the user class.</li>

<li><var class="term">pc</var> is a procedure class defined for that user class.</li>

<li><var class="term">nn</var> is a privilege byte constructed from combinations of the following bit settings:
<table>
<tr class="head">
<th> Bit </th>
<th>Privilege</th>
</tr>

<tr>
<td align="right"> X'80' </td>
<td>USE</td>
</tr>

<tr>
<td align="right"> X'40' </td>
<td>COPY</td>
</tr>

<tr>
<td align="right"> X'20' </td>
<td>CHANGE </td>
</tr>

<tr>
<td align="right"> X'10' </td>
<td>DEFINE</td>
</tr>

<tr>
<td align="right"> X'08' </td>
<td>DELETE</td>
</tr>
</table></li>
</ul></li>

<li>If NOUSE is specified, information is displayed at your terminal even if a USE command preceded the DISPLAY command. The device specified by the USE command is not used but is left open.</li>
</ul>

See the discussion of other DISPLAY command capabilities in [[ Field display and message broadcast#Overview|Overview]].

===Sample security scheme===

A simplified example of a security scheme at an installation is presented in this section. At this installation, the following access rules are established:
<ul>
<li>Most users are allowed to include all secured procedures.</li>

<li>Only programmers in the data processing department are allowed to define procedures. However, they cannot use them. These programmers can have user classes 8 or 9.</li>

<li>Only users in the payroll department are allowed to use procedures that manipulate salary fields in the file. Payroll users are assigned class 90, and the payroll procedures are in procedure classes 20 and 30.</li>

<li>Other users are assigned user classes 25, 30, or 31.</li>

<li>Other procedures are in procedure classes 40, 50, 60, or 70. </li>
</ul>

===Sample SECURE commands===

To create the security scheme in this example, issue the following commands:
SECURE PROC ACCESS=(CHANGE,DEFINE,DELETE,COPY) UCLASS=8,9 PCLASS=20,30,40,50,60,70
SECURE PROC ACCESS=(USE) UCLASS=90 PCLASS=20,30
SECURE PROC ACCESS=(USE) UCLASS=25,30,31,90 -
PCLASS=40,50,60,70


====Importance of SECURE command order====

In this example, the order of the SECURE commands is unimportant. However, the order becomes significant when a UCLASS=ALL or PCLASS=ALL clause is included in the command. UCLASS=ALL affects only user classes already mentioned in the ACT. This might be completely different from the list of user classes that actually can be assigned to users from the password table or default file or group settings.

When PCLASS=ALL is included in the command, no new entries are added to the ACT. Instead, for each user class in the UCLASS list, access rights for each procedure class already mentioned for that user are replaced by the new ACCESS rights. Again, the classes affected in the ACT may be completely different from those actually used for secured procedures in the file. 

===Changing and adding access privileges===

Suppose, in this sample security, that the payroll users now need to be able to display all the procedures that they use. Also, suppose that a new set of procedures (of class 15) is developed that all users (including the programmers) can include. The following commands are issued in the order shown to modify the ACT entries already built:
SECURE PROC ACCESS=(USE) UCLASS=ALL PCLASS=15
SECURE PROC ACCESS=(USE,COPY) UCLASS=90 PCLASS=ALL


If these commands are reversed, the payroll users cannot display members of the new class of procedures.

===Removing procedure security for procedures or user classes===

To remove the procedure access defined for user class/procedure class pairs, use the DESECURE command:
<ol>
<li>Remove the security for the procedure involved. </li>
<li>Delete the procedure class number assigned to the procedure in the procedure dictionary by issuing the form of the DESECURE command immediately below. </li>
</ol>
Note:
If you do not do this, no one can access the procedure, even though the entry might have been removed from the ACT (see the second form of DESECURE below). 

Only file managers can issue the DESECURE command and it must be issued in file context (that is, the current default must be a file, not a group). 

The format of the DESECURE command is:

DESECURE PROCEDURE {ALL | NAME=(procname[,procname...])}


Where:

<var class="term">procname</var> is the name of an existing secured procedure.

To remove particular access privileges for particular procedure classes, use the following form of the DESECURE command to delete entries from the ACT. You must specify either UCLASS or PCLASS, or both.

The format is:
DESECURE <var>PROC</var>EDURE
{[UCLASS= {ALL | (uclass[,uclass...])}] |
[PCLASS= {ALL | (pclass[,pclass...])}]}


Where:
<ul>
<li><var class="term">uclass</var> is the number of an existing user class whose users have access to the procedure in <var class="term">pclass</var>; the number must be in the range 1-255. If only UCLASS is specified, all references to the specified user classes are removed from the ACT.

Parentheses are optional with <var class="term">uclass</var>.
</li>

<li><var class="term">pclass</var> is the number of an existing procedure class to which users in <var class="term">uclass</var> have access; the number must be in the range 1-255. If only <var class="term">pclass</var> is specified, all references to the specified procedure classes are removed from the ACT.

Parentheses are optional with <var class="term">pclass</var>. 
</li>
</ul>

===Desecuring both UCLASS and PCLASS===

If both UCLASS and PCLASS are specified, the entries for all combinations of the specified user and procedure class pairs are removed from the ACT. For example:
DESECURE PROC UCLASS=8,9 PCLASS=1,2,3


removes access entries for:
UCLASS 8 and PCLASS 1
UCLASS 8 and PCLASS 2
UCLASS 8 and PCLASS 3
UCLASS 9 and PCLASS 1
UCLASS 9 and PCLASS 2
UCLASS 9 and PCLASS 3


===System manager responsibilities===

The final step in the desecuring process is to have the system manager remove the password(s) with associated uclasses from the password table. If they are not removed, you must remember not to use them when opening the file.

===Privileges required===

You must have file-level privileges of at least X'A000' (file manager and ad hoc data update) to issue SECURE and DESECURE commands. In this case, you actually need update but not retrieve privileges. (Refer to [[#File security|File security]] for a discussion of these privileges.) 

===File and group references===

When an explicit reference is made to a file with an IN clause and that file is opened only as a member of one or more permanent groups, the file-level privileges to be checked must be obtained from the group privileges, as defined for every group of which the file is a member. If any group's privileges allow the access in question, then the operation proceeds.

If the access is to a secured procedure, for every group in which the file is opened and the access is allowed by the group privileges, the user's user class in that group is used to determine privileges for that procedure's class. If any group's user class has the privilege, the operation proceeds.

See the discussion of reference context in the example on [[#Determining user access levels|Determining user access levels]] and see [[Files, groups, and reference context]] for more information. 

==Subsystem security==

When a user enters a subsystem, <var class="product">Model 204</var> opens and determines privileges for all subsystem files and groups for that user. The files that are opened and the privileges that are assigned are based on a combination of the user's subsystem user class and the subsystem's status, both specified by the system manager in the subsystem definition. 

The system manager assigns a user to a subsystem user class by entering the user's <var class="product">Model 204</var> login user ID in the appropriate subsystem user class. Whenever the user invokes the subsystem, the user is assigned the subsystem command privileges and the file and group privileges of that subsystem user class. 

The system manager controls access to the subsystem through the subsystem status: public, semipublic, or private. The status determines which user classes can enter a particular subsystem and whether or not users without a user class assignment are permitted entry. 

For more information about subsystems, see [[System requirements for Application Subsystems]].

==Terminal security==

<var class="product">Model 204</var> terminal security allows access to certain login user IDs, files, or groups to be restricted to users at certain terminals. For example, you might want a particular MEDICAL file to be accessible only through terminals located physically in doctors' offices. 

The terminal security feature allows a list of terminal numbers to be associated with each login, file, or group password. A terminal number is determined during <var class="product">Model 204</var> initialization by the order of the user parameter lines and the way in which they are assigned to specific telecommunications unit numbers in the JCL. 

The batch user (User 0) is considered to be terminal 0 (zero). A user at a particular terminal whose number is n can log in to a specific user ID or open a specific file or group only if the terminal number, n, is in the terminal list associated with the password for that user ID, file, or group. If it is not, <var class="product">Model 204</var> responds as though the user had entered an invalid password.

Terminal security is generally used with only hard-wired terminals, that is, terminals on leased lines. If an installation has dialup terminals, the terminal can be connected to a number of similar telecommunications units and user parameter lines. In this case, although the location of the terminal can be fixed, its terminal number can change every time it is dialed up. 

The entries in the ACT do not take effect for users that have the file open when the SECURE command is issued until they reopen the file. This includes the user who issues the command. The complete syntax and description of the SECURE command is located in the ry time it is dialed up.

By controlling the assignment of terminal numbers to physical terminals, the system manager determines the appropriate terminal security scheme. You provide assistance in limiting file and group access through file passwords and privileges, and group passwords and privileges.

</div> 

[[Category:Model 204 files]]

HLI: Model 204 security

2023-11-17T19:16:56Z

JDamon:

==Overview==

This topic briefly describes Model 204 security for application programmers who are using the Host Language Interface facility. 


For more information about Model 204 security, see the [[Security interfaces overview]]. 

See also:
[[Storing security information (CCASTAT)]]
[[Establishing and maintaining security]]

==Using Model 204 security==

Model 204 provides a variety of security features that prevent unauthorized use of IDs, files, groups, records, and fields. When a particular security feature is operational, the corresponding access restrictions apply. 

===Login security===

Login security requires you to enter a password when logging in. Only a valid password can gain access to the system. After successfully logging in, you are granted particular privileges. 

When login security is in effect, specify login information using the following HLI calls:
<ul>
<li>
For an IFSTRT thread in IFAM1, use the IFLOG call to provide login information, as necessary, where the user authorization is to be validated by a security interface.</li>
<li>
In IFAM2 and IFAM4, specify the login parameter in the IFSTRT call to supply the user ID and password that permit entry to the system. </li>
<li>
For an IFDIAL thread, supply the login information, as necessary, using the IFWRITE call.</li>
</ul>

===File security===

File security requires you to specify a legal password in the IFOPEN call. After you successfully open the file, Model 204 grants you particular file privileges, a user class number, and field security levels. 

===Group security===

Group security requires you to specify a legal password in the IFOPEN for the file group. 

===Record security===

Record security limits access to records by allowing you to retrieve and update only records that you have stored in the file or that users can share.

===Field-level security===

Field-level security protects fields in a file. Field access levels are assigned when you open a file or group. Specify the security level associated with a field in the IFDFLD call. 

===Terminal security===
Terminal security allows particular login user IDs and particular files and file groups to be accessed only from specific Model 204 threads.

==See also==
{{Template: HLI programming topic list}}

[[Category: Host Language Interface]]

Model 204 security features

2023-11-17T19:13:34Z

JDamon: /* Multi-factor Authentication - MFA */

<div class="toclimit-3">

==Overview==

A variety of security features provide <var class="product">Model 204</var> users with protection against unauthorized use of their account names, files, groups, records, fields, procedures, and terminals. This section describes the role of the file manager in maintaining <var class="product">Model 204</var> security. 

===Additional documentation on security features===
<ul>
<li>System manager responsibilities are described in detail in [[Storing security information (CCASTAT)#Overview|Storing security information (CCASTAT)]].</li>

<li>Rocket Software has add-on interfaces between <var class="product">Model 204</var> and a number of security products. These security interfaces are described in the [[:Category:Security interfaces|Security interfaces]] pages.</li>

<li>SSL/TLS security features for Janus products are described in [[Janus Network Security]]. </li>
</ul>

===Using the Model 204 password table===

The <var class="product">Model 204</var> password table is the backbone to the security features in <var class="product">Model 204</var>. The user must enter a valid password to access the <var class="product">Model 204</var> Online, files, groups of files, and subsystems, which in turn affects access to records. The security feature in <var class="product">Model 204</var> is not based on a hierarchy, but rather on direct password validation.

The password table, CCASTAT, is set up by the system manager. When the file manager determines which users or groups of users can have access to what data, then the file manager works with the system manager to correctly set up the password table and file access. 

===Types of security===

All <var class="product">Model 204</var> security features are optional. A site can support any combination of features. The file manager is primarily responsible for file, group, record, field, and procedure security. Both system and file managers handle terminal security. The file manager's responsibilities are described in this topic. 
<table>
<tr class="head">
<th>Type of security</th>
<th>Function</th>
</tr>

<tr>
<td>Login (System manager)</td>
<td>Limits access to the <var class="product">Model 204</var> system by requiring an individual user to enter a password when logging in. Only users who enter a valid password can gain access to the system. When a user successfully logs in, specified privileges are granted.
See [[Storing security information (CCASTAT)#Login security|Login security]] and the <var>[[LOGCTL command (user ID entries)|LOGCTL]]</var> command for modifying user ID entries.
</td>
</tr>

<tr>
<td>[[#File security|File]] (File manager)</td>
<td>Protects certain types of files by requiring a user to specify a valid file password in the OPEN command or OPEN statement. After successfully opening a file, a user is granted particular privileges pertaining to the data and procedures in that file, as well as a user class number for procedure security, and field-level security access levels. </td>
</tr>

<tr>
<td>[[#Group security|Group]] (File manager) </td>
<td>Protects certain types of file groups by requiring a user to specify a valid group password in the OPEN command or OPEN statement. When a user successfully opens a permanent group, the user is granted specified privileges that pertain to the files in the group. When opening a temporary group, the user is granted the privileges that all the member files have in common. </td>
</tr>

<tr>
<td>[[#Record security|Record]] (File manager) </td>
<td>Limits access to particular records in a <var class="product">Model 204</var> file. When record security is in effect, a user can retrieve and update only those records stored by the user's login ID or records that other users have agreed to share. </td>
</tr>

<tr>
<td>[[#Field-level security|Field-level]] (File manager) </td>
<td>Protects sensitive fields in a <var class="product">Model 204</var> file. Field-level security levels are granted when opening a file or group, and they indicate the type of access (for example, READ, UPDATE) to the field that the user is allowed. </td>
</tr>

<tr>
<td>[[#Procedure security|Procedure]] (File manager) </td>
<td>Limits access to the procedures in a file. It indicates whether a user is authorized to access particular procedures and specifies the type of access (for example, DEFINE, DELETE) that the user is allowed in secured procedures. </td>
</tr>

<tr>
<td>[[#Subsystem security|Subsystem]] (System manager) </td>
<td>Controls the privileges that are assigned to users who enter a subsystem. The system manager assigns users subsystem command privileges and privileges for each file and group in the subsystem. </td>
</tr>

<tr>
<td nowrap>[[#Terminal security|Terminal]] (File and system managers) </td>
<td>Allows specified login user IDs and specified files and file groups to be accessed only from certain hard-wired terminals. </td>
</tr>
</table>

====Multi-factor Authentication - MFA====
<tr>
<td>
Support for logon with Multi-factor authentication (MFA) is also provided with no updates or parameter changes required to Model 204. MFA does require that one of the three security interfaces, listed below, be linked into the Model 204 nucleus. Once a userid is provisioned under MFA, the user acquires a token from a client, e.g. IBM Security Verify, installed on the user's mobile device. That token is then concatenated, with a password or passphrase, to logon to Model 204. For example: token:password or token:passphrase, where colon (:) is the concatenating character. That string is passed, unmodified, to the security interface for verification.
<ul>
<li>ACF2
<li>RACF
<li>TopSecret
</ul>
</td>
</tr>

==File security==

<var class="product">Model 204</var> file security features allow you to restrict access to particular files to designated users, as well as to limit the operations that can be performed on those files. Although you are primarily responsible for determining the file security scheme in a <var class="product">Model 204</var> system, you can allow users to change a password for a file if you provide them with the appropriate login privileges. 

Security for files opened in a subsystem operates differently. See [[#Subsystem security|Subsystem security]] for more information.

===File manager's responsibilities===

Ordinarily, the file manager determines which files and file parameters to protect from unauthorized access and determines the initial passwords and associated privileges for the files. It is then the system manager's responsibility to add entries for these files to the password table. The password table contains password and privilege information for files, file groups, and login user IDs.
Maintaining this table is discussed in [[Storing security information (CCASTAT)#Password table data set|Password table data set]]. 

====Defining access levels for files====

The file manager is responsible for defining the default access levels for public and semipublic <var class="product">Model 204</var> files. You are also responsible for determining the four access levels that belong with each file or group password. These levels are then added by the system manager.

===File privileges===

File privileges determine the type of operations that the user is authorized to perform on the file that is being opened. The types of files are:
<table>
<tr class="head">
<th>If the file is...</th>
<th>Then Model 204...</th>
</tr>

<tr>
<td>Public</td>
<td>Opens the file without asking for a file password and grants the user default file privileges as specified by the <var>PRIVDEF</var> parameter.</td>
</tr>

<tr>
<td>Semipublic</td>
<td>Prompts the user to enter a valid password:
<ul>
<li>If the user enters a valid password, the user is given the privileges associated with that password. </li>

<li>If the user does not know the password or enters an incorrect password, the file is still opened but the user is granted the default file privileges associated with the file.</li>
</ul>
</td>
</tr>

<tr>
<td>Private</td>
<td>Prompts the user to enter a valid password:
<ul>
<li>If the user enters a valid password, the file is opened and the user is granted the privileges associated with that password. </li>
<li>If the user does not know the password or enters an invalid password, the file is not opened. </li>
</ul>
</td>
</tr>
</table>

====OPEN command and OPEN statement====

For a discussion of the <var>OPEN</var> command and the way in which a user specifies a password when opening different types of files,
refer to [[OPEN FILE command]] and also see [[Files, groups, and reference context#OPEN statement and OPENC_statement|OPEN statement and OPENC statement]]. 

===Creating files with file security===

When a file is first created with the CREATE command, you can limit access to the file by setting two system parameters, <var>OPENCTL</var> and <var>PRIVDEF</var>, and by asking the system manager to enter one or more file passwords in the password table. Also, the <var>OPENCTL</var> and <var>PRIVDEF</var> parameters can be reset at a later time.

The following sections provide a further description of file passwords and privileges, as well as the <var>OPENCTL</var> and <var>PRIVDEF</var> parameters. 

===File passwords and privileges===

You can define several passwords for a file. Each password can have a different set of privileges associated with it. These privileges determine what operations can be performed on the file by the user who opens the file with that password.

If you do not specify values for <var>OPENCTL</var> and <var>PRIVDEF</var> when you create the file, the file is assumed to be a public file that has a full set of default file privileges. This implies that any user can open the file using the <var>OPEN</var> command or <var>OPEN</var> statement without having to enter a file password, and can then retrieve and update data, define and run procedures, or access file parameters.

====Creating passwords====

Passwords can be up to eight characters long and cannot contain blanks, commas, or colons. 

===OPENCTL parameter===

The <var>OPENCTL</var> parameter determines whether or not a user must enter a file password when opening the file. Except as specified in the following table, <var>OPENCTL</var> settings can be added together. The first three settings are mutually exclusive and one of them must be included in your <var>OPENCTL</var> specification. The remaining settings in the table are options that you can add to one of the first three settings. 
<table>
<tr class="head">
<th>Setting</th>
<th>Means file is...</th>
<th>Password handling</th>
</tr>

<tr>
<td align="right">X'80'</td>
<td>Public</td>
<td>

Password is not requested and the file is opened with default privileges. 

This setting cannot be combined with X'40'.
</td>
</tr>

<tr>
<td align="right">X'40'</td>
<td>Semipublic</td>
<td>

User is asked for a password. For a valid password, the user is given the associated privileges. Otherwise, the user is granted default file privileges. 

This setting cannot be combined with X'80'.
</td>
</tr>

<tr>
<td align="right">X'00'</td>
<td>Private</td>
<td>Without a valid password the file is not opened.</td>
</tr>

<tr>
<td align="right">X'20'</td>
<td>Using record security</td>
<td>

No effect.

The user must have a security level that permits some type of access.
</td>
</tr>

<tr class="head">
<th colspan="3">Additional options for Parallel Query Option (PQO)</th>
</tr>

<tr>
<td align="right">X'08'</td>
<td>Accessible remotely without a valid password </td>
<td>

For a public file, no password is requested and the file is opened with default privileges.

For a semipublic file, a password is requested. If the password is missing or invalid, the user is granted default file privileges.

For a private file, or a semipublic file that a remote user presents a valid password for, the file is opened if X'02' is set. 
</td>
</tr>

<tr>
<td align="right">X'04'</td>
<td>Accessible remotely as a permanent group member</td>
<td><var class="product">Model 204</var> permanent group security is in effect. Password handling for local users is unaffected.</td>
</tr>

<tr>
<td align="right">X'02'</td>
<td>Accessible remotely with a valid password</td>
<td>For a private file, or a semipublic file that a remote user presents a valid password for, the file is opened. </td>
</tr>

<tr>
<td align="right">X'00'</td>
<td>Accessible remotely through APSY</td>
<td>For any file, no password is requested and the file cannot be opened remotely, except within a trusted subsystem.</td>
</tr>
</table>

For PQO sites, the OPENCTL parameter determines how a file can be accessed remotely. The PQO remote access settings have no meaning for local files. For more information about PQO remote files, see [[PQO: Remote files and scattered groups]].

===PRIVDEF parameter and file privileges===

The PRIVDEF parameter summarizes the default file privileges that are assigned when a public file is opened, or when a semipublic file is opened without a password or with an invalid password. Privileges can be set to any combination of the following bit settings. These privileges are identical to the privileges that can be specified for an individual file password in the password table. 
<table>
<tr class="head">
<th>Bit</th>
<th>User can...</th>
</tr>

<tr>
<td align="right"> X'8000'</td>
<td>Issue file manager privileged commands such as INITIALIZE, SECURE, and DESECURE. The file manager can also reset file parameters, provided that ad hoc update privileges (X'2000') are obtained. </td>
</tr>

<tr>
<td align="right"> X'4000'</td>
<td>Override record security; see [[#Record security|Record security]].</td>
</tr>

<tr>
<td align="right"> X'2000'</td>
<td>Update data with ad hoc requests or host language programs. </td>
</tr>

<tr>
<td align="right"> X'1000'</td>
<td>Make changes to internal procedures, that is, procedures defined in the same file as the data, but cannot delete them.</td>
</tr>

<tr>
<td align="right"> X'0800'</td>
<td>Update data using internal procedures. </td>
</tr>

<tr>
<td align="right"> X'0400'</td>
<td>Retrieve data with ad hoc requests or host language programs.</td>
</tr>

<tr>
<td align="right"> X'0200'</td>
<td>Display, echo, and copy internal procedures.</td>
</tr>

<tr>
<td align="right"> X'0100'</td>
<td>Retrieve data with internal procedures.</td>
</tr>

<tr>
<td align="right"> X'0080'</td>
<td>Update data using external procedures, that is, procedures defined in a different file from the data.</td>
</tr>

<tr>
<td align="right"> X'0040'</td>
<td>Retrieve data using external procedures.</td>
</tr>

<tr>
<td align="right"> X'0020'</td>
<td>Include internal procedures.</td>
</tr>

<tr>
<td align="right"> X'0010'</td>
<td>Define internal procedures.</td>
</tr>

<tr>
<td align="right"> X'0008'</td>
<td>Delete internal procedures.</td>
</tr>

<tr>
<td align="right"> X'0001'</td>
<td>Access file related parameters. The affected parameters are described in [[ FPARMS and TABLES file parameters#Setting file parameters|Setting file parameters]].</td>
</tr>
</table>

====PRIVDEF default setting====

The default value for the PRIVDEF parameter is X'BFFF', that is, all privileges except the ability to override record security.

====Combining PRIVDEF settings====

Update privileges, for example, update using ad hoc requests, do not imply corresponding retrieval privileges. Thus, a user who has only the ability to update using ad hoc requests (X'2000' bit set) cannot find any records to update. A user must be given both update and retrieval privileges (X'2400') to update data effectively.

Similarly, privileges for data retrieval using internal procedures (X'0100') do not imply that the user can include a procedure from the file. The X'0020' privilege is required for this.

If procedure security is desired, you must relate procedure class numbers to the procedures stored in the file. Also, determine the field-level security levels for any fields in the file that are particularly sensitive and need to be protected against unauthorized access. Field and procedure security features are discussed in [[#Field-level security|Field-level security]] and [[#Procedure security|Procedure security]].

===Resetting PRIVDEF or OPENCTL===

When the OPENCTL parameter is reset to X'80' (public), the assigned privileges are those of the current value of the PRIVDEF parameter. This means that if OPENCTL is reset to X'80' while PRIVDEF is set to less than full file manager privileges, you cannot update the file or reset any file parameters. This can also occur if you reset PRIVDEF while OPENCTL is set to X'80'.

To avoid this problem, use the VIEW PRIVDEF command to ensure that you have appropriate PRIVDEF privileges before you reset OPENCTL to X'80'. Be very careful about resetting PRIVDEF for a public file.

====Regaining access====

If you do accidently lock yourself out of a file, you can regain access as follows:
<ol>
<li>Have the system manager create a permanent private group that contains the locked file.</li>
<li>Have the system manager add a group password (and tell you that password) to the password table, CCASTAT, with the privileges X'BFFF'.</li>
<li>Then, open the private group and issue one of the following commands:

IN FILE name RESET OPENCTL=X'40'

or:
IN FILE name RESET PRIVDEF=X'BFFF'

where <var class="term">name</var> is the name of the locked file. </li>
</ol>

===Securing and desecuring a file===

====Making files secure====

Securing a file ensures that a user cannot access a file illegally by running a <var class="product">Model 204</var> program with a different password table. A special key in the password table serves as the key for securing a file. The key can be changed by the system manager with the LOGKEY command. When a secured file is opened, <var class="product">Model 204</var> compares the key to a copy placed in the file by the SECURE command. The file is opened if the two fields match. If the fields do not match, the user is logged out and an error message is displayed on the operator's console. 

The SECURE command, which can be issued only by a file manager, provides additional file protection by securing the currently open file. This form of the command is issued without arguments:
SECURE


====Desecuring a file====

To desecure a previously secured file, issue the command:
DESECURE


For a description of using the SECURE and DESECURE commands with procedures, refer to [[#Procedure security|Procedure security]]. 

==Group security==

The <var class="product">Model 204</var> group security features allow access to particular file groups to be limited to certain users.The file manager is primarily responsible for group security and for the file security features discussed in the preceding section. 

===Group passwords===

Ordinarily, the file manager determines which groups to protect from unauthorized access, and indicates the passwords and associated privileges for these groups. It is then
the system manager's responsibility to add entries for these groups to the password table and recommend group parameter settings. The system manager, however, is the only user authorized to create permanent groups.
This is done with the CREATE command, as described in [[Storing and using file group definitions (CCAGRP)#Creating file groups|Creating file groups]].

====Opening permanent file groups====

If passwords are required for a permanent file group, only users who know one of the group passwords can open the group. As with file security, the group password determines the types of operations that the user is authorized to perform on the group that is being opened. The privileges associated with the password determine the extent of these operations. Group security operates differently under the Subsystem Management facility. See [[#Subsystem security|Subsystem security]]. 

====Opening temporary file groups====

Opening a temporary group is functionally equivalent to opening a series of files. Only the user who creates a temporary group can open it. To open a temporary group, the user must be able to open each file in the group individually.

====Group file privileges====

The types of permanent groups are:
<ul>
<li>Public</li>
<li>Semipublic</li>
<li>Private </li>
</ul>

These types are the same as described in [[#File manager's responsibilities|File manager's responsibilities]].

When a user opens a semipublic or private group, <var class="product">Model 204</var> requests that the user enter the password. When the group is opened, the user is granted either the privileges associated with the group password or the default privileges for the group, depending on the password supplied. Default privileges are also supplied when a public group is opened.

===Group passwords and privileges===

A permanent group can have several passwords defined for it. Like a file password, a group password can have up to eight characters and cannot contain blanks, commas, or colons. Each password can have a different set of privileges associated with it. These privileges determine what operations can be performed on the group by the user who opens the group with that password. Privileges are expressed as two hexadecimal bytes, as discussed in [[#PRIVDEF parameter and group privileges|PRIVDEF parameter and group privileges]]. 

===PRIVDEF parameter and group privileges===

If a value for PRIVDEF and a PUBLIC, SEMIPUB, or PRIVATE specification is not specified at the time that the group is created, the group is assumed to be a PUBLIC group that has default privileges of X'3FFF'. The PRIVDEF parameter, which summarizes the default privileges for a group, provides all the privileges shown for files, plus the two group privileges summarized here. These privileges are identical to the privileges that can be specified for an individual group password in the password table. The X'8000' privilege has no meaning for groups, although it can be important for individual references to member files. 
<table>
<tr class="head">
<th>Bit</th>
<th>User can...</th>
</tr>

<tr>
<td align="right"> X'0004'</td>
<td>Update data through procedures from the procedure file.</td>
</tr>

<tr>
<td align="right"> X'0002'</td>
<td>Retrieve data through procedures from the procedure file.</td>
</tr>
</table>

When a group is created, one of its member files can be designated as the procedure file. This is the file in which procedures for the group are stored and from which procedures are retrieved or deleted. 

In a group context, internal means that a file is a member of the group, while external means that a file is not a member of the group.

===Determining file and group privileges===

When a command or a SOUL statement refers to a file or group, <var class="product">Model 204</var> checks the file and group privileges to ensure that the operation is allowed. <var class="product">Model 204</var> must determine whether a file has been opened as an individual file, as a member of a permanent or temporary group, or as both.

The privileges associated with individual files and groups can be granted and combined in different ways, depending upon the [[Files, groups, and reference context#Reference context|reference context]], as shown in the following table. 
<table>
<tr class="head">
<th>Referring to...</th>
<th>User's privileges are...</th>
</tr>

<tr>
<td>Individual file</td>
<td>Same as those granted by <var class="product">Model 204</var> when the file was opened. These privileges are associated with the specified file password or, if no password is required or is incorrectly specified, the default file privileges.</td>
</tr>

<tr>
<td>Temporary or ad hoc group</td>
<td>Intersection of the individual privileges associated with the files that make up the group. <var class="product">Model 204</var> compares the privileges of all of the member files; only privileges that are common to every file are granted. </td>
</tr>

<tr>
<td>Permanent group</td>
<td>Same as those granted by <var class="product">Model 204</var> when the group is opened. These are the privileges associated with the specified group password or, if no password is required or is incorrectly specified, the default group privileges.</td>
</tr>

<tr>
<td nowrap>Member of a permanent group (<var class="term">not</var> opened individually)
</td>
<td>Those granted for the group.

If the file is opened individually, its privileges remain those granted when the file was individually opened.
</td>
</tr>

<tr>
<td>Two permanent groups (<var class="term">not</var> opened as individual files)</td>
<td>Union of the privileges associated with the groups. <var class="product">Model 204</var> combines the privileges of all open groups of which the file is a member. Any privileges specified for any of the groups are granted.</td>
</tr>

<tr>
<td>File open as both an individual and a group</td>
<td>Privileges associated with the file, not the group. No open group has an effect on the file privileges. </td>
</tr>
</table>

==Record security==

In addition to protecting an entire file or group from unauthorized access, you can also protect individual records in a file. When record security is in effect for a particular <var class="product">Model 204</var> file, each user can be allowed to retrieve and update only records stored in the file with that user's ID or records that other users have agreed to share. The user does not know that any other records exist. 

Record security can be in effect for one or more of the files in a group, but not for the group as a whole. Access to a single record depends on only the record security field defined for the record's file.

===Record security and login security===

<var class="product">Model 204</var> record security can be considered as an extension to login security and cannot be used unless the login security feature is in effect at an installation. Login security is primarily the system manager's responsibility, and it is discussed in detail in [[Storing security information (CCASTAT)#Login security|Login security]]. 

===File manager responsibilities===

Record security usually is the responsibility of the file manager. To initiate record security, set the <var>[[OPENCTL parameter|OPENCTL]]</var> parameter in the <var>CREATE</var> command to indicate that record security is in effect and describe the special record security field in the <var>INITIALIZE</var> command, which is discussed in [[Initializing files#Initializing record security files|Initializing record security files]]. You can turn off record security by using the appropriate <var>OPENCTL</var> setting with the <var>RESET</var> command, but it cannot be turned on by <var>RESET</var>. The file must be defined to have record security through the <var>CREATE</var> command.

===Setting record security for remote users===

If your site has the Parallel Query Option/204 product, you can control access to remote files with record security using the <var>[[PQOSYS parameter|PQOSYS]]</var> CCAIN system parameter.
If set, <var>PQOSYS</var> creates a special record security key for remote users.
For more information about <var>PQOSYS</var>, see [[PQO: Managing files and groups#Record security for remote users: the PQOSYS parameter|Record security for remote users: the PQOSYS parameter]]. 

===Storing and retrieving records===

After a file has been initialized with a record security key, each record stored in the file with a SOUL <var>STORE RECORD</var> statement automatically has a record security field added to it, whose value is equal to the current user's login user ID. 

====Storing record security fields through File Load or the Host Language Interface====

For records stored with a Host Language Interface <var>IFBREC</var> or <var>IFSTOR</var> function or by a file load program, a record security field must be added explicitly, along with other fields, when the record is created. For example, the following file load statement adds a record security field:
LDC RECSEC=DARCY=


Refer to [[File Load utility]] for information about the File Load utility. 

Only records that have a record security field whose value is equal to the current user's login user ID are retrieved by a SOUL <var>FIND</var> statement or Host Language Interface calls that perform a find function. If the <var>FILE LOAD</var> statement shown here is executed, for example, only a user logged in under the name <code>DARCY</code> can retrieve these records. 

===Allowing multiple access===

To share a record with another user, either you or the user can add an explicit occurrence of the record security field with a value equal to the second user's login user ID. If the second user has update privileges, that user can delete the first value of the record security field, thus making the record accessible only through the second user's user ID. 

====Multiple access in 1NF files====

To allow access to record security fields in <var>1NF</var> files, you must define the record security field as <var>INVISIBLE</var> and <var>REPEATABLE</var>.

===Overriding record security===

Occasionally, it may be necessary to override the <var class="product">Model 204</var> record security scheme. To override record security, you must have the appropriate record security override privileges at login time: the X'04' bit must be set. When the file is opened, the X'4000' bit must be set. 

If both privileges have been granted, you can retrieve all records, regardless of the record security key value associated with them. However, if you store records from User Language at this time, they still have the record security field with the value of your login ID added to them automatically.

If record security was specified for a file in a permanent group, you can override record security for the file if login and group privileges (X'4000') allow it. 

For further information regarding login security bit settings, see [[Establishing and maintaining security#File security|File security]]. 

==Field-level security==

Field-level security (FLS) provides an additional level of protection for a user's data by controlling access to the individual fields of a <var class="product">Model 204</var> file. It involves a comparison of the user's predetermined numeric access level for a field with the field's own predetermined level, for each of four types of access. Field-level security specifications are put into effect only if access to a data record has been allowed by previous file-level and record-level security checks. The following paragraphs describe in detail how field-level security operates. 

In addition to field-level access for each field, each file has a default access level (that is, all fields within the file are automatically assigned access levels).

The following parameters determine the default field access:
<table>
<tr class="head">
<th>This parameter</th>
<th>Provides this default field access...</th>
</tr>

<tr>
<td>SELLVL</td>
<td>SELECT </td>
</tr>

<tr>
<td>READLVL</td>
<td>READ </td>
</tr>

<tr>
<td>UPDTLVL</td>
<td>UPDATE </td>
</tr>

<tr>
<td>ADDLVL</td>
<td>ADD </td>
</tr>
</table>

Like PRIVDEF, these parameters can be set when a file is created, or they can be reset later. If not explicitly specified, all of these parameters are set to zero, which allows a user to access only unsecured fields (that is, fields with access levels of 0). The same four parameters can be set for a permanent group when it is created by the system manager.

===File manager responsibilities===

The file manager is responsible for determining the desired field-level security scheme and for assigning security levels to fields that are to be protected. The LEVEL option allows you to indicate the security level for the field. 

For example, if the following command is issued, only users who have access levels of 70 or greater are allowed to access the PERFORM field, which might contain an employee's performance evaluation code:
DEFINE FIELD PERFORM WITH LEVEL 70


===Types of field access===

By using the <var class="product">Model 204</var> field-level security scheme, you can protect particularly sensitive data fields from unauthorized access. A field can be accessed in several different ways.

Field-level security features limits access to a field to any combination of the following access types: 
<table>
<tr class="head">
<th>This access type</th>
<th>Allows you to...</th>
</tr>

<tr>
<td>SELECT</td>
<td>Use the field in a SOUL FIND statement or in an IFFIND call.</td>
</tr>

<tr>
<td>READ</td>
<td>Examine the value of a field, for example, in a SOUL PRINT or assignment statement or an IFGET call. </td>
</tr>

<tr>
<td>UPDATE</td>
<td>Change the value of a previously stored occurrence of a field. This type of access can be granted without a corresponding READ access, which precludes updates of the form shown below:
CHANGE fieldname = value TO value
</td>
</tr>

<tr>
<td>ADD</td>
<td>Add new occurrences of a field, including those added by a STORE RECORD statement. This type of access allows data entry clerks or other personnel to add new field occurrences or records without being able to change existing occurrences, or possibly even to examine them.

This type of access can also provide a user with the ability to add occurrences of the record security field without altering existing occurrences.
</td>
</tr>
</table>

Field-level security controls only explicit field references. Implicit references, such as retrieving a record security field with a FIND statement or adding a record security key value with STORE RECORD, are not controlled. 

===Field levels===

Every field definition can have a security level associated with it. Security levels are numbered from 0 to 255. 0 implies no security for the field; 255 implies the highest security. 

====Field-level security and field ordering====

In the <var class="product">Model 204</var> field-level security scheme, fields can be assigned security levels in a hierarchical fashion. The fields can be ordered in view of the sensitivity of the data that they contain. An example of such an ordering is shown in [[#Field levels|Field levels]], the fields being listed in order of increasing sensitivity.
<table>
<caption>Field-level ordering example</caption>
<tr class="head">
<th>Field </th>
<th>FLS READ level</th>
</tr>

<tr>
<td>Last name</td>
<td align="right">0</td>
</tr>

<tr>
<td>First name</td>
<td align="right">0</td>
</tr>

<tr>
<td>Employee number</td>
<td align="right">0</td>
</tr>

<tr>
<td>City</td>
<td align="right">10</td>
</tr>

<tr>
<td>State</td>
<td align="right">10</td>
</tr>

<tr>
<td>Zip code</td>
<td align="right">10</td>
</tr>

<tr>
<td>Street address</td>
<td align="right">20</td>
</tr>

<tr>
<td>Position</td>
<td align="right">30</td>
</tr>

<tr>
<td>Telephone number</td>
<td align="right">40</td>
</tr>

<tr>
<td>Salary</td>
<td align="right">60</td>
</tr>

<tr>
<td>Performance evaluation</td>
<td align="right">70</td>
</tr>
</table>

In [[#Field levels|Field levels]], performance evaluation is considered to be the most sensitive field in the record, followed by salary, and so on. Last name, first name, and employee number have not been assigned field-level security numbers. However, file, record, and procedure security features still can be used to control access to those fields.

===User levels===

Each user has four field-level security access levels associated with each file and group opened. These correspond to the four field access levels defined previously: SELECT, READ, UPDATE, and ADD. User levels also range from 0 to 255.

When a user attempts to access a field in a particular way, <var class="product">Model 204</var> compares the user's access level with the level assigned for the field. If the user's level for the desired type of access, for example, READ, is greater than or equal to the field's FLS level, the particular type of field access is allowed. 

====User-level security example====

For example, a user who has a READ level of 30 is permitted to print any field that has a READ level between 0 and 30, but cannot print a field that has a higher READ level. Thus, when using the file described above, a user who has a READ level of 30 can print an employee's position (and all fields that have lower FLS fields), but not the employee's telephone number, salary, or performance evaluation. An example of a possible set of access levels at an installation is shown below: 
<table>
<caption>User access levels example</caption>
<tr class="head">
<th>Employee category</th>
<th>SELECT</th>
<th>READ</th>
<th>UPDATE</th>
<th>ADD</th>
</tr>

<tr>
<td>Data entry clerks</td>
<td align="right">0</td>
<td align="right">0</td>
<td align="right">0</td>
<td align="right">60</td>
</tr>

<tr>
<td>Personnel department clerks</td>
<td align="right">50</td>
<td align="right">50</td>
<td align="right">40</td>
<td align="right">0</td>
</tr>

<tr>
<td>Personnel department supervisor</td>
<td align="right">70</td>
<td align="right">70</td>
<td align="right">70</td>
<td align="right">0</td>
</tr>

<tr>
<td>Other employees (for example, telephone operators)</td>
<td align="right">0</td>
<td align="right">10</td>
<td align="right">0</td>
<td align="right">0</td>
</tr>

<tr>
<td>Employee supervisor</td>
<td align="right">0</td>
<td align="right">70</td>
<td align="right">0</td>
<td align="right">70</td>
</tr>
</table>

The motivations for these assignments easily can be understood in relation to the sample file. Only data entry clerks can add employee records; only supervisors can add performance evaluations; only personnel department supervisors can update salaries, and so on.

====Referring to or displaying fields====

When a user's access levels are lower than permitted for the level of a particular field, a reference to the field is treated as a reference to a nonexistent field. Furthermore, the names of such fields are excluded from the output of the DISPLAY FIELD ALL command. Thus, when using the file shown in [[#User levels|User levels]], only personnel and employee supervisors know that a performance evaluation field even exists in the file. The field is never visible to other users. 

=====Limiting access to fields=====

Access to records for particular employees can be controlled in another way. Employee supervisors usually are given a password that allows them to read or add any field in the file. However, procedure- or record-level security can be used to restrict supervisors' access to only the records of their employees.

===Determining user access levels===

The access levels assigned for a user are determined when the user opens a file or a group using the
[[OPEN FILE command]], [[OPEN PERM GROUP command]], or [[OPEN TEMP GROUP command]] or using the <var>[[Files, groups, and reference context#OPEN statement and OPENC statement|OPEN]]</var> statement.
Access level assignments are made for various types of files or groups as follows: 
<ul>
<li>If a file or a permanent group is public or semipublic and an incorrect password is specified in the OPEN, the user's four access levels are taken from the file or group defaults described in [[#Procedure security|Procedure security]]. </li>

<li>If a private or semipublic file or group is opened with a valid password, the user's four access levels are the same as those associated with the password. </li>

<li>If a temporary or ad hoc group is opened, all the member files are opened separately as individual files. Opening these individual files establishes a set of four access levels for each member file.</li>
</ul>

====Access levels for temporary or ad hoc groups====

The four access levels for a temporary or ad hoc group are formed by taking the minimum of each access level across all the member files. Suppose that <code>FILEA</code> and <code>FILEB</code> have the access levels shown in the following table.
<table>
<tr class="head">
<th>File</th>
<th>SELECT</th>
<th>READ</th>
<th>UPDATE</th>
<th>ADD</th>
</tr>

<tr>
<td>FILEA</td>
<td align="right">30</td>
<td align="right">40</td>
<td align="right">10</td>
<td align="right"> 0</td>
</tr>

<tr>
<td>FILEB</td>
<td align="right">40</td>
<td align="right">30</td>
<td align="right"> 0</td>
<td align="right">10</td>
</tr>
</table>

If a temporary group named <code>FILES</code>, consisting of <code>FILEA</code> and <code>FILEB</code>, is opened, the group is assigned the access levels:
<table>
<tr class="head">
<th>Group </th>
<th> SELECT</th>
<th>READ</th>
<th>UPDATE</th>
<th>ADD</th>
</tr>

<tr>
<td>FILES</td>
<td align="right">30</td>
<td align="right">30</td>
<td align="right"> 0</td>
<td align="right"> 0</td>
</tr>
</table>

This is equivalent to the comparison of file privileges that occurs when opening a temporary or ad hoc group; see [[#Group security|Group security]].

====Examples====

The following examples show how your user access levels for a file can change as the reference context changes. In the examples, the four user-access levels, SELECT, READ, UPDATE, and ADD, are represented by their first letters.

A field reference occurs in single file context, and the file is opened as a single file:
 S R U A
OPEN FILE FILEA 100 100 10 20
BEGIN
FPC NAME=JONES
END


The four access levels used in checking field references (100, 100, 10, 20) are those assigned when <code>FILEA</code> was opened as a single file.

A field reference occurs in group context:
 S R U A
OPEN FILE GROUPA 50 75 20 0
BEGIN
FPC NAME=JONES
END


The four access levels used for checking field references in any file of the group (50, 75, 20, 0) are the four assigned when the group was opened. All the files in a group receive the same four access levels.

A field reference occurs in single file context, but the file was opened only as a member of one or more permanent groups. <code>FILEA</code> is a member of the two groups, <code>GROUPA</code> and <code>GROUPB</code>:
 S R U A
CLOSE FILE FILEA
OPEN GROUP GROUPA 50 75 20 0
OPEN GROUP GROUPB 50 50 0 100
BEGIN
IN FILEA FPC NAME=JONES
END


The four access levels used in checking field references (50, 75, 20, 100) are formed by taking the maximum level defined for the file by every group containing the file that the user has opened. 

==Procedure security==

<var class="product">Model 204</var> procedure security limits access to a file's procedures in the following ways: 
<ul>
<li>By allowing you to specify user privileges that control the type of functions that can be performed on the procedures within a file, for example, to display, define, or delete the procedure.</li>

<li>By limiting access to a procedure to only a particular class of users. This is done by assigning a procedure class number to the procedure that is being secured and a user class to the users allowed to manipulate the procedures. </li>
</ul>

These security features are discussed in greater detail in the following sections. In addition, [[#File security|File security]] and [[#Group security|Group security]] discuss the privileges that enable users to access the data in a file or group through procedures.

===Accessing procedures===

At the time a file or group is opened, particular privileges are established that concern the text of the procedures stored in the file or group. These privileges, or access rights, enable a user to manipulate a procedure in any of the following ways: 
<ul>
<li>Use the procedure, for example, by specifying it in an INCLUDE command.</li>

<li>Display and copy the procedure. This includes echoing the procedure and using the EDIT command to display or copy it. </li>

<li>Change the procedure, usually with the Editor.</li>

<li>Define a new procedure in the file with the PROCEDURE command or the Editor. </li>

<li>Delete a procedure by means of the DELETE command. </li>
</ul>

For information about the basic procedure functions, see the $Prc* and $Proc* functions in [[List of $functions]]; and for information about procedure related commands, see [[:Category:Commands]].

===Securing procedures===

The privileges established for procedure access discussed in [[#PRIVDEF parameter and file privileges|PRIVDEF parameter and file privileges]] are used to limit the way in which the procedures associated with a file or group can be accessed. <var class="product">Model 204</var> provides an additional facility that allows particular procedures to be secured and thus protected from unauthorized access. 

===User and procedure classes===

You can limit user access to procedures by assigning user classes that have access to procedures in a particular procedure class.

User and procedure classes are usually put in place as part of the security scheme for a file or group. Although every user and procedure could have a distinct class number (UCLASS and PCLASS), this approach is too complex and cumbersome for most installations. Thus, sets of procedures and users more often are handled together. 

====User classes (UCLASS)====

Examples of typical user classes are:
<ul>
<li>All employees in a department</li>
<li>All managers, regardless of department</li>
<li>All data entry personnel </li>
</ul>

====Procedure classes (PCLASS)====

Examples of typical procedure classes include procedures that:
<ul>
<li>Display salary data</li>
<li>Update personnel records</li>
<li>Perform general utility operations</li>
<li>Access sensitive fields in files </li>
</ul>

Procedure classes and user classes are arbitrary numbers that range from 1 to 255. Their only significance is in their relationship to each other. The numbers are assigned as described in [[#User and procedure classes|User and procedure classes]].

When a user opens a file or group, the user is given the privileges and user class determined by the OPEN: 
<ul>
<li>If the file or group is opened with a password, the user class is obtained from the password table, where it is stored with the privilege bytes and field-level security levels for the password.

The user class normally is provided by the file manager and entered into the password table by the system manager, as discussed in [[Storing security information (CCASTAT)#Password table maintenance|Password table maintenance]]. 
</li>

<li>If the file or group is opened without a password, the user is granted default privileges and a default user class. This default user class is the value of the PRCLDEF system parameter, which has a default value of zero and can be set by the file manager. </li>
</ul>

====Relationship between user and procedure classes====

An access control table (ACT) stored in each file assigns to particular user classes the access rights to particular procedure classes. These mappings from user class to procedure class in the ACT are created using the SECURE command described in [[#SECURE command, definition format|SECURE command, definition format]]. 

The user class established for a group applies to all its member files. If a file is opened only as part of a permanent group, any reference to a secured procedure compares the user class specified for the group against the procedure's class to determine the available access rights. 

=====Example=====

The association of user classes and procedure classes can be explained best by an example: 

Suppose that a user whose user class is 8 includes a procedure named <code>CENTEST</code>, which has a procedure class of 20. <var class="product">Model 204</var> must determine whether users of class 8 are allowed to include procedures of class 20. 

If <var class="product">Model 204</var> checks the ACT in the file in which <code>CENTEST</code> is defined and finds that an INCLUDE is permitted, the procedure is included. If, however, INCLUDE is not permitted for users of class 8, the INCLUDE does not take place and an error message is issued. 

This mapping of user and procedure classes is discussed in greater detail in the sections that follow.

====Assigning procedure classes====

A procedure class can be specified for a procedure by the file manager or by an individual user. The class can be assigned:
<ul>
<li>By the user when defining the procedure with the PROCEDURE command</li>
<li>By the file manager when securing the procedure with the SECURE command </li>
</ul>

=====User-defined procedure classes=====

When defining a procedure, the user can specify a procedure class number in the following format:
PROCEDURE name PCLASS=n


Where:

<var class="term">n</var> is any number in the range 1 through 255.

A user's access rights to procedures are checked first at the file level and then at the procedure level. Thus, if the user is to be allowed to change a secured procedure, the user must have procedure update file privileges, and the appropriate entry must have been made in the ACT.

=====File manager-defined procedure classes=====

File manager-defined procedure classes are discussed in the following sections, in context of the commands that the file manager uses for this purpose.

===SECURE command, definition format===

If you have appropriate file manager privileges, you can use the SECURE command in the following form to:
<ul>
<li>Secure both files and procedures</li>
<li>Define privileges for procedures that already have been secured</li>
<li>Make entries in the access control table</li>
</ul>

The format is:

SECURE [PROCEDURE]
NAME=procname [,procname ...] PCLASS=pclass


Where:
<ul>
<li><var class="term">procname</var> is the name of an existing procedure to be secured.</li>
<li><var class="term">pclass</var> is the procedure class number to assign to the procedure(s); the number must be in the range 1 to 255. </li>
<li>The SECURE command must be issued in file context, that is, the current default must be a file, not a group.</li>
</ul>

====Example====

The following example is a SECURE command used to secure a procedure:
SECURE PROCEDURE NAME = PAY PCLASS = 7


After this command is issued, the procedure PAY is secured with the procedure class number 7. An entry for PCLASS=7 is made in the procedure dictionary. If PAY is currently secured, its old procedure class is changed to the new class.

===SECURE command, mapping format===

The SECURE command lets you map particular access privileges and user classes to particular procedure classes. This command creates entries in the access control table. Issue the following form of the command:

SECURE [PROCEDURE]
ACCESS = {ALL | (access [,access...]) | NONE}
UCLASS = {ALL | (uclass [,uclass...])}
PCLASS = {ALL | (pclass [,pclass...])}


Where:
<ul>
<li><var class="term">access</var> is a particular privilege associated with the procedures in the procedure class. It can be one of the following:
<table>
<tr class="head">
<th>Privilege</th>
<th>Users can...</th>
</tr>

<tr>
<td>USE </td>
<td>Include procedures.</td>
</tr>

<tr>
<td>COPY </td>
<td>Display and edit (copy only) procedures.</td>
</tr>

<tr>
<td>CHANGE </td>
<td>Edit procedures.</td>
</tr>

<tr>
<td>DEFINE </td>
<td>Create new procedures (PROCEDURE and EDIT).</td>
</tr>

<tr>
<td>DELETE </td>
<td>Delete procedures.</td>
</tr>
</table></li>
<li><var class="term">uclass</var> is the user class number whose users have access to the procedures in PCLASS; the number must be in the range 1 to 255. Parentheses are optional in the uclass definition.</li>

<li><var class="term">pclass</var> is the procedure class number to which users in UCLASS have access; the number must be in the range 1 to 255. Parentheses are optional in the pclass definition. </li>
</ul>

====Example====

In the following example, only users in the Payroll Department (user class 90) are allowed to use procedures that manipulate salary fields in a file (procedure class 20 and 30):
SECURE PROC ACCESS = (USE) UCLASS = 90 PCLASS = 20,30


The entries in the ACT do not take effect for users that have the file open when the <var>SECURE</var> command is issued until they reopen the file. This includes the user who issues the command. See [[SECURE PROCEDURE ACCESS command]] for the complete syntax and description of the <var>SECURE</var> command.

To complete procedure security implementation, the system manager updates the password table using the <var>LOGCTL</var> command to assign user classes to the appropriate passwords. 

===Procedure-related commands and required privileges===

The following list is a summary of <var class="product">Model 204</var> procedure or procedure-related commands that require particular privileges. All these commands are described in the <var class="product">Model 204</var> Parameter and Command Reference. 
<table>
<caption>Privileges for procedure or procedure-related commands</caption>
<tr class="head">
<th>Command</th>
<th colspan="2">Required privileges</th>
</tr>

<tr>
<td>INCLUDE</td>
<td>USE</td>
<td> </td>
</tr>

<tr>
<td>EDIT</td>
<td>COPY</td>
<td> </td>
</tr>

<tr>
<td>DISPLAY</td>
<td>COPY (to display text)</td>
<td> </td>
</tr>

<tr>
<td>DELETE</td>
<td>DELETE</td>
<td> </td>
</tr>

<tr>
<td>ASSIGN</td>
<td>CHANGE</td>
<td> </td>
</tr>

<tr>
<td>DEASSIGN</td>
<td>CHANGE</td>
<td> </td>
</tr>

<tr>
<td>RENAME</td>
<td>CHANGE</td>
<td> </td>
</tr>

<tr class="head">
<th>Command</th>
<th>New procedure</th>
<th>Old procedure</th>
</tr>

<tr>
<td>PROCEDURE</td>
<td>DEFINE</td>
<td>CHANGE</td>
</tr>

<tr>
<td>EDIT commands:

GO END</td>
<td>DEFINE, USE* DEFINE</td>
<td>CHANGE, USE* CHANGE</td>
</tr>

<tr>
<td></td>
<td colspan="2">*COPY privileges are required in addition to USE to echo text lines of a procedure to a journal.</td>
</tr>
</table>

===Displaying user and procedure classes===

The SECURE command constructs entries in the access control table for any user classes specified in the UCLASS clause. 
Note: It is important to display procedure security and save it before reorganizing a file, so that you can reestablish the same security. You might have to upgrade your file manager privileges to include COPY, which is not part of the default privileges of a file manager.

To determine a user's access rights for various procedure classes, issue the following form of the DISPLAY command: 

DISPLAY [PROCEDURE (PRIVILEGES [,NOUSE])
[ALL | UCLASS = <var class="term">uclass</var>[,<var class="term">uclass</var>...]]


Where:
<ul>
<li>ALL displays information for all user classes. </li>

<li><var class="term">uclass</var> displays information only for the specified classes.</li>

<li>If neither is specified, your current class and privileges are displayed.

Privileges are displayed in the following format:
UCLASS=<var class="term">u</var> PCLASS=<var class="term">pc</var>,X'<var class="term">nn</var>'
.
.
.
PCLASS=<var class="term">pc</var>,X'<var class="term">nn</var>'


Where:
<ul>
<li><var class="term">u</var> is the user class.</li>

<li><var class="term">pc</var> is a procedure class defined for that user class.</li>

<li><var class="term">nn</var> is a privilege byte constructed from combinations of the following bit settings:
<table>
<tr class="head">
<th> Bit </th>
<th>Privilege</th>
</tr>

<tr>
<td align="right"> X'80' </td>
<td>USE</td>
</tr>

<tr>
<td align="right"> X'40' </td>
<td>COPY</td>
</tr>

<tr>
<td align="right"> X'20' </td>
<td>CHANGE </td>
</tr>

<tr>
<td align="right"> X'10' </td>
<td>DEFINE</td>
</tr>

<tr>
<td align="right"> X'08' </td>
<td>DELETE</td>
</tr>
</table></li>
</ul></li>

<li>If NOUSE is specified, information is displayed at your terminal even if a USE command preceded the DISPLAY command. The device specified by the USE command is not used but is left open.</li>
</ul>

See the discussion of other DISPLAY command capabilities in [[ Field display and message broadcast#Overview|Overview]].

===Sample security scheme===

A simplified example of a security scheme at an installation is presented in this section. At this installation, the following access rules are established:
<ul>
<li>Most users are allowed to include all secured procedures.</li>

<li>Only programmers in the data processing department are allowed to define procedures. However, they cannot use them. These programmers can have user classes 8 or 9.</li>

<li>Only users in the payroll department are allowed to use procedures that manipulate salary fields in the file. Payroll users are assigned class 90, and the payroll procedures are in procedure classes 20 and 30.</li>

<li>Other users are assigned user classes 25, 30, or 31.</li>

<li>Other procedures are in procedure classes 40, 50, 60, or 70. </li>
</ul>

===Sample SECURE commands===

To create the security scheme in this example, issue the following commands:
SECURE PROC ACCESS=(CHANGE,DEFINE,DELETE,COPY) UCLASS=8,9 PCLASS=20,30,40,50,60,70
SECURE PROC ACCESS=(USE) UCLASS=90 PCLASS=20,30
SECURE PROC ACCESS=(USE) UCLASS=25,30,31,90 -
PCLASS=40,50,60,70


====Importance of SECURE command order====

In this example, the order of the SECURE commands is unimportant. However, the order becomes significant when a UCLASS=ALL or PCLASS=ALL clause is included in the command. UCLASS=ALL affects only user classes already mentioned in the ACT. This might be completely different from the list of user classes that actually can be assigned to users from the password table or default file or group settings.

When PCLASS=ALL is included in the command, no new entries are added to the ACT. Instead, for each user class in the UCLASS list, access rights for each procedure class already mentioned for that user are replaced by the new ACCESS rights. Again, the classes affected in the ACT may be completely different from those actually used for secured procedures in the file. 

===Changing and adding access privileges===

Suppose, in this sample security, that the payroll users now need to be able to display all the procedures that they use. Also, suppose that a new set of procedures (of class 15) is developed that all users (including the programmers) can include. The following commands are issued in the order shown to modify the ACT entries already built:
SECURE PROC ACCESS=(USE) UCLASS=ALL PCLASS=15
SECURE PROC ACCESS=(USE,COPY) UCLASS=90 PCLASS=ALL


If these commands are reversed, the payroll users cannot display members of the new class of procedures.

===Removing procedure security for procedures or user classes===

To remove the procedure access defined for user class/procedure class pairs, use the DESECURE command:
<ol>
<li>Remove the security for the procedure involved. </li>
<li>Delete the procedure class number assigned to the procedure in the procedure dictionary by issuing the form of the DESECURE command immediately below. </li>
</ol>
Note:
If you do not do this, no one can access the procedure, even though the entry might have been removed from the ACT (see the second form of DESECURE below). 

Only file managers can issue the DESECURE command and it must be issued in file context (that is, the current default must be a file, not a group). 

The format of the DESECURE command is:

DESECURE PROCEDURE {ALL | NAME=(procname[,procname...])}


Where:

<var class="term">procname</var> is the name of an existing secured procedure.

To remove particular access privileges for particular procedure classes, use the following form of the DESECURE command to delete entries from the ACT. You must specify either UCLASS or PCLASS, or both.

The format is:
DESECURE <var>PROC</var>EDURE
{[UCLASS= {ALL | (uclass[,uclass...])}] |
[PCLASS= {ALL | (pclass[,pclass...])}]}


Where:
<ul>
<li><var class="term">uclass</var> is the number of an existing user class whose users have access to the procedure in <var class="term">pclass</var>; the number must be in the range 1-255. If only UCLASS is specified, all references to the specified user classes are removed from the ACT.

Parentheses are optional with <var class="term">uclass</var>.
</li>

<li><var class="term">pclass</var> is the number of an existing procedure class to which users in <var class="term">uclass</var> have access; the number must be in the range 1-255. If only <var class="term">pclass</var> is specified, all references to the specified procedure classes are removed from the ACT.

Parentheses are optional with <var class="term">pclass</var>. 
</li>
</ul>

===Desecuring both UCLASS and PCLASS===

If both UCLASS and PCLASS are specified, the entries for all combinations of the specified user and procedure class pairs are removed from the ACT. For example:
DESECURE PROC UCLASS=8,9 PCLASS=1,2,3


removes access entries for:
UCLASS 8 and PCLASS 1
UCLASS 8 and PCLASS 2
UCLASS 8 and PCLASS 3
UCLASS 9 and PCLASS 1
UCLASS 9 and PCLASS 2
UCLASS 9 and PCLASS 3


===System manager responsibilities===

The final step in the desecuring process is to have the system manager remove the password(s) with associated uclasses from the password table. If they are not removed, you must remember not to use them when opening the file.

===Privileges required===

You must have file-level privileges of at least X'A000' (file manager and ad hoc data update) to issue SECURE and DESECURE commands. In this case, you actually need update but not retrieve privileges. (Refer to [[#File security|File security]] for a discussion of these privileges.) 

===File and group references===

When an explicit reference is made to a file with an IN clause and that file is opened only as a member of one or more permanent groups, the file-level privileges to be checked must be obtained from the group privileges, as defined for every group of which the file is a member. If any group's privileges allow the access in question, then the operation proceeds.

If the access is to a secured procedure, for every group in which the file is opened and the access is allowed by the group privileges, the user's user class in that group is used to determine privileges for that procedure's class. If any group's user class has the privilege, the operation proceeds.

See the discussion of reference context in the example on [[#Determining user access levels|Determining user access levels]] and see [[Files, groups, and reference context]] for more information. 

==Subsystem security==

When a user enters a subsystem, <var class="product">Model 204</var> opens and determines privileges for all subsystem files and groups for that user. The files that are opened and the privileges that are assigned are based on a combination of the user's subsystem user class and the subsystem's status, both specified by the system manager in the subsystem definition. 

The system manager assigns a user to a subsystem user class by entering the user's <var class="product">Model 204</var> login user ID in the appropriate subsystem user class. Whenever the user invokes the subsystem, the user is assigned the subsystem command privileges and the file and group privileges of that subsystem user class. 

The system manager controls access to the subsystem through the subsystem status: public, semipublic, or private. The status determines which user classes can enter a particular subsystem and whether or not users without a user class assignment are permitted entry. 

For more information about subsystems, see [[System requirements for Application Subsystems]].

==Terminal security==

<var class="product">Model 204</var> terminal security allows access to certain login user IDs, files, or groups to be restricted to users at certain terminals. For example, you might want a particular MEDICAL file to be accessible only through terminals located physically in doctors' offices. 

The terminal security feature allows a list of terminal numbers to be associated with each login, file, or group password. A terminal number is determined during <var class="product">Model 204</var> initialization by the order of the user parameter lines and the way in which they are assigned to specific telecommunications unit numbers in the JCL. 

The batch user (User 0) is considered to be terminal 0 (zero). A user at a particular terminal whose number is n can log in to a specific user ID or open a specific file or group only if the terminal number, n, is in the terminal list associated with the password for that user ID, file, or group. If it is not, <var class="product">Model 204</var> responds as though the user had entered an invalid password.

Terminal security is generally used with only hard-wired terminals, that is, terminals on leased lines. If an installation has dialup terminals, the terminal can be connected to a number of similar telecommunications units and user parameter lines. In this case, although the location of the terminal can be fixed, its terminal number can change every time it is dialed up. 

The entries in the ACT do not take effect for users that have the file open when the SECURE command is issued until they reopen the file. This includes the user who issues the command. The complete syntax and description of the SECURE command is located in the ry time it is dialed up.

By controlling the assignment of terminal numbers to physical terminals, the system manager determines the appropriate terminal security scheme. You provide assistance in limiting file and group access through file passwords and privileges, and group passwords and privileges.

</div> 

[[Category:Model 204 files]]

Model 204 security features

2023-11-17T19:12:41Z

JDamon: /* Types of security */

<div class="toclimit-3">

==Overview==

A variety of security features provide <var class="product">Model 204</var> users with protection against unauthorized use of their account names, files, groups, records, fields, procedures, and terminals. This section describes the role of the file manager in maintaining <var class="product">Model 204</var> security. 

===Additional documentation on security features===
<ul>
<li>System manager responsibilities are described in detail in [[Storing security information (CCASTAT)#Overview|Storing security information (CCASTAT)]].</li>

<li>Rocket Software has add-on interfaces between <var class="product">Model 204</var> and a number of security products. These security interfaces are described in the [[:Category:Security interfaces|Security interfaces]] pages.</li>

<li>SSL/TLS security features for Janus products are described in [[Janus Network Security]]. </li>
</ul>

===Using the Model 204 password table===

The <var class="product">Model 204</var> password table is the backbone to the security features in <var class="product">Model 204</var>. The user must enter a valid password to access the <var class="product">Model 204</var> Online, files, groups of files, and subsystems, which in turn affects access to records. The security feature in <var class="product">Model 204</var> is not based on a hierarchy, but rather on direct password validation.

The password table, CCASTAT, is set up by the system manager. When the file manager determines which users or groups of users can have access to what data, then the file manager works with the system manager to correctly set up the password table and file access. 

===Types of security===

All <var class="product">Model 204</var> security features are optional. A site can support any combination of features. The file manager is primarily responsible for file, group, record, field, and procedure security. Both system and file managers handle terminal security. The file manager's responsibilities are described in this topic. 
<table>
<tr class="head">
<th>Type of security</th>
<th>Function</th>
</tr>

<tr>
<td>Login (System manager)</td>
<td>Limits access to the <var class="product">Model 204</var> system by requiring an individual user to enter a password when logging in. Only users who enter a valid password can gain access to the system. When a user successfully logs in, specified privileges are granted.
See [[Storing security information (CCASTAT)#Login security|Login security]] and the <var>[[LOGCTL command (user ID entries)|LOGCTL]]</var> command for modifying user ID entries.
</td>
</tr>

<tr>
<td>[[#File security|File]] (File manager)</td>
<td>Protects certain types of files by requiring a user to specify a valid file password in the OPEN command or OPEN statement. After successfully opening a file, a user is granted particular privileges pertaining to the data and procedures in that file, as well as a user class number for procedure security, and field-level security access levels. </td>
</tr>

<tr>
<td>[[#Group security|Group]] (File manager) </td>
<td>Protects certain types of file groups by requiring a user to specify a valid group password in the OPEN command or OPEN statement. When a user successfully opens a permanent group, the user is granted specified privileges that pertain to the files in the group. When opening a temporary group, the user is granted the privileges that all the member files have in common. </td>
</tr>

<tr>
<td>[[#Record security|Record]] (File manager) </td>
<td>Limits access to particular records in a <var class="product">Model 204</var> file. When record security is in effect, a user can retrieve and update only those records stored by the user's login ID or records that other users have agreed to share. </td>
</tr>

<tr>
<td>[[#Field-level security|Field-level]] (File manager) </td>
<td>Protects sensitive fields in a <var class="product">Model 204</var> file. Field-level security levels are granted when opening a file or group, and they indicate the type of access (for example, READ, UPDATE) to the field that the user is allowed. </td>
</tr>

<tr>
<td>[[#Procedure security|Procedure]] (File manager) </td>
<td>Limits access to the procedures in a file. It indicates whether a user is authorized to access particular procedures and specifies the type of access (for example, DEFINE, DELETE) that the user is allowed in secured procedures. </td>
</tr>

<tr>
<td>[[#Subsystem security|Subsystem]] (System manager) </td>
<td>Controls the privileges that are assigned to users who enter a subsystem. The system manager assigns users subsystem command privileges and privileges for each file and group in the subsystem. </td>
</tr>

<tr>
<td nowrap>[[#Terminal security|Terminal]] (File and system managers) </td>
<td>Allows specified login user IDs and specified files and file groups to be accessed only from certain hard-wired terminals. </td>
</tr>
</table>

====Multi-factor Authentication - MFA====
<table>
<tr>
<td>
Support for logon with Multi-factor authentication (MFA) is also provided with no updates or parameter changes required to Model 204. MFA does require that one of the three security interfaces, listed below, be linked into the Model 204 nucleus. Once a userid is provisioned under MFA, the user acquires a token from a client, e.g. IBM Security Verify, installed on the user's mobile device. That token is then concatenated, with a password or passphrase, to logon to Model 204. For example: token:password or token:passphrase, where colon (:) is the concatenating character. That string is passed, unmodified, to the security interface for verification.
<ul>
<li>ACF2
<li>RACF
<li>TopSecret
</ul>
</td>
</tr>

==File security==

<var class="product">Model 204</var> file security features allow you to restrict access to particular files to designated users, as well as to limit the operations that can be performed on those files. Although you are primarily responsible for determining the file security scheme in a <var class="product">Model 204</var> system, you can allow users to change a password for a file if you provide them with the appropriate login privileges. 

Security for files opened in a subsystem operates differently. See [[#Subsystem security|Subsystem security]] for more information.

===File manager's responsibilities===

Ordinarily, the file manager determines which files and file parameters to protect from unauthorized access and determines the initial passwords and associated privileges for the files. It is then the system manager's responsibility to add entries for these files to the password table. The password table contains password and privilege information for files, file groups, and login user IDs.
Maintaining this table is discussed in [[Storing security information (CCASTAT)#Password table data set|Password table data set]]. 

====Defining access levels for files====

The file manager is responsible for defining the default access levels for public and semipublic <var class="product">Model 204</var> files. You are also responsible for determining the four access levels that belong with each file or group password. These levels are then added by the system manager.

===File privileges===

File privileges determine the type of operations that the user is authorized to perform on the file that is being opened. The types of files are:
<table>
<tr class="head">
<th>If the file is...</th>
<th>Then Model 204...</th>
</tr>

<tr>
<td>Public</td>
<td>Opens the file without asking for a file password and grants the user default file privileges as specified by the <var>PRIVDEF</var> parameter.</td>
</tr>

<tr>
<td>Semipublic</td>
<td>Prompts the user to enter a valid password:
<ul>
<li>If the user enters a valid password, the user is given the privileges associated with that password. </li>

<li>If the user does not know the password or enters an incorrect password, the file is still opened but the user is granted the default file privileges associated with the file.</li>
</ul>
</td>
</tr>

<tr>
<td>Private</td>
<td>Prompts the user to enter a valid password:
<ul>
<li>If the user enters a valid password, the file is opened and the user is granted the privileges associated with that password. </li>
<li>If the user does not know the password or enters an invalid password, the file is not opened. </li>
</ul>
</td>
</tr>
</table>

====OPEN command and OPEN statement====

For a discussion of the <var>OPEN</var> command and the way in which a user specifies a password when opening different types of files,
refer to [[OPEN FILE command]] and also see [[Files, groups, and reference context#OPEN statement and OPENC_statement|OPEN statement and OPENC statement]]. 

===Creating files with file security===

When a file is first created with the CREATE command, you can limit access to the file by setting two system parameters, <var>OPENCTL</var> and <var>PRIVDEF</var>, and by asking the system manager to enter one or more file passwords in the password table. Also, the <var>OPENCTL</var> and <var>PRIVDEF</var> parameters can be reset at a later time.

The following sections provide a further description of file passwords and privileges, as well as the <var>OPENCTL</var> and <var>PRIVDEF</var> parameters. 

===File passwords and privileges===

You can define several passwords for a file. Each password can have a different set of privileges associated with it. These privileges determine what operations can be performed on the file by the user who opens the file with that password.

If you do not specify values for <var>OPENCTL</var> and <var>PRIVDEF</var> when you create the file, the file is assumed to be a public file that has a full set of default file privileges. This implies that any user can open the file using the <var>OPEN</var> command or <var>OPEN</var> statement without having to enter a file password, and can then retrieve and update data, define and run procedures, or access file parameters.

====Creating passwords====

Passwords can be up to eight characters long and cannot contain blanks, commas, or colons. 

===OPENCTL parameter===

The <var>OPENCTL</var> parameter determines whether or not a user must enter a file password when opening the file. Except as specified in the following table, <var>OPENCTL</var> settings can be added together. The first three settings are mutually exclusive and one of them must be included in your <var>OPENCTL</var> specification. The remaining settings in the table are options that you can add to one of the first three settings. 
<table>
<tr class="head">
<th>Setting</th>
<th>Means file is...</th>
<th>Password handling</th>
</tr>

<tr>
<td align="right">X'80'</td>
<td>Public</td>
<td>

Password is not requested and the file is opened with default privileges. 

This setting cannot be combined with X'40'.
</td>
</tr>

<tr>
<td align="right">X'40'</td>
<td>Semipublic</td>
<td>

User is asked for a password. For a valid password, the user is given the associated privileges. Otherwise, the user is granted default file privileges. 

This setting cannot be combined with X'80'.
</td>
</tr>

<tr>
<td align="right">X'00'</td>
<td>Private</td>
<td>Without a valid password the file is not opened.</td>
</tr>

<tr>
<td align="right">X'20'</td>
<td>Using record security</td>
<td>

No effect.

The user must have a security level that permits some type of access.
</td>
</tr>

<tr class="head">
<th colspan="3">Additional options for Parallel Query Option (PQO)</th>
</tr>

<tr>
<td align="right">X'08'</td>
<td>Accessible remotely without a valid password </td>
<td>

For a public file, no password is requested and the file is opened with default privileges.

For a semipublic file, a password is requested. If the password is missing or invalid, the user is granted default file privileges.

For a private file, or a semipublic file that a remote user presents a valid password for, the file is opened if X'02' is set. 
</td>
</tr>

<tr>
<td align="right">X'04'</td>
<td>Accessible remotely as a permanent group member</td>
<td><var class="product">Model 204</var> permanent group security is in effect. Password handling for local users is unaffected.</td>
</tr>

<tr>
<td align="right">X'02'</td>
<td>Accessible remotely with a valid password</td>
<td>For a private file, or a semipublic file that a remote user presents a valid password for, the file is opened. </td>
</tr>

<tr>
<td align="right">X'00'</td>
<td>Accessible remotely through APSY</td>
<td>For any file, no password is requested and the file cannot be opened remotely, except within a trusted subsystem.</td>
</tr>
</table>

For PQO sites, the OPENCTL parameter determines how a file can be accessed remotely. The PQO remote access settings have no meaning for local files. For more information about PQO remote files, see [[PQO: Remote files and scattered groups]].

===PRIVDEF parameter and file privileges===

The PRIVDEF parameter summarizes the default file privileges that are assigned when a public file is opened, or when a semipublic file is opened without a password or with an invalid password. Privileges can be set to any combination of the following bit settings. These privileges are identical to the privileges that can be specified for an individual file password in the password table. 
<table>
<tr class="head">
<th>Bit</th>
<th>User can...</th>
</tr>

<tr>
<td align="right"> X'8000'</td>
<td>Issue file manager privileged commands such as INITIALIZE, SECURE, and DESECURE. The file manager can also reset file parameters, provided that ad hoc update privileges (X'2000') are obtained. </td>
</tr>

<tr>
<td align="right"> X'4000'</td>
<td>Override record security; see [[#Record security|Record security]].</td>
</tr>

<tr>
<td align="right"> X'2000'</td>
<td>Update data with ad hoc requests or host language programs. </td>
</tr>

<tr>
<td align="right"> X'1000'</td>
<td>Make changes to internal procedures, that is, procedures defined in the same file as the data, but cannot delete them.</td>
</tr>

<tr>
<td align="right"> X'0800'</td>
<td>Update data using internal procedures. </td>
</tr>

<tr>
<td align="right"> X'0400'</td>
<td>Retrieve data with ad hoc requests or host language programs.</td>
</tr>

<tr>
<td align="right"> X'0200'</td>
<td>Display, echo, and copy internal procedures.</td>
</tr>

<tr>
<td align="right"> X'0100'</td>
<td>Retrieve data with internal procedures.</td>
</tr>

<tr>
<td align="right"> X'0080'</td>
<td>Update data using external procedures, that is, procedures defined in a different file from the data.</td>
</tr>

<tr>
<td align="right"> X'0040'</td>
<td>Retrieve data using external procedures.</td>
</tr>

<tr>
<td align="right"> X'0020'</td>
<td>Include internal procedures.</td>
</tr>

<tr>
<td align="right"> X'0010'</td>
<td>Define internal procedures.</td>
</tr>

<tr>
<td align="right"> X'0008'</td>
<td>Delete internal procedures.</td>
</tr>

<tr>
<td align="right"> X'0001'</td>
<td>Access file related parameters. The affected parameters are described in [[ FPARMS and TABLES file parameters#Setting file parameters|Setting file parameters]].</td>
</tr>
</table>

====PRIVDEF default setting====

The default value for the PRIVDEF parameter is X'BFFF', that is, all privileges except the ability to override record security.

====Combining PRIVDEF settings====

Update privileges, for example, update using ad hoc requests, do not imply corresponding retrieval privileges. Thus, a user who has only the ability to update using ad hoc requests (X'2000' bit set) cannot find any records to update. A user must be given both update and retrieval privileges (X'2400') to update data effectively.

Similarly, privileges for data retrieval using internal procedures (X'0100') do not imply that the user can include a procedure from the file. The X'0020' privilege is required for this.

If procedure security is desired, you must relate procedure class numbers to the procedures stored in the file. Also, determine the field-level security levels for any fields in the file that are particularly sensitive and need to be protected against unauthorized access. Field and procedure security features are discussed in [[#Field-level security|Field-level security]] and [[#Procedure security|Procedure security]].

===Resetting PRIVDEF or OPENCTL===

When the OPENCTL parameter is reset to X'80' (public), the assigned privileges are those of the current value of the PRIVDEF parameter. This means that if OPENCTL is reset to X'80' while PRIVDEF is set to less than full file manager privileges, you cannot update the file or reset any file parameters. This can also occur if you reset PRIVDEF while OPENCTL is set to X'80'.

To avoid this problem, use the VIEW PRIVDEF command to ensure that you have appropriate PRIVDEF privileges before you reset OPENCTL to X'80'. Be very careful about resetting PRIVDEF for a public file.

====Regaining access====

If you do accidently lock yourself out of a file, you can regain access as follows:
<ol>
<li>Have the system manager create a permanent private group that contains the locked file.</li>
<li>Have the system manager add a group password (and tell you that password) to the password table, CCASTAT, with the privileges X'BFFF'.</li>
<li>Then, open the private group and issue one of the following commands:

IN FILE name RESET OPENCTL=X'40'

or:
IN FILE name RESET PRIVDEF=X'BFFF'

where <var class="term">name</var> is the name of the locked file. </li>
</ol>

===Securing and desecuring a file===

====Making files secure====

Securing a file ensures that a user cannot access a file illegally by running a <var class="product">Model 204</var> program with a different password table. A special key in the password table serves as the key for securing a file. The key can be changed by the system manager with the LOGKEY command. When a secured file is opened, <var class="product">Model 204</var> compares the key to a copy placed in the file by the SECURE command. The file is opened if the two fields match. If the fields do not match, the user is logged out and an error message is displayed on the operator's console. 

The SECURE command, which can be issued only by a file manager, provides additional file protection by securing the currently open file. This form of the command is issued without arguments:
SECURE


====Desecuring a file====

To desecure a previously secured file, issue the command:
DESECURE


For a description of using the SECURE and DESECURE commands with procedures, refer to [[#Procedure security|Procedure security]]. 

==Group security==

The <var class="product">Model 204</var> group security features allow access to particular file groups to be limited to certain users.The file manager is primarily responsible for group security and for the file security features discussed in the preceding section. 

===Group passwords===

Ordinarily, the file manager determines which groups to protect from unauthorized access, and indicates the passwords and associated privileges for these groups. It is then
the system manager's responsibility to add entries for these groups to the password table and recommend group parameter settings. The system manager, however, is the only user authorized to create permanent groups.
This is done with the CREATE command, as described in [[Storing and using file group definitions (CCAGRP)#Creating file groups|Creating file groups]].

====Opening permanent file groups====

If passwords are required for a permanent file group, only users who know one of the group passwords can open the group. As with file security, the group password determines the types of operations that the user is authorized to perform on the group that is being opened. The privileges associated with the password determine the extent of these operations. Group security operates differently under the Subsystem Management facility. See [[#Subsystem security|Subsystem security]]. 

====Opening temporary file groups====

Opening a temporary group is functionally equivalent to opening a series of files. Only the user who creates a temporary group can open it. To open a temporary group, the user must be able to open each file in the group individually.

====Group file privileges====

The types of permanent groups are:
<ul>
<li>Public</li>
<li>Semipublic</li>
<li>Private </li>
</ul>

These types are the same as described in [[#File manager's responsibilities|File manager's responsibilities]].

When a user opens a semipublic or private group, <var class="product">Model 204</var> requests that the user enter the password. When the group is opened, the user is granted either the privileges associated with the group password or the default privileges for the group, depending on the password supplied. Default privileges are also supplied when a public group is opened.

===Group passwords and privileges===

A permanent group can have several passwords defined for it. Like a file password, a group password can have up to eight characters and cannot contain blanks, commas, or colons. Each password can have a different set of privileges associated with it. These privileges determine what operations can be performed on the group by the user who opens the group with that password. Privileges are expressed as two hexadecimal bytes, as discussed in [[#PRIVDEF parameter and group privileges|PRIVDEF parameter and group privileges]]. 

===PRIVDEF parameter and group privileges===

If a value for PRIVDEF and a PUBLIC, SEMIPUB, or PRIVATE specification is not specified at the time that the group is created, the group is assumed to be a PUBLIC group that has default privileges of X'3FFF'. The PRIVDEF parameter, which summarizes the default privileges for a group, provides all the privileges shown for files, plus the two group privileges summarized here. These privileges are identical to the privileges that can be specified for an individual group password in the password table. The X'8000' privilege has no meaning for groups, although it can be important for individual references to member files. 
<table>
<tr class="head">
<th>Bit</th>
<th>User can...</th>
</tr>

<tr>
<td align="right"> X'0004'</td>
<td>Update data through procedures from the procedure file.</td>
</tr>

<tr>
<td align="right"> X'0002'</td>
<td>Retrieve data through procedures from the procedure file.</td>
</tr>
</table>

When a group is created, one of its member files can be designated as the procedure file. This is the file in which procedures for the group are stored and from which procedures are retrieved or deleted. 

In a group context, internal means that a file is a member of the group, while external means that a file is not a member of the group.

===Determining file and group privileges===

When a command or a SOUL statement refers to a file or group, <var class="product">Model 204</var> checks the file and group privileges to ensure that the operation is allowed. <var class="product">Model 204</var> must determine whether a file has been opened as an individual file, as a member of a permanent or temporary group, or as both.

The privileges associated with individual files and groups can be granted and combined in different ways, depending upon the [[Files, groups, and reference context#Reference context|reference context]], as shown in the following table. 
<table>
<tr class="head">
<th>Referring to...</th>
<th>User's privileges are...</th>
</tr>

<tr>
<td>Individual file</td>
<td>Same as those granted by <var class="product">Model 204</var> when the file was opened. These privileges are associated with the specified file password or, if no password is required or is incorrectly specified, the default file privileges.</td>
</tr>

<tr>
<td>Temporary or ad hoc group</td>
<td>Intersection of the individual privileges associated with the files that make up the group. <var class="product">Model 204</var> compares the privileges of all of the member files; only privileges that are common to every file are granted. </td>
</tr>

<tr>
<td>Permanent group</td>
<td>Same as those granted by <var class="product">Model 204</var> when the group is opened. These are the privileges associated with the specified group password or, if no password is required or is incorrectly specified, the default group privileges.</td>
</tr>

<tr>
<td nowrap>Member of a permanent group (<var class="term">not</var> opened individually)
</td>
<td>Those granted for the group.

If the file is opened individually, its privileges remain those granted when the file was individually opened.
</td>
</tr>

<tr>
<td>Two permanent groups (<var class="term">not</var> opened as individual files)</td>
<td>Union of the privileges associated with the groups. <var class="product">Model 204</var> combines the privileges of all open groups of which the file is a member. Any privileges specified for any of the groups are granted.</td>
</tr>

<tr>
<td>File open as both an individual and a group</td>
<td>Privileges associated with the file, not the group. No open group has an effect on the file privileges. </td>
</tr>
</table>

==Record security==

In addition to protecting an entire file or group from unauthorized access, you can also protect individual records in a file. When record security is in effect for a particular <var class="product">Model 204</var> file, each user can be allowed to retrieve and update only records stored in the file with that user's ID or records that other users have agreed to share. The user does not know that any other records exist. 

Record security can be in effect for one or more of the files in a group, but not for the group as a whole. Access to a single record depends on only the record security field defined for the record's file.

===Record security and login security===

<var class="product">Model 204</var> record security can be considered as an extension to login security and cannot be used unless the login security feature is in effect at an installation. Login security is primarily the system manager's responsibility, and it is discussed in detail in [[Storing security information (CCASTAT)#Login security|Login security]]. 

===File manager responsibilities===

Record security usually is the responsibility of the file manager. To initiate record security, set the <var>[[OPENCTL parameter|OPENCTL]]</var> parameter in the <var>CREATE</var> command to indicate that record security is in effect and describe the special record security field in the <var>INITIALIZE</var> command, which is discussed in [[Initializing files#Initializing record security files|Initializing record security files]]. You can turn off record security by using the appropriate <var>OPENCTL</var> setting with the <var>RESET</var> command, but it cannot be turned on by <var>RESET</var>. The file must be defined to have record security through the <var>CREATE</var> command.

===Setting record security for remote users===

If your site has the Parallel Query Option/204 product, you can control access to remote files with record security using the <var>[[PQOSYS parameter|PQOSYS]]</var> CCAIN system parameter.
If set, <var>PQOSYS</var> creates a special record security key for remote users.
For more information about <var>PQOSYS</var>, see [[PQO: Managing files and groups#Record security for remote users: the PQOSYS parameter|Record security for remote users: the PQOSYS parameter]]. 

===Storing and retrieving records===

After a file has been initialized with a record security key, each record stored in the file with a SOUL <var>STORE RECORD</var> statement automatically has a record security field added to it, whose value is equal to the current user's login user ID. 

====Storing record security fields through File Load or the Host Language Interface====

For records stored with a Host Language Interface <var>IFBREC</var> or <var>IFSTOR</var> function or by a file load program, a record security field must be added explicitly, along with other fields, when the record is created. For example, the following file load statement adds a record security field:
LDC RECSEC=DARCY=


Refer to [[File Load utility]] for information about the File Load utility. 

Only records that have a record security field whose value is equal to the current user's login user ID are retrieved by a SOUL <var>FIND</var> statement or Host Language Interface calls that perform a find function. If the <var>FILE LOAD</var> statement shown here is executed, for example, only a user logged in under the name <code>DARCY</code> can retrieve these records. 

===Allowing multiple access===

To share a record with another user, either you or the user can add an explicit occurrence of the record security field with a value equal to the second user's login user ID. If the second user has update privileges, that user can delete the first value of the record security field, thus making the record accessible only through the second user's user ID. 

====Multiple access in 1NF files====

To allow access to record security fields in <var>1NF</var> files, you must define the record security field as <var>INVISIBLE</var> and <var>REPEATABLE</var>.

===Overriding record security===

Occasionally, it may be necessary to override the <var class="product">Model 204</var> record security scheme. To override record security, you must have the appropriate record security override privileges at login time: the X'04' bit must be set. When the file is opened, the X'4000' bit must be set. 

If both privileges have been granted, you can retrieve all records, regardless of the record security key value associated with them. However, if you store records from User Language at this time, they still have the record security field with the value of your login ID added to them automatically.

If record security was specified for a file in a permanent group, you can override record security for the file if login and group privileges (X'4000') allow it. 

For further information regarding login security bit settings, see [[Establishing and maintaining security#File security|File security]]. 

==Field-level security==

Field-level security (FLS) provides an additional level of protection for a user's data by controlling access to the individual fields of a <var class="product">Model 204</var> file. It involves a comparison of the user's predetermined numeric access level for a field with the field's own predetermined level, for each of four types of access. Field-level security specifications are put into effect only if access to a data record has been allowed by previous file-level and record-level security checks. The following paragraphs describe in detail how field-level security operates. 

In addition to field-level access for each field, each file has a default access level (that is, all fields within the file are automatically assigned access levels).

The following parameters determine the default field access:
<table>
<tr class="head">
<th>This parameter</th>
<th>Provides this default field access...</th>
</tr>

<tr>
<td>SELLVL</td>
<td>SELECT </td>
</tr>

<tr>
<td>READLVL</td>
<td>READ </td>
</tr>

<tr>
<td>UPDTLVL</td>
<td>UPDATE </td>
</tr>

<tr>
<td>ADDLVL</td>
<td>ADD </td>
</tr>
</table>

Like PRIVDEF, these parameters can be set when a file is created, or they can be reset later. If not explicitly specified, all of these parameters are set to zero, which allows a user to access only unsecured fields (that is, fields with access levels of 0). The same four parameters can be set for a permanent group when it is created by the system manager.

===File manager responsibilities===

The file manager is responsible for determining the desired field-level security scheme and for assigning security levels to fields that are to be protected. The LEVEL option allows you to indicate the security level for the field. 

For example, if the following command is issued, only users who have access levels of 70 or greater are allowed to access the PERFORM field, which might contain an employee's performance evaluation code:
DEFINE FIELD PERFORM WITH LEVEL 70


===Types of field access===

By using the <var class="product">Model 204</var> field-level security scheme, you can protect particularly sensitive data fields from unauthorized access. A field can be accessed in several different ways.

Field-level security features limits access to a field to any combination of the following access types: 
<table>
<tr class="head">
<th>This access type</th>
<th>Allows you to...</th>
</tr>

<tr>
<td>SELECT</td>
<td>Use the field in a SOUL FIND statement or in an IFFIND call.</td>
</tr>

<tr>
<td>READ</td>
<td>Examine the value of a field, for example, in a SOUL PRINT or assignment statement or an IFGET call. </td>
</tr>

<tr>
<td>UPDATE</td>
<td>Change the value of a previously stored occurrence of a field. This type of access can be granted without a corresponding READ access, which precludes updates of the form shown below:
CHANGE fieldname = value TO value
</td>
</tr>

<tr>
<td>ADD</td>
<td>Add new occurrences of a field, including those added by a STORE RECORD statement. This type of access allows data entry clerks or other personnel to add new field occurrences or records without being able to change existing occurrences, or possibly even to examine them.

This type of access can also provide a user with the ability to add occurrences of the record security field without altering existing occurrences.
</td>
</tr>
</table>

Field-level security controls only explicit field references. Implicit references, such as retrieving a record security field with a FIND statement or adding a record security key value with STORE RECORD, are not controlled. 

===Field levels===

Every field definition can have a security level associated with it. Security levels are numbered from 0 to 255. 0 implies no security for the field; 255 implies the highest security. 

====Field-level security and field ordering====

In the <var class="product">Model 204</var> field-level security scheme, fields can be assigned security levels in a hierarchical fashion. The fields can be ordered in view of the sensitivity of the data that they contain. An example of such an ordering is shown in [[#Field levels|Field levels]], the fields being listed in order of increasing sensitivity.
<table>
<caption>Field-level ordering example</caption>
<tr class="head">
<th>Field </th>
<th>FLS READ level</th>
</tr>

<tr>
<td>Last name</td>
<td align="right">0</td>
</tr>

<tr>
<td>First name</td>
<td align="right">0</td>
</tr>

<tr>
<td>Employee number</td>
<td align="right">0</td>
</tr>

<tr>
<td>City</td>
<td align="right">10</td>
</tr>

<tr>
<td>State</td>
<td align="right">10</td>
</tr>

<tr>
<td>Zip code</td>
<td align="right">10</td>
</tr>

<tr>
<td>Street address</td>
<td align="right">20</td>
</tr>

<tr>
<td>Position</td>
<td align="right">30</td>
</tr>

<tr>
<td>Telephone number</td>
<td align="right">40</td>
</tr>

<tr>
<td>Salary</td>
<td align="right">60</td>
</tr>

<tr>
<td>Performance evaluation</td>
<td align="right">70</td>
</tr>
</table>

In [[#Field levels|Field levels]], performance evaluation is considered to be the most sensitive field in the record, followed by salary, and so on. Last name, first name, and employee number have not been assigned field-level security numbers. However, file, record, and procedure security features still can be used to control access to those fields.

===User levels===

Each user has four field-level security access levels associated with each file and group opened. These correspond to the four field access levels defined previously: SELECT, READ, UPDATE, and ADD. User levels also range from 0 to 255.

When a user attempts to access a field in a particular way, <var class="product">Model 204</var> compares the user's access level with the level assigned for the field. If the user's level for the desired type of access, for example, READ, is greater than or equal to the field's FLS level, the particular type of field access is allowed. 

====User-level security example====

For example, a user who has a READ level of 30 is permitted to print any field that has a READ level between 0 and 30, but cannot print a field that has a higher READ level. Thus, when using the file described above, a user who has a READ level of 30 can print an employee's position (and all fields that have lower FLS fields), but not the employee's telephone number, salary, or performance evaluation. An example of a possible set of access levels at an installation is shown below: 
<table>
<caption>User access levels example</caption>
<tr class="head">
<th>Employee category</th>
<th>SELECT</th>
<th>READ</th>
<th>UPDATE</th>
<th>ADD</th>
</tr>

<tr>
<td>Data entry clerks</td>
<td align="right">0</td>
<td align="right">0</td>
<td align="right">0</td>
<td align="right">60</td>
</tr>

<tr>
<td>Personnel department clerks</td>
<td align="right">50</td>
<td align="right">50</td>
<td align="right">40</td>
<td align="right">0</td>
</tr>

<tr>
<td>Personnel department supervisor</td>
<td align="right">70</td>
<td align="right">70</td>
<td align="right">70</td>
<td align="right">0</td>
</tr>

<tr>
<td>Other employees (for example, telephone operators)</td>
<td align="right">0</td>
<td align="right">10</td>
<td align="right">0</td>
<td align="right">0</td>
</tr>

<tr>
<td>Employee supervisor</td>
<td align="right">0</td>
<td align="right">70</td>
<td align="right">0</td>
<td align="right">70</td>
</tr>
</table>

The motivations for these assignments easily can be understood in relation to the sample file. Only data entry clerks can add employee records; only supervisors can add performance evaluations; only personnel department supervisors can update salaries, and so on.

====Referring to or displaying fields====

When a user's access levels are lower than permitted for the level of a particular field, a reference to the field is treated as a reference to a nonexistent field. Furthermore, the names of such fields are excluded from the output of the DISPLAY FIELD ALL command. Thus, when using the file shown in [[#User levels|User levels]], only personnel and employee supervisors know that a performance evaluation field even exists in the file. The field is never visible to other users. 

=====Limiting access to fields=====

Access to records for particular employees can be controlled in another way. Employee supervisors usually are given a password that allows them to read or add any field in the file. However, procedure- or record-level security can be used to restrict supervisors' access to only the records of their employees.

===Determining user access levels===

The access levels assigned for a user are determined when the user opens a file or a group using the
[[OPEN FILE command]], [[OPEN PERM GROUP command]], or [[OPEN TEMP GROUP command]] or using the <var>[[Files, groups, and reference context#OPEN statement and OPENC statement|OPEN]]</var> statement.
Access level assignments are made for various types of files or groups as follows: 
<ul>
<li>If a file or a permanent group is public or semipublic and an incorrect password is specified in the OPEN, the user's four access levels are taken from the file or group defaults described in [[#Procedure security|Procedure security]]. </li>

<li>If a private or semipublic file or group is opened with a valid password, the user's four access levels are the same as those associated with the password. </li>

<li>If a temporary or ad hoc group is opened, all the member files are opened separately as individual files. Opening these individual files establishes a set of four access levels for each member file.</li>
</ul>

====Access levels for temporary or ad hoc groups====

The four access levels for a temporary or ad hoc group are formed by taking the minimum of each access level across all the member files. Suppose that <code>FILEA</code> and <code>FILEB</code> have the access levels shown in the following table.
<table>
<tr class="head">
<th>File</th>
<th>SELECT</th>
<th>READ</th>
<th>UPDATE</th>
<th>ADD</th>
</tr>

<tr>
<td>FILEA</td>
<td align="right">30</td>
<td align="right">40</td>
<td align="right">10</td>
<td align="right"> 0</td>
</tr>

<tr>
<td>FILEB</td>
<td align="right">40</td>
<td align="right">30</td>
<td align="right"> 0</td>
<td align="right">10</td>
</tr>
</table>

If a temporary group named <code>FILES</code>, consisting of <code>FILEA</code> and <code>FILEB</code>, is opened, the group is assigned the access levels:
<table>
<tr class="head">
<th>Group </th>
<th> SELECT</th>
<th>READ</th>
<th>UPDATE</th>
<th>ADD</th>
</tr>

<tr>
<td>FILES</td>
<td align="right">30</td>
<td align="right">30</td>
<td align="right"> 0</td>
<td align="right"> 0</td>
</tr>
</table>

This is equivalent to the comparison of file privileges that occurs when opening a temporary or ad hoc group; see [[#Group security|Group security]].

====Examples====

The following examples show how your user access levels for a file can change as the reference context changes. In the examples, the four user-access levels, SELECT, READ, UPDATE, and ADD, are represented by their first letters.

A field reference occurs in single file context, and the file is opened as a single file:
 S R U A
OPEN FILE FILEA 100 100 10 20
BEGIN
FPC NAME=JONES
END


The four access levels used in checking field references (100, 100, 10, 20) are those assigned when <code>FILEA</code> was opened as a single file.

A field reference occurs in group context:
 S R U A
OPEN FILE GROUPA 50 75 20 0
BEGIN
FPC NAME=JONES
END


The four access levels used for checking field references in any file of the group (50, 75, 20, 0) are the four assigned when the group was opened. All the files in a group receive the same four access levels.

A field reference occurs in single file context, but the file was opened only as a member of one or more permanent groups. <code>FILEA</code> is a member of the two groups, <code>GROUPA</code> and <code>GROUPB</code>:
 S R U A
CLOSE FILE FILEA
OPEN GROUP GROUPA 50 75 20 0
OPEN GROUP GROUPB 50 50 0 100
BEGIN
IN FILEA FPC NAME=JONES
END


The four access levels used in checking field references (50, 75, 20, 100) are formed by taking the maximum level defined for the file by every group containing the file that the user has opened. 

==Procedure security==

<var class="product">Model 204</var> procedure security limits access to a file's procedures in the following ways: 
<ul>
<li>By allowing you to specify user privileges that control the type of functions that can be performed on the procedures within a file, for example, to display, define, or delete the procedure.</li>

<li>By limiting access to a procedure to only a particular class of users. This is done by assigning a procedure class number to the procedure that is being secured and a user class to the users allowed to manipulate the procedures. </li>
</ul>

These security features are discussed in greater detail in the following sections. In addition, [[#File security|File security]] and [[#Group security|Group security]] discuss the privileges that enable users to access the data in a file or group through procedures.

===Accessing procedures===

At the time a file or group is opened, particular privileges are established that concern the text of the procedures stored in the file or group. These privileges, or access rights, enable a user to manipulate a procedure in any of the following ways: 
<ul>
<li>Use the procedure, for example, by specifying it in an INCLUDE command.</li>

<li>Display and copy the procedure. This includes echoing the procedure and using the EDIT command to display or copy it. </li>

<li>Change the procedure, usually with the Editor.</li>

<li>Define a new procedure in the file with the PROCEDURE command or the Editor. </li>

<li>Delete a procedure by means of the DELETE command. </li>
</ul>

For information about the basic procedure functions, see the $Prc* and $Proc* functions in [[List of $functions]]; and for information about procedure related commands, see [[:Category:Commands]].

===Securing procedures===

The privileges established for procedure access discussed in [[#PRIVDEF parameter and file privileges|PRIVDEF parameter and file privileges]] are used to limit the way in which the procedures associated with a file or group can be accessed. <var class="product">Model 204</var> provides an additional facility that allows particular procedures to be secured and thus protected from unauthorized access. 

===User and procedure classes===

You can limit user access to procedures by assigning user classes that have access to procedures in a particular procedure class.

User and procedure classes are usually put in place as part of the security scheme for a file or group. Although every user and procedure could have a distinct class number (UCLASS and PCLASS), this approach is too complex and cumbersome for most installations. Thus, sets of procedures and users more often are handled together. 

====User classes (UCLASS)====

Examples of typical user classes are:
<ul>
<li>All employees in a department</li>
<li>All managers, regardless of department</li>
<li>All data entry personnel </li>
</ul>

====Procedure classes (PCLASS)====

Examples of typical procedure classes include procedures that:
<ul>
<li>Display salary data</li>
<li>Update personnel records</li>
<li>Perform general utility operations</li>
<li>Access sensitive fields in files </li>
</ul>

Procedure classes and user classes are arbitrary numbers that range from 1 to 255. Their only significance is in their relationship to each other. The numbers are assigned as described in [[#User and procedure classes|User and procedure classes]].

When a user opens a file or group, the user is given the privileges and user class determined by the OPEN: 
<ul>
<li>If the file or group is opened with a password, the user class is obtained from the password table, where it is stored with the privilege bytes and field-level security levels for the password.

The user class normally is provided by the file manager and entered into the password table by the system manager, as discussed in [[Storing security information (CCASTAT)#Password table maintenance|Password table maintenance]]. 
</li>

<li>If the file or group is opened without a password, the user is granted default privileges and a default user class. This default user class is the value of the PRCLDEF system parameter, which has a default value of zero and can be set by the file manager. </li>
</ul>

====Relationship between user and procedure classes====

An access control table (ACT) stored in each file assigns to particular user classes the access rights to particular procedure classes. These mappings from user class to procedure class in the ACT are created using the SECURE command described in [[#SECURE command, definition format|SECURE command, definition format]]. 

The user class established for a group applies to all its member files. If a file is opened only as part of a permanent group, any reference to a secured procedure compares the user class specified for the group against the procedure's class to determine the available access rights. 

=====Example=====

The association of user classes and procedure classes can be explained best by an example: 

Suppose that a user whose user class is 8 includes a procedure named <code>CENTEST</code>, which has a procedure class of 20. <var class="product">Model 204</var> must determine whether users of class 8 are allowed to include procedures of class 20. 

If <var class="product">Model 204</var> checks the ACT in the file in which <code>CENTEST</code> is defined and finds that an INCLUDE is permitted, the procedure is included. If, however, INCLUDE is not permitted for users of class 8, the INCLUDE does not take place and an error message is issued. 

This mapping of user and procedure classes is discussed in greater detail in the sections that follow.

====Assigning procedure classes====

A procedure class can be specified for a procedure by the file manager or by an individual user. The class can be assigned:
<ul>
<li>By the user when defining the procedure with the PROCEDURE command</li>
<li>By the file manager when securing the procedure with the SECURE command </li>
</ul>

=====User-defined procedure classes=====

When defining a procedure, the user can specify a procedure class number in the following format:
PROCEDURE name PCLASS=n


Where:

<var class="term">n</var> is any number in the range 1 through 255.

A user's access rights to procedures are checked first at the file level and then at the procedure level. Thus, if the user is to be allowed to change a secured procedure, the user must have procedure update file privileges, and the appropriate entry must have been made in the ACT.

=====File manager-defined procedure classes=====

File manager-defined procedure classes are discussed in the following sections, in context of the commands that the file manager uses for this purpose.

===SECURE command, definition format===

If you have appropriate file manager privileges, you can use the SECURE command in the following form to:
<ul>
<li>Secure both files and procedures</li>
<li>Define privileges for procedures that already have been secured</li>
<li>Make entries in the access control table</li>
</ul>

The format is:

SECURE [PROCEDURE]
NAME=procname [,procname ...] PCLASS=pclass


Where:
<ul>
<li><var class="term">procname</var> is the name of an existing procedure to be secured.</li>
<li><var class="term">pclass</var> is the procedure class number to assign to the procedure(s); the number must be in the range 1 to 255. </li>
<li>The SECURE command must be issued in file context, that is, the current default must be a file, not a group.</li>
</ul>

====Example====

The following example is a SECURE command used to secure a procedure:
SECURE PROCEDURE NAME = PAY PCLASS = 7


After this command is issued, the procedure PAY is secured with the procedure class number 7. An entry for PCLASS=7 is made in the procedure dictionary. If PAY is currently secured, its old procedure class is changed to the new class.

===SECURE command, mapping format===

The SECURE command lets you map particular access privileges and user classes to particular procedure classes. This command creates entries in the access control table. Issue the following form of the command:

SECURE [PROCEDURE]
ACCESS = {ALL | (access [,access...]) | NONE}
UCLASS = {ALL | (uclass [,uclass...])}
PCLASS = {ALL | (pclass [,pclass...])}


Where:
<ul>
<li><var class="term">access</var> is a particular privilege associated with the procedures in the procedure class. It can be one of the following:
<table>
<tr class="head">
<th>Privilege</th>
<th>Users can...</th>
</tr>

<tr>
<td>USE </td>
<td>Include procedures.</td>
</tr>

<tr>
<td>COPY </td>
<td>Display and edit (copy only) procedures.</td>
</tr>

<tr>
<td>CHANGE </td>
<td>Edit procedures.</td>
</tr>

<tr>
<td>DEFINE </td>
<td>Create new procedures (PROCEDURE and EDIT).</td>
</tr>

<tr>
<td>DELETE </td>
<td>Delete procedures.</td>
</tr>
</table></li>
<li><var class="term">uclass</var> is the user class number whose users have access to the procedures in PCLASS; the number must be in the range 1 to 255. Parentheses are optional in the uclass definition.</li>

<li><var class="term">pclass</var> is the procedure class number to which users in UCLASS have access; the number must be in the range 1 to 255. Parentheses are optional in the pclass definition. </li>
</ul>

====Example====

In the following example, only users in the Payroll Department (user class 90) are allowed to use procedures that manipulate salary fields in a file (procedure class 20 and 30):
SECURE PROC ACCESS = (USE) UCLASS = 90 PCLASS = 20,30


The entries in the ACT do not take effect for users that have the file open when the <var>SECURE</var> command is issued until they reopen the file. This includes the user who issues the command. See [[SECURE PROCEDURE ACCESS command]] for the complete syntax and description of the <var>SECURE</var> command.

To complete procedure security implementation, the system manager updates the password table using the <var>LOGCTL</var> command to assign user classes to the appropriate passwords. 

===Procedure-related commands and required privileges===

The following list is a summary of <var class="product">Model 204</var> procedure or procedure-related commands that require particular privileges. All these commands are described in the <var class="product">Model 204</var> Parameter and Command Reference. 
<table>
<caption>Privileges for procedure or procedure-related commands</caption>
<tr class="head">
<th>Command</th>
<th colspan="2">Required privileges</th>
</tr>

<tr>
<td>INCLUDE</td>
<td>USE</td>
<td> </td>
</tr>

<tr>
<td>EDIT</td>
<td>COPY</td>
<td> </td>
</tr>

<tr>
<td>DISPLAY</td>
<td>COPY (to display text)</td>
<td> </td>
</tr>

<tr>
<td>DELETE</td>
<td>DELETE</td>
<td> </td>
</tr>

<tr>
<td>ASSIGN</td>
<td>CHANGE</td>
<td> </td>
</tr>

<tr>
<td>DEASSIGN</td>
<td>CHANGE</td>
<td> </td>
</tr>

<tr>
<td>RENAME</td>
<td>CHANGE</td>
<td> </td>
</tr>

<tr class="head">
<th>Command</th>
<th>New procedure</th>
<th>Old procedure</th>
</tr>

<tr>
<td>PROCEDURE</td>
<td>DEFINE</td>
<td>CHANGE</td>
</tr>

<tr>
<td>EDIT commands:

GO END</td>
<td>DEFINE, USE* DEFINE</td>
<td>CHANGE, USE* CHANGE</td>
</tr>

<tr>
<td></td>
<td colspan="2">*COPY privileges are required in addition to USE to echo text lines of a procedure to a journal.</td>
</tr>
</table>

===Displaying user and procedure classes===

The SECURE command constructs entries in the access control table for any user classes specified in the UCLASS clause. 
Note: It is important to display procedure security and save it before reorganizing a file, so that you can reestablish the same security. You might have to upgrade your file manager privileges to include COPY, which is not part of the default privileges of a file manager.

To determine a user's access rights for various procedure classes, issue the following form of the DISPLAY command: 

DISPLAY [PROCEDURE (PRIVILEGES [,NOUSE])
[ALL | UCLASS = <var class="term">uclass</var>[,<var class="term">uclass</var>...]]


Where:
<ul>
<li>ALL displays information for all user classes. </li>

<li><var class="term">uclass</var> displays information only for the specified classes.</li>

<li>If neither is specified, your current class and privileges are displayed.

Privileges are displayed in the following format:
UCLASS=<var class="term">u</var> PCLASS=<var class="term">pc</var>,X'<var class="term">nn</var>'
.
.
.
PCLASS=<var class="term">pc</var>,X'<var class="term">nn</var>'


Where:
<ul>
<li><var class="term">u</var> is the user class.</li>

<li><var class="term">pc</var> is a procedure class defined for that user class.</li>

<li><var class="term">nn</var> is a privilege byte constructed from combinations of the following bit settings:
<table>
<tr class="head">
<th> Bit </th>
<th>Privilege</th>
</tr>

<tr>
<td align="right"> X'80' </td>
<td>USE</td>
</tr>

<tr>
<td align="right"> X'40' </td>
<td>COPY</td>
</tr>

<tr>
<td align="right"> X'20' </td>
<td>CHANGE </td>
</tr>

<tr>
<td align="right"> X'10' </td>
<td>DEFINE</td>
</tr>

<tr>
<td align="right"> X'08' </td>
<td>DELETE</td>
</tr>
</table></li>
</ul></li>

<li>If NOUSE is specified, information is displayed at your terminal even if a USE command preceded the DISPLAY command. The device specified by the USE command is not used but is left open.</li>
</ul>

See the discussion of other DISPLAY command capabilities in [[ Field display and message broadcast#Overview|Overview]].

===Sample security scheme===

A simplified example of a security scheme at an installation is presented in this section. At this installation, the following access rules are established:
<ul>
<li>Most users are allowed to include all secured procedures.</li>

<li>Only programmers in the data processing department are allowed to define procedures. However, they cannot use them. These programmers can have user classes 8 or 9.</li>

<li>Only users in the payroll department are allowed to use procedures that manipulate salary fields in the file. Payroll users are assigned class 90, and the payroll procedures are in procedure classes 20 and 30.</li>

<li>Other users are assigned user classes 25, 30, or 31.</li>

<li>Other procedures are in procedure classes 40, 50, 60, or 70. </li>
</ul>

===Sample SECURE commands===

To create the security scheme in this example, issue the following commands:
SECURE PROC ACCESS=(CHANGE,DEFINE,DELETE,COPY) UCLASS=8,9 PCLASS=20,30,40,50,60,70
SECURE PROC ACCESS=(USE) UCLASS=90 PCLASS=20,30
SECURE PROC ACCESS=(USE) UCLASS=25,30,31,90 -
PCLASS=40,50,60,70


====Importance of SECURE command order====

In this example, the order of the SECURE commands is unimportant. However, the order becomes significant when a UCLASS=ALL or PCLASS=ALL clause is included in the command. UCLASS=ALL affects only user classes already mentioned in the ACT. This might be completely different from the list of user classes that actually can be assigned to users from the password table or default file or group settings.

When PCLASS=ALL is included in the command, no new entries are added to the ACT. Instead, for each user class in the UCLASS list, access rights for each procedure class already mentioned for that user are replaced by the new ACCESS rights. Again, the classes affected in the ACT may be completely different from those actually used for secured procedures in the file. 

===Changing and adding access privileges===

Suppose, in this sample security, that the payroll users now need to be able to display all the procedures that they use. Also, suppose that a new set of procedures (of class 15) is developed that all users (including the programmers) can include. The following commands are issued in the order shown to modify the ACT entries already built:
SECURE PROC ACCESS=(USE) UCLASS=ALL PCLASS=15
SECURE PROC ACCESS=(USE,COPY) UCLASS=90 PCLASS=ALL


If these commands are reversed, the payroll users cannot display members of the new class of procedures.

===Removing procedure security for procedures or user classes===

To remove the procedure access defined for user class/procedure class pairs, use the DESECURE command:
<ol>
<li>Remove the security for the procedure involved. </li>
<li>Delete the procedure class number assigned to the procedure in the procedure dictionary by issuing the form of the DESECURE command immediately below. </li>
</ol>
Note:
If you do not do this, no one can access the procedure, even though the entry might have been removed from the ACT (see the second form of DESECURE below). 

Only file managers can issue the DESECURE command and it must be issued in file context (that is, the current default must be a file, not a group). 

The format of the DESECURE command is:

DESECURE PROCEDURE {ALL | NAME=(procname[,procname...])}


Where:

<var class="term">procname</var> is the name of an existing secured procedure.

To remove particular access privileges for particular procedure classes, use the following form of the DESECURE command to delete entries from the ACT. You must specify either UCLASS or PCLASS, or both.

The format is:
DESECURE <var>PROC</var>EDURE
{[UCLASS= {ALL | (uclass[,uclass...])}] |
[PCLASS= {ALL | (pclass[,pclass...])}]}


Where:
<ul>
<li><var class="term">uclass</var> is the number of an existing user class whose users have access to the procedure in <var class="term">pclass</var>; the number must be in the range 1-255. If only UCLASS is specified, all references to the specified user classes are removed from the ACT.

Parentheses are optional with <var class="term">uclass</var>.
</li>

<li><var class="term">pclass</var> is the number of an existing procedure class to which users in <var class="term">uclass</var> have access; the number must be in the range 1-255. If only <var class="term">pclass</var> is specified, all references to the specified procedure classes are removed from the ACT.

Parentheses are optional with <var class="term">pclass</var>. 
</li>
</ul>

===Desecuring both UCLASS and PCLASS===

If both UCLASS and PCLASS are specified, the entries for all combinations of the specified user and procedure class pairs are removed from the ACT. For example:
DESECURE PROC UCLASS=8,9 PCLASS=1,2,3


removes access entries for:
UCLASS 8 and PCLASS 1
UCLASS 8 and PCLASS 2
UCLASS 8 and PCLASS 3
UCLASS 9 and PCLASS 1
UCLASS 9 and PCLASS 2
UCLASS 9 and PCLASS 3


===System manager responsibilities===

The final step in the desecuring process is to have the system manager remove the password(s) with associated uclasses from the password table. If they are not removed, you must remember not to use them when opening the file.

===Privileges required===

You must have file-level privileges of at least X'A000' (file manager and ad hoc data update) to issue SECURE and DESECURE commands. In this case, you actually need update but not retrieve privileges. (Refer to [[#File security|File security]] for a discussion of these privileges.) 

===File and group references===

When an explicit reference is made to a file with an IN clause and that file is opened only as a member of one or more permanent groups, the file-level privileges to be checked must be obtained from the group privileges, as defined for every group of which the file is a member. If any group's privileges allow the access in question, then the operation proceeds.

If the access is to a secured procedure, for every group in which the file is opened and the access is allowed by the group privileges, the user's user class in that group is used to determine privileges for that procedure's class. If any group's user class has the privilege, the operation proceeds.

See the discussion of reference context in the example on [[#Determining user access levels|Determining user access levels]] and see [[Files, groups, and reference context]] for more information. 

==Subsystem security==

When a user enters a subsystem, <var class="product">Model 204</var> opens and determines privileges for all subsystem files and groups for that user. The files that are opened and the privileges that are assigned are based on a combination of the user's subsystem user class and the subsystem's status, both specified by the system manager in the subsystem definition. 

The system manager assigns a user to a subsystem user class by entering the user's <var class="product">Model 204</var> login user ID in the appropriate subsystem user class. Whenever the user invokes the subsystem, the user is assigned the subsystem command privileges and the file and group privileges of that subsystem user class. 

The system manager controls access to the subsystem through the subsystem status: public, semipublic, or private. The status determines which user classes can enter a particular subsystem and whether or not users without a user class assignment are permitted entry. 

For more information about subsystems, see [[System requirements for Application Subsystems]].

==Terminal security==

<var class="product">Model 204</var> terminal security allows access to certain login user IDs, files, or groups to be restricted to users at certain terminals. For example, you might want a particular MEDICAL file to be accessible only through terminals located physically in doctors' offices. 

The terminal security feature allows a list of terminal numbers to be associated with each login, file, or group password. A terminal number is determined during <var class="product">Model 204</var> initialization by the order of the user parameter lines and the way in which they are assigned to specific telecommunications unit numbers in the JCL. 

The batch user (User 0) is considered to be terminal 0 (zero). A user at a particular terminal whose number is n can log in to a specific user ID or open a specific file or group only if the terminal number, n, is in the terminal list associated with the password for that user ID, file, or group. If it is not, <var class="product">Model 204</var> responds as though the user had entered an invalid password.

Terminal security is generally used with only hard-wired terminals, that is, terminals on leased lines. If an installation has dialup terminals, the terminal can be connected to a number of similar telecommunications units and user parameter lines. In this case, although the location of the terminal can be fixed, its terminal number can change every time it is dialed up. 

The entries in the ACT do not take effect for users that have the file open when the SECURE command is issued until they reopen the file. This includes the user who issues the command. The complete syntax and description of the SECURE command is located in the ry time it is dialed up.

By controlling the assignment of terminal numbers to physical terminals, the system manager determines the appropriate terminal security scheme. You provide assistance in limiting file and group access through file passwords and privileges, and group passwords and privileges.

</div> 

[[Category:Model 204 files]]

Model 204 security features

2023-11-17T18:59:38Z

JDamon: /* Types of security */

<div class="toclimit-3">

==Overview==

A variety of security features provide <var class="product">Model 204</var> users with protection against unauthorized use of their account names, files, groups, records, fields, procedures, and terminals. This section describes the role of the file manager in maintaining <var class="product">Model 204</var> security. 

===Additional documentation on security features===
<ul>
<li>System manager responsibilities are described in detail in [[Storing security information (CCASTAT)#Overview|Storing security information (CCASTAT)]].</li>

<li>Rocket Software has add-on interfaces between <var class="product">Model 204</var> and a number of security products. These security interfaces are described in the [[:Category:Security interfaces|Security interfaces]] pages.</li>

<li>SSL/TLS security features for Janus products are described in [[Janus Network Security]]. </li>
</ul>

===Using the Model 204 password table===

The <var class="product">Model 204</var> password table is the backbone to the security features in <var class="product">Model 204</var>. The user must enter a valid password to access the <var class="product">Model 204</var> Online, files, groups of files, and subsystems, which in turn affects access to records. The security feature in <var class="product">Model 204</var> is not based on a hierarchy, but rather on direct password validation.

The password table, CCASTAT, is set up by the system manager. When the file manager determines which users or groups of users can have access to what data, then the file manager works with the system manager to correctly set up the password table and file access. 

===Types of security===

All <var class="product">Model 204</var> security features are optional. A site can support any combination of features. The file manager is primarily responsible for file, group, record, field, and procedure security. Both system and file managers handle terminal security. The file manager's responsibilities are described in this topic. 
<table>
<tr class="head">
<th>Type of security</th>
<th>Function</th>
</tr>

<tr>
<td>Login (System manager)</td>
<td>Limits access to the <var class="product">Model 204</var> system by requiring an individual user to enter a password when logging in. Only users who enter a valid password can gain access to the system. When a user successfully logs in, specified privileges are granted.
See [[Storing security information (CCASTAT)#Login security|Login security]] and the <var>[[LOGCTL command (user ID entries)|LOGCTL]]</var> command for modifying user ID entries.
</td>
</tr>

<tr>
<td>Multi-factor authentication - MFA</td>
<td>
Support for logon with Multi-factor authentication (MFA) is also provided with no updates or parameter changes required to Model 204. MFA does require that one of the three security interfaces, listed below, be linked into the Model 204 nucleus. Once a userid is provisioned under MFA, the user acquires a token from a client, e.g. IBM Security Verify, installed on the user's mobile device. That token is then concatenated, with a password or passphrase, to logon to Model 204. For example: token:password or token:passphrase, where colon (:) is the concatenating character. That string is passed, unmodified, to the security interface for verification.
<ul>
<li>ACF2
<li>RACF
<li>TopSecret
</ul>
</td>
</tr>

<tr>
<td>[[#File security|File]] (File manager)</td>
<td>Protects certain types of files by requiring a user to specify a valid file password in the OPEN command or OPEN statement. After successfully opening a file, a user is granted particular privileges pertaining to the data and procedures in that file, as well as a user class number for procedure security, and field-level security access levels. </td>
</tr>

<tr>
<td>[[#Group security|Group]] (File manager) </td>
<td>Protects certain types of file groups by requiring a user to specify a valid group password in the OPEN command or OPEN statement. When a user successfully opens a permanent group, the user is granted specified privileges that pertain to the files in the group. When opening a temporary group, the user is granted the privileges that all the member files have in common. </td>
</tr>

<tr>
<td>[[#Record security|Record]] (File manager) </td>
<td>Limits access to particular records in a <var class="product">Model 204</var> file. When record security is in effect, a user can retrieve and update only those records stored by the user's login ID or records that other users have agreed to share. </td>
</tr>

<tr>
<td>[[#Field-level security|Field-level]] (File manager) </td>
<td>Protects sensitive fields in a <var class="product">Model 204</var> file. Field-level security levels are granted when opening a file or group, and they indicate the type of access (for example, READ, UPDATE) to the field that the user is allowed. </td>
</tr>

<tr>
<td>[[#Procedure security|Procedure]] (File manager) </td>
<td>Limits access to the procedures in a file. It indicates whether a user is authorized to access particular procedures and specifies the type of access (for example, DEFINE, DELETE) that the user is allowed in secured procedures. </td>
</tr>

<tr>
<td>[[#Subsystem security|Subsystem]] (System manager) </td>
<td>Controls the privileges that are assigned to users who enter a subsystem. The system manager assigns users subsystem command privileges and privileges for each file and group in the subsystem. </td>
</tr>

<tr>
<td nowrap>[[#Terminal security|Terminal]] (File and system managers) </td>
<td>Allows specified login user IDs and specified files and file groups to be accessed only from certain hard-wired terminals. </td>
</tr>
</table>

==File security==

<var class="product">Model 204</var> file security features allow you to restrict access to particular files to designated users, as well as to limit the operations that can be performed on those files. Although you are primarily responsible for determining the file security scheme in a <var class="product">Model 204</var> system, you can allow users to change a password for a file if you provide them with the appropriate login privileges. 

Security for files opened in a subsystem operates differently. See [[#Subsystem security|Subsystem security]] for more information.

===File manager's responsibilities===

Ordinarily, the file manager determines which files and file parameters to protect from unauthorized access and determines the initial passwords and associated privileges for the files. It is then the system manager's responsibility to add entries for these files to the password table. The password table contains password and privilege information for files, file groups, and login user IDs.
Maintaining this table is discussed in [[Storing security information (CCASTAT)#Password table data set|Password table data set]]. 

====Defining access levels for files====

The file manager is responsible for defining the default access levels for public and semipublic <var class="product">Model 204</var> files. You are also responsible for determining the four access levels that belong with each file or group password. These levels are then added by the system manager.

===File privileges===

File privileges determine the type of operations that the user is authorized to perform on the file that is being opened. The types of files are:
<table>
<tr class="head">
<th>If the file is...</th>
<th>Then Model 204...</th>
</tr>

<tr>
<td>Public</td>
<td>Opens the file without asking for a file password and grants the user default file privileges as specified by the <var>PRIVDEF</var> parameter.</td>
</tr>

<tr>
<td>Semipublic</td>
<td>Prompts the user to enter a valid password:
<ul>
<li>If the user enters a valid password, the user is given the privileges associated with that password. </li>

<li>If the user does not know the password or enters an incorrect password, the file is still opened but the user is granted the default file privileges associated with the file.</li>
</ul>
</td>
</tr>

<tr>
<td>Private</td>
<td>Prompts the user to enter a valid password:
<ul>
<li>If the user enters a valid password, the file is opened and the user is granted the privileges associated with that password. </li>
<li>If the user does not know the password or enters an invalid password, the file is not opened. </li>
</ul>
</td>
</tr>
</table>

====OPEN command and OPEN statement====

For a discussion of the <var>OPEN</var> command and the way in which a user specifies a password when opening different types of files,
refer to [[OPEN FILE command]] and also see [[Files, groups, and reference context#OPEN statement and OPENC_statement|OPEN statement and OPENC statement]]. 

===Creating files with file security===

When a file is first created with the CREATE command, you can limit access to the file by setting two system parameters, <var>OPENCTL</var> and <var>PRIVDEF</var>, and by asking the system manager to enter one or more file passwords in the password table. Also, the <var>OPENCTL</var> and <var>PRIVDEF</var> parameters can be reset at a later time.

The following sections provide a further description of file passwords and privileges, as well as the <var>OPENCTL</var> and <var>PRIVDEF</var> parameters. 

===File passwords and privileges===

You can define several passwords for a file. Each password can have a different set of privileges associated with it. These privileges determine what operations can be performed on the file by the user who opens the file with that password.

If you do not specify values for <var>OPENCTL</var> and <var>PRIVDEF</var> when you create the file, the file is assumed to be a public file that has a full set of default file privileges. This implies that any user can open the file using the <var>OPEN</var> command or <var>OPEN</var> statement without having to enter a file password, and can then retrieve and update data, define and run procedures, or access file parameters.

====Creating passwords====

Passwords can be up to eight characters long and cannot contain blanks, commas, or colons. 

===OPENCTL parameter===

The <var>OPENCTL</var> parameter determines whether or not a user must enter a file password when opening the file. Except as specified in the following table, <var>OPENCTL</var> settings can be added together. The first three settings are mutually exclusive and one of them must be included in your <var>OPENCTL</var> specification. The remaining settings in the table are options that you can add to one of the first three settings. 
<table>
<tr class="head">
<th>Setting</th>
<th>Means file is...</th>
<th>Password handling</th>
</tr>

<tr>
<td align="right">X'80'</td>
<td>Public</td>
<td>

Password is not requested and the file is opened with default privileges. 

This setting cannot be combined with X'40'.
</td>
</tr>

<tr>
<td align="right">X'40'</td>
<td>Semipublic</td>
<td>

User is asked for a password. For a valid password, the user is given the associated privileges. Otherwise, the user is granted default file privileges. 

This setting cannot be combined with X'80'.
</td>
</tr>

<tr>
<td align="right">X'00'</td>
<td>Private</td>
<td>Without a valid password the file is not opened.</td>
</tr>

<tr>
<td align="right">X'20'</td>
<td>Using record security</td>
<td>

No effect.

The user must have a security level that permits some type of access.
</td>
</tr>

<tr class="head">
<th colspan="3">Additional options for Parallel Query Option (PQO)</th>
</tr>

<tr>
<td align="right">X'08'</td>
<td>Accessible remotely without a valid password </td>
<td>

For a public file, no password is requested and the file is opened with default privileges.

For a semipublic file, a password is requested. If the password is missing or invalid, the user is granted default file privileges.

For a private file, or a semipublic file that a remote user presents a valid password for, the file is opened if X'02' is set. 
</td>
</tr>

<tr>
<td align="right">X'04'</td>
<td>Accessible remotely as a permanent group member</td>
<td><var class="product">Model 204</var> permanent group security is in effect. Password handling for local users is unaffected.</td>
</tr>

<tr>
<td align="right">X'02'</td>
<td>Accessible remotely with a valid password</td>
<td>For a private file, or a semipublic file that a remote user presents a valid password for, the file is opened. </td>
</tr>

<tr>
<td align="right">X'00'</td>
<td>Accessible remotely through APSY</td>
<td>For any file, no password is requested and the file cannot be opened remotely, except within a trusted subsystem.</td>
</tr>
</table>

For PQO sites, the OPENCTL parameter determines how a file can be accessed remotely. The PQO remote access settings have no meaning for local files. For more information about PQO remote files, see [[PQO: Remote files and scattered groups]].

===PRIVDEF parameter and file privileges===

The PRIVDEF parameter summarizes the default file privileges that are assigned when a public file is opened, or when a semipublic file is opened without a password or with an invalid password. Privileges can be set to any combination of the following bit settings. These privileges are identical to the privileges that can be specified for an individual file password in the password table. 
<table>
<tr class="head">
<th>Bit</th>
<th>User can...</th>
</tr>

<tr>
<td align="right"> X'8000'</td>
<td>Issue file manager privileged commands such as INITIALIZE, SECURE, and DESECURE. The file manager can also reset file parameters, provided that ad hoc update privileges (X'2000') are obtained. </td>
</tr>

<tr>
<td align="right"> X'4000'</td>
<td>Override record security; see [[#Record security|Record security]].</td>
</tr>

<tr>
<td align="right"> X'2000'</td>
<td>Update data with ad hoc requests or host language programs. </td>
</tr>

<tr>
<td align="right"> X'1000'</td>
<td>Make changes to internal procedures, that is, procedures defined in the same file as the data, but cannot delete them.</td>
</tr>

<tr>
<td align="right"> X'0800'</td>
<td>Update data using internal procedures. </td>
</tr>

<tr>
<td align="right"> X'0400'</td>
<td>Retrieve data with ad hoc requests or host language programs.</td>
</tr>

<tr>
<td align="right"> X'0200'</td>
<td>Display, echo, and copy internal procedures.</td>
</tr>

<tr>
<td align="right"> X'0100'</td>
<td>Retrieve data with internal procedures.</td>
</tr>

<tr>
<td align="right"> X'0080'</td>
<td>Update data using external procedures, that is, procedures defined in a different file from the data.</td>
</tr>

<tr>
<td align="right"> X'0040'</td>
<td>Retrieve data using external procedures.</td>
</tr>

<tr>
<td align="right"> X'0020'</td>
<td>Include internal procedures.</td>
</tr>

<tr>
<td align="right"> X'0010'</td>
<td>Define internal procedures.</td>
</tr>

<tr>
<td align="right"> X'0008'</td>
<td>Delete internal procedures.</td>
</tr>

<tr>
<td align="right"> X'0001'</td>
<td>Access file related parameters. The affected parameters are described in [[ FPARMS and TABLES file parameters#Setting file parameters|Setting file parameters]].</td>
</tr>
</table>

====PRIVDEF default setting====

The default value for the PRIVDEF parameter is X'BFFF', that is, all privileges except the ability to override record security.

====Combining PRIVDEF settings====

Update privileges, for example, update using ad hoc requests, do not imply corresponding retrieval privileges. Thus, a user who has only the ability to update using ad hoc requests (X'2000' bit set) cannot find any records to update. A user must be given both update and retrieval privileges (X'2400') to update data effectively.

Similarly, privileges for data retrieval using internal procedures (X'0100') do not imply that the user can include a procedure from the file. The X'0020' privilege is required for this.

If procedure security is desired, you must relate procedure class numbers to the procedures stored in the file. Also, determine the field-level security levels for any fields in the file that are particularly sensitive and need to be protected against unauthorized access. Field and procedure security features are discussed in [[#Field-level security|Field-level security]] and [[#Procedure security|Procedure security]].

===Resetting PRIVDEF or OPENCTL===

When the OPENCTL parameter is reset to X'80' (public), the assigned privileges are those of the current value of the PRIVDEF parameter. This means that if OPENCTL is reset to X'80' while PRIVDEF is set to less than full file manager privileges, you cannot update the file or reset any file parameters. This can also occur if you reset PRIVDEF while OPENCTL is set to X'80'.

To avoid this problem, use the VIEW PRIVDEF command to ensure that you have appropriate PRIVDEF privileges before you reset OPENCTL to X'80'. Be very careful about resetting PRIVDEF for a public file.

====Regaining access====

If you do accidently lock yourself out of a file, you can regain access as follows:
<ol>
<li>Have the system manager create a permanent private group that contains the locked file.</li>
<li>Have the system manager add a group password (and tell you that password) to the password table, CCASTAT, with the privileges X'BFFF'.</li>
<li>Then, open the private group and issue one of the following commands:

IN FILE name RESET OPENCTL=X'40'

or:
IN FILE name RESET PRIVDEF=X'BFFF'

where <var class="term">name</var> is the name of the locked file. </li>
</ol>

===Securing and desecuring a file===

====Making files secure====

Securing a file ensures that a user cannot access a file illegally by running a <var class="product">Model 204</var> program with a different password table. A special key in the password table serves as the key for securing a file. The key can be changed by the system manager with the LOGKEY command. When a secured file is opened, <var class="product">Model 204</var> compares the key to a copy placed in the file by the SECURE command. The file is opened if the two fields match. If the fields do not match, the user is logged out and an error message is displayed on the operator's console. 

The SECURE command, which can be issued only by a file manager, provides additional file protection by securing the currently open file. This form of the command is issued without arguments:
SECURE


====Desecuring a file====

To desecure a previously secured file, issue the command:
DESECURE


For a description of using the SECURE and DESECURE commands with procedures, refer to [[#Procedure security|Procedure security]]. 

==Group security==

The <var class="product">Model 204</var> group security features allow access to particular file groups to be limited to certain users.The file manager is primarily responsible for group security and for the file security features discussed in the preceding section. 

===Group passwords===

Ordinarily, the file manager determines which groups to protect from unauthorized access, and indicates the passwords and associated privileges for these groups. It is then
the system manager's responsibility to add entries for these groups to the password table and recommend group parameter settings. The system manager, however, is the only user authorized to create permanent groups.
This is done with the CREATE command, as described in [[Storing and using file group definitions (CCAGRP)#Creating file groups|Creating file groups]].

====Opening permanent file groups====

If passwords are required for a permanent file group, only users who know one of the group passwords can open the group. As with file security, the group password determines the types of operations that the user is authorized to perform on the group that is being opened. The privileges associated with the password determine the extent of these operations. Group security operates differently under the Subsystem Management facility. See [[#Subsystem security|Subsystem security]]. 

====Opening temporary file groups====

Opening a temporary group is functionally equivalent to opening a series of files. Only the user who creates a temporary group can open it. To open a temporary group, the user must be able to open each file in the group individually.

====Group file privileges====

The types of permanent groups are:
<ul>
<li>Public</li>
<li>Semipublic</li>
<li>Private </li>
</ul>

These types are the same as described in [[#File manager's responsibilities|File manager's responsibilities]].

When a user opens a semipublic or private group, <var class="product">Model 204</var> requests that the user enter the password. When the group is opened, the user is granted either the privileges associated with the group password or the default privileges for the group, depending on the password supplied. Default privileges are also supplied when a public group is opened.

===Group passwords and privileges===

A permanent group can have several passwords defined for it. Like a file password, a group password can have up to eight characters and cannot contain blanks, commas, or colons. Each password can have a different set of privileges associated with it. These privileges determine what operations can be performed on the group by the user who opens the group with that password. Privileges are expressed as two hexadecimal bytes, as discussed in [[#PRIVDEF parameter and group privileges|PRIVDEF parameter and group privileges]]. 

===PRIVDEF parameter and group privileges===

If a value for PRIVDEF and a PUBLIC, SEMIPUB, or PRIVATE specification is not specified at the time that the group is created, the group is assumed to be a PUBLIC group that has default privileges of X'3FFF'. The PRIVDEF parameter, which summarizes the default privileges for a group, provides all the privileges shown for files, plus the two group privileges summarized here. These privileges are identical to the privileges that can be specified for an individual group password in the password table. The X'8000' privilege has no meaning for groups, although it can be important for individual references to member files. 
<table>
<tr class="head">
<th>Bit</th>
<th>User can...</th>
</tr>

<tr>
<td align="right"> X'0004'</td>
<td>Update data through procedures from the procedure file.</td>
</tr>

<tr>
<td align="right"> X'0002'</td>
<td>Retrieve data through procedures from the procedure file.</td>
</tr>
</table>

When a group is created, one of its member files can be designated as the procedure file. This is the file in which procedures for the group are stored and from which procedures are retrieved or deleted. 

In a group context, internal means that a file is a member of the group, while external means that a file is not a member of the group.

===Determining file and group privileges===

When a command or a SOUL statement refers to a file or group, <var class="product">Model 204</var> checks the file and group privileges to ensure that the operation is allowed. <var class="product">Model 204</var> must determine whether a file has been opened as an individual file, as a member of a permanent or temporary group, or as both.

The privileges associated with individual files and groups can be granted and combined in different ways, depending upon the [[Files, groups, and reference context#Reference context|reference context]], as shown in the following table. 
<table>
<tr class="head">
<th>Referring to...</th>
<th>User's privileges are...</th>
</tr>

<tr>
<td>Individual file</td>
<td>Same as those granted by <var class="product">Model 204</var> when the file was opened. These privileges are associated with the specified file password or, if no password is required or is incorrectly specified, the default file privileges.</td>
</tr>

<tr>
<td>Temporary or ad hoc group</td>
<td>Intersection of the individual privileges associated with the files that make up the group. <var class="product">Model 204</var> compares the privileges of all of the member files; only privileges that are common to every file are granted. </td>
</tr>

<tr>
<td>Permanent group</td>
<td>Same as those granted by <var class="product">Model 204</var> when the group is opened. These are the privileges associated with the specified group password or, if no password is required or is incorrectly specified, the default group privileges.</td>
</tr>

<tr>
<td nowrap>Member of a permanent group (<var class="term">not</var> opened individually)
</td>
<td>Those granted for the group.

If the file is opened individually, its privileges remain those granted when the file was individually opened.
</td>
</tr>

<tr>
<td>Two permanent groups (<var class="term">not</var> opened as individual files)</td>
<td>Union of the privileges associated with the groups. <var class="product">Model 204</var> combines the privileges of all open groups of which the file is a member. Any privileges specified for any of the groups are granted.</td>
</tr>

<tr>
<td>File open as both an individual and a group</td>
<td>Privileges associated with the file, not the group. No open group has an effect on the file privileges. </td>
</tr>
</table>

==Record security==

In addition to protecting an entire file or group from unauthorized access, you can also protect individual records in a file. When record security is in effect for a particular <var class="product">Model 204</var> file, each user can be allowed to retrieve and update only records stored in the file with that user's ID or records that other users have agreed to share. The user does not know that any other records exist. 

Record security can be in effect for one or more of the files in a group, but not for the group as a whole. Access to a single record depends on only the record security field defined for the record's file.

===Record security and login security===

<var class="product">Model 204</var> record security can be considered as an extension to login security and cannot be used unless the login security feature is in effect at an installation. Login security is primarily the system manager's responsibility, and it is discussed in detail in [[Storing security information (CCASTAT)#Login security|Login security]]. 

===File manager responsibilities===

Record security usually is the responsibility of the file manager. To initiate record security, set the <var>[[OPENCTL parameter|OPENCTL]]</var> parameter in the <var>CREATE</var> command to indicate that record security is in effect and describe the special record security field in the <var>INITIALIZE</var> command, which is discussed in [[Initializing files#Initializing record security files|Initializing record security files]]. You can turn off record security by using the appropriate <var>OPENCTL</var> setting with the <var>RESET</var> command, but it cannot be turned on by <var>RESET</var>. The file must be defined to have record security through the <var>CREATE</var> command.

===Setting record security for remote users===

If your site has the Parallel Query Option/204 product, you can control access to remote files with record security using the <var>[[PQOSYS parameter|PQOSYS]]</var> CCAIN system parameter.
If set, <var>PQOSYS</var> creates a special record security key for remote users.
For more information about <var>PQOSYS</var>, see [[PQO: Managing files and groups#Record security for remote users: the PQOSYS parameter|Record security for remote users: the PQOSYS parameter]]. 

===Storing and retrieving records===

After a file has been initialized with a record security key, each record stored in the file with a SOUL <var>STORE RECORD</var> statement automatically has a record security field added to it, whose value is equal to the current user's login user ID. 

====Storing record security fields through File Load or the Host Language Interface====

For records stored with a Host Language Interface <var>IFBREC</var> or <var>IFSTOR</var> function or by a file load program, a record security field must be added explicitly, along with other fields, when the record is created. For example, the following file load statement adds a record security field:
LDC RECSEC=DARCY=


Refer to [[File Load utility]] for information about the File Load utility. 

Only records that have a record security field whose value is equal to the current user's login user ID are retrieved by a SOUL <var>FIND</var> statement or Host Language Interface calls that perform a find function. If the <var>FILE LOAD</var> statement shown here is executed, for example, only a user logged in under the name <code>DARCY</code> can retrieve these records. 

===Allowing multiple access===

To share a record with another user, either you or the user can add an explicit occurrence of the record security field with a value equal to the second user's login user ID. If the second user has update privileges, that user can delete the first value of the record security field, thus making the record accessible only through the second user's user ID. 

====Multiple access in 1NF files====

To allow access to record security fields in <var>1NF</var> files, you must define the record security field as <var>INVISIBLE</var> and <var>REPEATABLE</var>.

===Overriding record security===

Occasionally, it may be necessary to override the <var class="product">Model 204</var> record security scheme. To override record security, you must have the appropriate record security override privileges at login time: the X'04' bit must be set. When the file is opened, the X'4000' bit must be set. 

If both privileges have been granted, you can retrieve all records, regardless of the record security key value associated with them. However, if you store records from User Language at this time, they still have the record security field with the value of your login ID added to them automatically.

If record security was specified for a file in a permanent group, you can override record security for the file if login and group privileges (X'4000') allow it. 

For further information regarding login security bit settings, see [[Establishing and maintaining security#File security|File security]]. 

==Field-level security==

Field-level security (FLS) provides an additional level of protection for a user's data by controlling access to the individual fields of a <var class="product">Model 204</var> file. It involves a comparison of the user's predetermined numeric access level for a field with the field's own predetermined level, for each of four types of access. Field-level security specifications are put into effect only if access to a data record has been allowed by previous file-level and record-level security checks. The following paragraphs describe in detail how field-level security operates. 

In addition to field-level access for each field, each file has a default access level (that is, all fields within the file are automatically assigned access levels).

The following parameters determine the default field access:
<table>
<tr class="head">
<th>This parameter</th>
<th>Provides this default field access...</th>
</tr>

<tr>
<td>SELLVL</td>
<td>SELECT </td>
</tr>

<tr>
<td>READLVL</td>
<td>READ </td>
</tr>

<tr>
<td>UPDTLVL</td>
<td>UPDATE </td>
</tr>

<tr>
<td>ADDLVL</td>
<td>ADD </td>
</tr>
</table>

Like PRIVDEF, these parameters can be set when a file is created, or they can be reset later. If not explicitly specified, all of these parameters are set to zero, which allows a user to access only unsecured fields (that is, fields with access levels of 0). The same four parameters can be set for a permanent group when it is created by the system manager.

===File manager responsibilities===

The file manager is responsible for determining the desired field-level security scheme and for assigning security levels to fields that are to be protected. The LEVEL option allows you to indicate the security level for the field. 

For example, if the following command is issued, only users who have access levels of 70 or greater are allowed to access the PERFORM field, which might contain an employee's performance evaluation code:
DEFINE FIELD PERFORM WITH LEVEL 70


===Types of field access===

By using the <var class="product">Model 204</var> field-level security scheme, you can protect particularly sensitive data fields from unauthorized access. A field can be accessed in several different ways.

Field-level security features limits access to a field to any combination of the following access types: 
<table>
<tr class="head">
<th>This access type</th>
<th>Allows you to...</th>
</tr>

<tr>
<td>SELECT</td>
<td>Use the field in a SOUL FIND statement or in an IFFIND call.</td>
</tr>

<tr>
<td>READ</td>
<td>Examine the value of a field, for example, in a SOUL PRINT or assignment statement or an IFGET call. </td>
</tr>

<tr>
<td>UPDATE</td>
<td>Change the value of a previously stored occurrence of a field. This type of access can be granted without a corresponding READ access, which precludes updates of the form shown below:
CHANGE fieldname = value TO value
</td>
</tr>

<tr>
<td>ADD</td>
<td>Add new occurrences of a field, including those added by a STORE RECORD statement. This type of access allows data entry clerks or other personnel to add new field occurrences or records without being able to change existing occurrences, or possibly even to examine them.

This type of access can also provide a user with the ability to add occurrences of the record security field without altering existing occurrences.
</td>
</tr>
</table>

Field-level security controls only explicit field references. Implicit references, such as retrieving a record security field with a FIND statement or adding a record security key value with STORE RECORD, are not controlled. 

===Field levels===

Every field definition can have a security level associated with it. Security levels are numbered from 0 to 255. 0 implies no security for the field; 255 implies the highest security. 

====Field-level security and field ordering====

In the <var class="product">Model 204</var> field-level security scheme, fields can be assigned security levels in a hierarchical fashion. The fields can be ordered in view of the sensitivity of the data that they contain. An example of such an ordering is shown in [[#Field levels|Field levels]], the fields being listed in order of increasing sensitivity.
<table>
<caption>Field-level ordering example</caption>
<tr class="head">
<th>Field </th>
<th>FLS READ level</th>
</tr>

<tr>
<td>Last name</td>
<td align="right">0</td>
</tr>

<tr>
<td>First name</td>
<td align="right">0</td>
</tr>

<tr>
<td>Employee number</td>
<td align="right">0</td>
</tr>

<tr>
<td>City</td>
<td align="right">10</td>
</tr>

<tr>
<td>State</td>
<td align="right">10</td>
</tr>

<tr>
<td>Zip code</td>
<td align="right">10</td>
</tr>

<tr>
<td>Street address</td>
<td align="right">20</td>
</tr>

<tr>
<td>Position</td>
<td align="right">30</td>
</tr>

<tr>
<td>Telephone number</td>
<td align="right">40</td>
</tr>

<tr>
<td>Salary</td>
<td align="right">60</td>
</tr>

<tr>
<td>Performance evaluation</td>
<td align="right">70</td>
</tr>
</table>

In [[#Field levels|Field levels]], performance evaluation is considered to be the most sensitive field in the record, followed by salary, and so on. Last name, first name, and employee number have not been assigned field-level security numbers. However, file, record, and procedure security features still can be used to control access to those fields.

===User levels===

Each user has four field-level security access levels associated with each file and group opened. These correspond to the four field access levels defined previously: SELECT, READ, UPDATE, and ADD. User levels also range from 0 to 255.

When a user attempts to access a field in a particular way, <var class="product">Model 204</var> compares the user's access level with the level assigned for the field. If the user's level for the desired type of access, for example, READ, is greater than or equal to the field's FLS level, the particular type of field access is allowed. 

====User-level security example====

For example, a user who has a READ level of 30 is permitted to print any field that has a READ level between 0 and 30, but cannot print a field that has a higher READ level. Thus, when using the file described above, a user who has a READ level of 30 can print an employee's position (and all fields that have lower FLS fields), but not the employee's telephone number, salary, or performance evaluation. An example of a possible set of access levels at an installation is shown below: 
<table>
<caption>User access levels example</caption>
<tr class="head">
<th>Employee category</th>
<th>SELECT</th>
<th>READ</th>
<th>UPDATE</th>
<th>ADD</th>
</tr>

<tr>
<td>Data entry clerks</td>
<td align="right">0</td>
<td align="right">0</td>
<td align="right">0</td>
<td align="right">60</td>
</tr>

<tr>
<td>Personnel department clerks</td>
<td align="right">50</td>
<td align="right">50</td>
<td align="right">40</td>
<td align="right">0</td>
</tr>

<tr>
<td>Personnel department supervisor</td>
<td align="right">70</td>
<td align="right">70</td>
<td align="right">70</td>
<td align="right">0</td>
</tr>

<tr>
<td>Other employees (for example, telephone operators)</td>
<td align="right">0</td>
<td align="right">10</td>
<td align="right">0</td>
<td align="right">0</td>
</tr>

<tr>
<td>Employee supervisor</td>
<td align="right">0</td>
<td align="right">70</td>
<td align="right">0</td>
<td align="right">70</td>
</tr>
</table>

The motivations for these assignments easily can be understood in relation to the sample file. Only data entry clerks can add employee records; only supervisors can add performance evaluations; only personnel department supervisors can update salaries, and so on.

====Referring to or displaying fields====

When a user's access levels are lower than permitted for the level of a particular field, a reference to the field is treated as a reference to a nonexistent field. Furthermore, the names of such fields are excluded from the output of the DISPLAY FIELD ALL command. Thus, when using the file shown in [[#User levels|User levels]], only personnel and employee supervisors know that a performance evaluation field even exists in the file. The field is never visible to other users. 

=====Limiting access to fields=====

Access to records for particular employees can be controlled in another way. Employee supervisors usually are given a password that allows them to read or add any field in the file. However, procedure- or record-level security can be used to restrict supervisors' access to only the records of their employees.

===Determining user access levels===

The access levels assigned for a user are determined when the user opens a file or a group using the
[[OPEN FILE command]], [[OPEN PERM GROUP command]], or [[OPEN TEMP GROUP command]] or using the <var>[[Files, groups, and reference context#OPEN statement and OPENC statement|OPEN]]</var> statement.
Access level assignments are made for various types of files or groups as follows: 
<ul>
<li>If a file or a permanent group is public or semipublic and an incorrect password is specified in the OPEN, the user's four access levels are taken from the file or group defaults described in [[#Procedure security|Procedure security]]. </li>

<li>If a private or semipublic file or group is opened with a valid password, the user's four access levels are the same as those associated with the password. </li>

<li>If a temporary or ad hoc group is opened, all the member files are opened separately as individual files. Opening these individual files establishes a set of four access levels for each member file.</li>
</ul>

====Access levels for temporary or ad hoc groups====

The four access levels for a temporary or ad hoc group are formed by taking the minimum of each access level across all the member files. Suppose that <code>FILEA</code> and <code>FILEB</code> have the access levels shown in the following table.
<table>
<tr class="head">
<th>File</th>
<th>SELECT</th>
<th>READ</th>
<th>UPDATE</th>
<th>ADD</th>
</tr>

<tr>
<td>FILEA</td>
<td align="right">30</td>
<td align="right">40</td>
<td align="right">10</td>
<td align="right"> 0</td>
</tr>

<tr>
<td>FILEB</td>
<td align="right">40</td>
<td align="right">30</td>
<td align="right"> 0</td>
<td align="right">10</td>
</tr>
</table>

If a temporary group named <code>FILES</code>, consisting of <code>FILEA</code> and <code>FILEB</code>, is opened, the group is assigned the access levels:
<table>
<tr class="head">
<th>Group </th>
<th> SELECT</th>
<th>READ</th>
<th>UPDATE</th>
<th>ADD</th>
</tr>

<tr>
<td>FILES</td>
<td align="right">30</td>
<td align="right">30</td>
<td align="right"> 0</td>
<td align="right"> 0</td>
</tr>
</table>

This is equivalent to the comparison of file privileges that occurs when opening a temporary or ad hoc group; see [[#Group security|Group security]].

====Examples====

The following examples show how your user access levels for a file can change as the reference context changes. In the examples, the four user-access levels, SELECT, READ, UPDATE, and ADD, are represented by their first letters.

A field reference occurs in single file context, and the file is opened as a single file:
 S R U A
OPEN FILE FILEA 100 100 10 20
BEGIN
FPC NAME=JONES
END


The four access levels used in checking field references (100, 100, 10, 20) are those assigned when <code>FILEA</code> was opened as a single file.

A field reference occurs in group context:
 S R U A
OPEN FILE GROUPA 50 75 20 0
BEGIN
FPC NAME=JONES
END


The four access levels used for checking field references in any file of the group (50, 75, 20, 0) are the four assigned when the group was opened. All the files in a group receive the same four access levels.

A field reference occurs in single file context, but the file was opened only as a member of one or more permanent groups. <code>FILEA</code> is a member of the two groups, <code>GROUPA</code> and <code>GROUPB</code>:
 S R U A
CLOSE FILE FILEA
OPEN GROUP GROUPA 50 75 20 0
OPEN GROUP GROUPB 50 50 0 100
BEGIN
IN FILEA FPC NAME=JONES
END


The four access levels used in checking field references (50, 75, 20, 100) are formed by taking the maximum level defined for the file by every group containing the file that the user has opened. 

==Procedure security==

<var class="product">Model 204</var> procedure security limits access to a file's procedures in the following ways: 
<ul>
<li>By allowing you to specify user privileges that control the type of functions that can be performed on the procedures within a file, for example, to display, define, or delete the procedure.</li>

<li>By limiting access to a procedure to only a particular class of users. This is done by assigning a procedure class number to the procedure that is being secured and a user class to the users allowed to manipulate the procedures. </li>
</ul>

These security features are discussed in greater detail in the following sections. In addition, [[#File security|File security]] and [[#Group security|Group security]] discuss the privileges that enable users to access the data in a file or group through procedures.

===Accessing procedures===

At the time a file or group is opened, particular privileges are established that concern the text of the procedures stored in the file or group. These privileges, or access rights, enable a user to manipulate a procedure in any of the following ways: 
<ul>
<li>Use the procedure, for example, by specifying it in an INCLUDE command.</li>

<li>Display and copy the procedure. This includes echoing the procedure and using the EDIT command to display or copy it. </li>

<li>Change the procedure, usually with the Editor.</li>

<li>Define a new procedure in the file with the PROCEDURE command or the Editor. </li>

<li>Delete a procedure by means of the DELETE command. </li>
</ul>

For information about the basic procedure functions, see the $Prc* and $Proc* functions in [[List of $functions]]; and for information about procedure related commands, see [[:Category:Commands]].

===Securing procedures===

The privileges established for procedure access discussed in [[#PRIVDEF parameter and file privileges|PRIVDEF parameter and file privileges]] are used to limit the way in which the procedures associated with a file or group can be accessed. <var class="product">Model 204</var> provides an additional facility that allows particular procedures to be secured and thus protected from unauthorized access. 

===User and procedure classes===

You can limit user access to procedures by assigning user classes that have access to procedures in a particular procedure class.

User and procedure classes are usually put in place as part of the security scheme for a file or group. Although every user and procedure could have a distinct class number (UCLASS and PCLASS), this approach is too complex and cumbersome for most installations. Thus, sets of procedures and users more often are handled together. 

====User classes (UCLASS)====

Examples of typical user classes are:
<ul>
<li>All employees in a department</li>
<li>All managers, regardless of department</li>
<li>All data entry personnel </li>
</ul>

====Procedure classes (PCLASS)====

Examples of typical procedure classes include procedures that:
<ul>
<li>Display salary data</li>
<li>Update personnel records</li>
<li>Perform general utility operations</li>
<li>Access sensitive fields in files </li>
</ul>

Procedure classes and user classes are arbitrary numbers that range from 1 to 255. Their only significance is in their relationship to each other. The numbers are assigned as described in [[#User and procedure classes|User and procedure classes]].

When a user opens a file or group, the user is given the privileges and user class determined by the OPEN: 
<ul>
<li>If the file or group is opened with a password, the user class is obtained from the password table, where it is stored with the privilege bytes and field-level security levels for the password.

The user class normally is provided by the file manager and entered into the password table by the system manager, as discussed in [[Storing security information (CCASTAT)#Password table maintenance|Password table maintenance]]. 
</li>

<li>If the file or group is opened without a password, the user is granted default privileges and a default user class. This default user class is the value of the PRCLDEF system parameter, which has a default value of zero and can be set by the file manager. </li>
</ul>

====Relationship between user and procedure classes====

An access control table (ACT) stored in each file assigns to particular user classes the access rights to particular procedure classes. These mappings from user class to procedure class in the ACT are created using the SECURE command described in [[#SECURE command, definition format|SECURE command, definition format]]. 

The user class established for a group applies to all its member files. If a file is opened only as part of a permanent group, any reference to a secured procedure compares the user class specified for the group against the procedure's class to determine the available access rights. 

=====Example=====

The association of user classes and procedure classes can be explained best by an example: 

Suppose that a user whose user class is 8 includes a procedure named <code>CENTEST</code>, which has a procedure class of 20. <var class="product">Model 204</var> must determine whether users of class 8 are allowed to include procedures of class 20. 

If <var class="product">Model 204</var> checks the ACT in the file in which <code>CENTEST</code> is defined and finds that an INCLUDE is permitted, the procedure is included. If, however, INCLUDE is not permitted for users of class 8, the INCLUDE does not take place and an error message is issued. 

This mapping of user and procedure classes is discussed in greater detail in the sections that follow.

====Assigning procedure classes====

A procedure class can be specified for a procedure by the file manager or by an individual user. The class can be assigned:
<ul>
<li>By the user when defining the procedure with the PROCEDURE command</li>
<li>By the file manager when securing the procedure with the SECURE command </li>
</ul>

=====User-defined procedure classes=====

When defining a procedure, the user can specify a procedure class number in the following format:
PROCEDURE name PCLASS=n


Where:

<var class="term">n</var> is any number in the range 1 through 255.

A user's access rights to procedures are checked first at the file level and then at the procedure level. Thus, if the user is to be allowed to change a secured procedure, the user must have procedure update file privileges, and the appropriate entry must have been made in the ACT.

=====File manager-defined procedure classes=====

File manager-defined procedure classes are discussed in the following sections, in context of the commands that the file manager uses for this purpose.

===SECURE command, definition format===

If you have appropriate file manager privileges, you can use the SECURE command in the following form to:
<ul>
<li>Secure both files and procedures</li>
<li>Define privileges for procedures that already have been secured</li>
<li>Make entries in the access control table</li>
</ul>

The format is:

SECURE [PROCEDURE]
NAME=procname [,procname ...] PCLASS=pclass


Where:
<ul>
<li><var class="term">procname</var> is the name of an existing procedure to be secured.</li>
<li><var class="term">pclass</var> is the procedure class number to assign to the procedure(s); the number must be in the range 1 to 255. </li>
<li>The SECURE command must be issued in file context, that is, the current default must be a file, not a group.</li>
</ul>

====Example====

The following example is a SECURE command used to secure a procedure:
SECURE PROCEDURE NAME = PAY PCLASS = 7


After this command is issued, the procedure PAY is secured with the procedure class number 7. An entry for PCLASS=7 is made in the procedure dictionary. If PAY is currently secured, its old procedure class is changed to the new class.

===SECURE command, mapping format===

The SECURE command lets you map particular access privileges and user classes to particular procedure classes. This command creates entries in the access control table. Issue the following form of the command:

SECURE [PROCEDURE]
ACCESS = {ALL | (access [,access...]) | NONE}
UCLASS = {ALL | (uclass [,uclass...])}
PCLASS = {ALL | (pclass [,pclass...])}


Where:
<ul>
<li><var class="term">access</var> is a particular privilege associated with the procedures in the procedure class. It can be one of the following:
<table>
<tr class="head">
<th>Privilege</th>
<th>Users can...</th>
</tr>

<tr>
<td>USE </td>
<td>Include procedures.</td>
</tr>

<tr>
<td>COPY </td>
<td>Display and edit (copy only) procedures.</td>
</tr>

<tr>
<td>CHANGE </td>
<td>Edit procedures.</td>
</tr>

<tr>
<td>DEFINE </td>
<td>Create new procedures (PROCEDURE and EDIT).</td>
</tr>

<tr>
<td>DELETE </td>
<td>Delete procedures.</td>
</tr>
</table></li>
<li><var class="term">uclass</var> is the user class number whose users have access to the procedures in PCLASS; the number must be in the range 1 to 255. Parentheses are optional in the uclass definition.</li>

<li><var class="term">pclass</var> is the procedure class number to which users in UCLASS have access; the number must be in the range 1 to 255. Parentheses are optional in the pclass definition. </li>
</ul>

====Example====

In the following example, only users in the Payroll Department (user class 90) are allowed to use procedures that manipulate salary fields in a file (procedure class 20 and 30):
SECURE PROC ACCESS = (USE) UCLASS = 90 PCLASS = 20,30


The entries in the ACT do not take effect for users that have the file open when the <var>SECURE</var> command is issued until they reopen the file. This includes the user who issues the command. See [[SECURE PROCEDURE ACCESS command]] for the complete syntax and description of the <var>SECURE</var> command.

To complete procedure security implementation, the system manager updates the password table using the <var>LOGCTL</var> command to assign user classes to the appropriate passwords. 

===Procedure-related commands and required privileges===

The following list is a summary of <var class="product">Model 204</var> procedure or procedure-related commands that require particular privileges. All these commands are described in the <var class="product">Model 204</var> Parameter and Command Reference. 
<table>
<caption>Privileges for procedure or procedure-related commands</caption>
<tr class="head">
<th>Command</th>
<th colspan="2">Required privileges</th>
</tr>

<tr>
<td>INCLUDE</td>
<td>USE</td>
<td> </td>
</tr>

<tr>
<td>EDIT</td>
<td>COPY</td>
<td> </td>
</tr>

<tr>
<td>DISPLAY</td>
<td>COPY (to display text)</td>
<td> </td>
</tr>

<tr>
<td>DELETE</td>
<td>DELETE</td>
<td> </td>
</tr>

<tr>
<td>ASSIGN</td>
<td>CHANGE</td>
<td> </td>
</tr>

<tr>
<td>DEASSIGN</td>
<td>CHANGE</td>
<td> </td>
</tr>

<tr>
<td>RENAME</td>
<td>CHANGE</td>
<td> </td>
</tr>

<tr class="head">
<th>Command</th>
<th>New procedure</th>
<th>Old procedure</th>
</tr>

<tr>
<td>PROCEDURE</td>
<td>DEFINE</td>
<td>CHANGE</td>
</tr>

<tr>
<td>EDIT commands:

GO END</td>
<td>DEFINE, USE* DEFINE</td>
<td>CHANGE, USE* CHANGE</td>
</tr>

<tr>
<td></td>
<td colspan="2">*COPY privileges are required in addition to USE to echo text lines of a procedure to a journal.</td>
</tr>
</table>

===Displaying user and procedure classes===

The SECURE command constructs entries in the access control table for any user classes specified in the UCLASS clause. 
Note: It is important to display procedure security and save it before reorganizing a file, so that you can reestablish the same security. You might have to upgrade your file manager privileges to include COPY, which is not part of the default privileges of a file manager.

To determine a user's access rights for various procedure classes, issue the following form of the DISPLAY command: 

DISPLAY [PROCEDURE (PRIVILEGES [,NOUSE])
[ALL | UCLASS = <var class="term">uclass</var>[,<var class="term">uclass</var>...]]


Where:
<ul>
<li>ALL displays information for all user classes. </li>

<li><var class="term">uclass</var> displays information only for the specified classes.</li>

<li>If neither is specified, your current class and privileges are displayed.

Privileges are displayed in the following format:
UCLASS=<var class="term">u</var> PCLASS=<var class="term">pc</var>,X'<var class="term">nn</var>'
.
.
.
PCLASS=<var class="term">pc</var>,X'<var class="term">nn</var>'


Where:
<ul>
<li><var class="term">u</var> is the user class.</li>

<li><var class="term">pc</var> is a procedure class defined for that user class.</li>

<li><var class="term">nn</var> is a privilege byte constructed from combinations of the following bit settings:
<table>
<tr class="head">
<th> Bit </th>
<th>Privilege</th>
</tr>

<tr>
<td align="right"> X'80' </td>
<td>USE</td>
</tr>

<tr>
<td align="right"> X'40' </td>
<td>COPY</td>
</tr>

<tr>
<td align="right"> X'20' </td>
<td>CHANGE </td>
</tr>

<tr>
<td align="right"> X'10' </td>
<td>DEFINE</td>
</tr>

<tr>
<td align="right"> X'08' </td>
<td>DELETE</td>
</tr>
</table></li>
</ul></li>

<li>If NOUSE is specified, information is displayed at your terminal even if a USE command preceded the DISPLAY command. The device specified by the USE command is not used but is left open.</li>
</ul>

See the discussion of other DISPLAY command capabilities in [[ Field display and message broadcast#Overview|Overview]].

===Sample security scheme===

A simplified example of a security scheme at an installation is presented in this section. At this installation, the following access rules are established:
<ul>
<li>Most users are allowed to include all secured procedures.</li>

<li>Only programmers in the data processing department are allowed to define procedures. However, they cannot use them. These programmers can have user classes 8 or 9.</li>

<li>Only users in the payroll department are allowed to use procedures that manipulate salary fields in the file. Payroll users are assigned class 90, and the payroll procedures are in procedure classes 20 and 30.</li>

<li>Other users are assigned user classes 25, 30, or 31.</li>

<li>Other procedures are in procedure classes 40, 50, 60, or 70. </li>
</ul>

===Sample SECURE commands===

To create the security scheme in this example, issue the following commands:
SECURE PROC ACCESS=(CHANGE,DEFINE,DELETE,COPY) UCLASS=8,9 PCLASS=20,30,40,50,60,70
SECURE PROC ACCESS=(USE) UCLASS=90 PCLASS=20,30
SECURE PROC ACCESS=(USE) UCLASS=25,30,31,90 -
PCLASS=40,50,60,70


====Importance of SECURE command order====

In this example, the order of the SECURE commands is unimportant. However, the order becomes significant when a UCLASS=ALL or PCLASS=ALL clause is included in the command. UCLASS=ALL affects only user classes already mentioned in the ACT. This might be completely different from the list of user classes that actually can be assigned to users from the password table or default file or group settings.

When PCLASS=ALL is included in the command, no new entries are added to the ACT. Instead, for each user class in the UCLASS list, access rights for each procedure class already mentioned for that user are replaced by the new ACCESS rights. Again, the classes affected in the ACT may be completely different from those actually used for secured procedures in the file. 

===Changing and adding access privileges===

Suppose, in this sample security, that the payroll users now need to be able to display all the procedures that they use. Also, suppose that a new set of procedures (of class 15) is developed that all users (including the programmers) can include. The following commands are issued in the order shown to modify the ACT entries already built:
SECURE PROC ACCESS=(USE) UCLASS=ALL PCLASS=15
SECURE PROC ACCESS=(USE,COPY) UCLASS=90 PCLASS=ALL


If these commands are reversed, the payroll users cannot display members of the new class of procedures.

===Removing procedure security for procedures or user classes===

To remove the procedure access defined for user class/procedure class pairs, use the DESECURE command:
<ol>
<li>Remove the security for the procedure involved. </li>
<li>Delete the procedure class number assigned to the procedure in the procedure dictionary by issuing the form of the DESECURE command immediately below. </li>
</ol>
Note:
If you do not do this, no one can access the procedure, even though the entry might have been removed from the ACT (see the second form of DESECURE below). 

Only file managers can issue the DESECURE command and it must be issued in file context (that is, the current default must be a file, not a group). 

The format of the DESECURE command is:

DESECURE PROCEDURE {ALL | NAME=(procname[,procname...])}


Where:

<var class="term">procname</var> is the name of an existing secured procedure.

To remove particular access privileges for particular procedure classes, use the following form of the DESECURE command to delete entries from the ACT. You must specify either UCLASS or PCLASS, or both.

The format is:
DESECURE <var>PROC</var>EDURE
{[UCLASS= {ALL | (uclass[,uclass...])}] |
[PCLASS= {ALL | (pclass[,pclass...])}]}


Where:
<ul>
<li><var class="term">uclass</var> is the number of an existing user class whose users have access to the procedure in <var class="term">pclass</var>; the number must be in the range 1-255. If only UCLASS is specified, all references to the specified user classes are removed from the ACT.

Parentheses are optional with <var class="term">uclass</var>.
</li>

<li><var class="term">pclass</var> is the number of an existing procedure class to which users in <var class="term">uclass</var> have access; the number must be in the range 1-255. If only <var class="term">pclass</var> is specified, all references to the specified procedure classes are removed from the ACT.

Parentheses are optional with <var class="term">pclass</var>. 
</li>
</ul>

===Desecuring both UCLASS and PCLASS===

If both UCLASS and PCLASS are specified, the entries for all combinations of the specified user and procedure class pairs are removed from the ACT. For example:
DESECURE PROC UCLASS=8,9 PCLASS=1,2,3


removes access entries for:
UCLASS 8 and PCLASS 1
UCLASS 8 and PCLASS 2
UCLASS 8 and PCLASS 3
UCLASS 9 and PCLASS 1
UCLASS 9 and PCLASS 2
UCLASS 9 and PCLASS 3


===System manager responsibilities===

The final step in the desecuring process is to have the system manager remove the password(s) with associated uclasses from the password table. If they are not removed, you must remember not to use them when opening the file.

===Privileges required===

You must have file-level privileges of at least X'A000' (file manager and ad hoc data update) to issue SECURE and DESECURE commands. In this case, you actually need update but not retrieve privileges. (Refer to [[#File security|File security]] for a discussion of these privileges.) 

===File and group references===

When an explicit reference is made to a file with an IN clause and that file is opened only as a member of one or more permanent groups, the file-level privileges to be checked must be obtained from the group privileges, as defined for every group of which the file is a member. If any group's privileges allow the access in question, then the operation proceeds.

If the access is to a secured procedure, for every group in which the file is opened and the access is allowed by the group privileges, the user's user class in that group is used to determine privileges for that procedure's class. If any group's user class has the privilege, the operation proceeds.

See the discussion of reference context in the example on [[#Determining user access levels|Determining user access levels]] and see [[Files, groups, and reference context]] for more information. 

==Subsystem security==

When a user enters a subsystem, <var class="product">Model 204</var> opens and determines privileges for all subsystem files and groups for that user. The files that are opened and the privileges that are assigned are based on a combination of the user's subsystem user class and the subsystem's status, both specified by the system manager in the subsystem definition. 

The system manager assigns a user to a subsystem user class by entering the user's <var class="product">Model 204</var> login user ID in the appropriate subsystem user class. Whenever the user invokes the subsystem, the user is assigned the subsystem command privileges and the file and group privileges of that subsystem user class. 

The system manager controls access to the subsystem through the subsystem status: public, semipublic, or private. The status determines which user classes can enter a particular subsystem and whether or not users without a user class assignment are permitted entry. 

For more information about subsystems, see [[System requirements for Application Subsystems]].

==Terminal security==

<var class="product">Model 204</var> terminal security allows access to certain login user IDs, files, or groups to be restricted to users at certain terminals. For example, you might want a particular MEDICAL file to be accessible only through terminals located physically in doctors' offices. 

The terminal security feature allows a list of terminal numbers to be associated with each login, file, or group password. A terminal number is determined during <var class="product">Model 204</var> initialization by the order of the user parameter lines and the way in which they are assigned to specific telecommunications unit numbers in the JCL. 

The batch user (User 0) is considered to be terminal 0 (zero). A user at a particular terminal whose number is n can log in to a specific user ID or open a specific file or group only if the terminal number, n, is in the terminal list associated with the password for that user ID, file, or group. If it is not, <var class="product">Model 204</var> responds as though the user had entered an invalid password.

Terminal security is generally used with only hard-wired terminals, that is, terminals on leased lines. If an installation has dialup terminals, the terminal can be connected to a number of similar telecommunications units and user parameter lines. In this case, although the location of the terminal can be fixed, its terminal number can change every time it is dialed up. 

The entries in the ACT do not take effect for users that have the file open when the SECURE command is issued until they reopen the file. This includes the user who issues the command. The complete syntax and description of the SECURE command is located in the ry time it is dialed up.

By controlling the assignment of terminal numbers to physical terminals, the system manager determines the appropriate terminal security scheme. You provide assistance in limiting file and group access through file passwords and privileges, and group passwords and privileges.

</div> 

[[Category:Model 204 files]]

HLI: Model 204 security

2023-11-17T18:34:42Z

JDamon:

==Overview==

This topic briefly describes Model 204 security for application programmers who are using the Host Language Interface facility. 


For more information about Model 204 security, see the [[Security interfaces overview]]. 

See also:
[[Storing security information (CCASTAT)]]
[[Establishing and maintaining security]]

==Using Model 204 security==

Model 204 provides a variety of security features that prevent unauthorized use of IDs, files, groups, records, and fields. When a particular security feature is operational, the corresponding access restrictions apply. 

===Login security===

Login security requires you to enter a password when logging in. Only a valid password can gain access to the system. After successfully logging in, you are granted particular privileges. 

When login security is in effect, specify login information using the following HLI calls:
<ul>
<li>
For an IFSTRT thread in IFAM1, use the IFLOG call to provide login information, as necessary, where the user authorization is to be validated by a security interface.</li>
<li>
In IFAM2 and IFAM4, specify the login parameter in the IFSTRT call to supply the user ID and password that permit entry to the system. </li>
<li>
For an IFDIAL thread, supply the login information, as necessary, using the IFWRITE call.</li>
</ul>
===Multi-factor authentication - MFA===

Support for Multi-factor authentication (MFA) is provided with no updates or parameter changes required to Model 204. MFA does require that one of the three security interfaces, listed below, be linked into the Model 204 nucleus. Once a userid is provisioned under MFA, the user acquires a token from a client like IBM Security Verify, installed on the user's mobile device. That token is then concatenated, with a password or passphrase, to logon to Model 204. For example: token:password or token:passphrase, where colon (:) is the concatenating character. That string is passed, unmodified, to the security interface for verification.
<ul>
<li>ACF2
<li>RACF
<li>TopSecret
</ul>

===File security===

File security requires you to specify a legal password in the IFOPEN call. After you successfully open the file, Model 204 grants you particular file privileges, a user class number, and field security levels. 

===Group security===

Group security requires you to specify a legal password in the IFOPEN for the file group. 

===Record security===

Record security limits access to records by allowing you to retrieve and update only records that you have stored in the file or that users can share.

===Field-level security===

Field-level security protects fields in a file. Field access levels are assigned when you open a file or group. Specify the security level associated with a field in the IFDFLD call. 

===Terminal security===
Terminal security allows particular login user IDs and particular files and file groups to be accessed only from specific Model 204 threads.

==See also==
{{Template: HLI programming topic list}}

[[Category: Host Language Interface]]

MONITOR command: SERVSIZE, LSERVER and server number

2023-11-16T19:52:56Z

JDamon:

==Summary==
<dl>
<dt>Privileges
<dd>System administrator
<dt>Function
<dd>Displays information regarding servers defined to the Online. <var>TSRVSIZE</var> and <var>SIZREQD</var> are displayed for each server defined, and if the server is currently occupied by a user, standard user information is also provided.
</dl>

'''TSRVSIZE''' - is the total server size defined using <var>[[SERVSIZE_parameter|SERVSIZE]]</var>, <var>[[SERVGSZ_parameter|SERVGSZ]]</var>, and <var>[[SERVNSSZ_parameter|SERVNSSZ]]</var>.
'''SIZREQD''' - is the total server size required using the viewable parameters <var>[[LSERVER_parameter|LSERVER]]</var>, <var>[[LSERVERN_parameter|LSERVERN]]</var>, <var>[[LSERVERG_parameter|LSERVERG]]</var>. Those parameters,
in turn, are determined by the size of each of the server tables - LSTBL, LNTBL, LQTBL, LVTBL, etc. and whether
they area allocated below-the-bar, above-the-bar or in the non-swappable, above-the-bar area.


==Syntax==
MONITOR (s1, s2, s3...) SERV [SL] [CHKP | SUBTRAN] [USERLIST] [ACTIVE|ACTV]


Where: 
<table>
<tr>
<th><var>SERV</var></th>
<td>Display information regarding all servers defined to the Online.</td>
</tr>

<tr>
<th nowrap><var>(s1, s2, s3...) SERV</var></th>
<td>Display information for only the named servers defined to the Online.</td>
</tr>

<tr>
<th><var>SL</var></th>
<td>Display the since-last statistics.</td>
</tr>

<tr>
<th><var>CHKP | SUBTRAN</var></th>
<td>Display information regarding transaction checkpoints (CHKP) or both transaction and sub-transaction checkpoints (SUBTRAN). See [[MONITOR command: Checkpoints-transaction and sub-transaction|MONITOR: Checkpoints-transaction and sub-transaction]] for more details and examples.</td>
</tr>

<tr>
<th><var>USERLIST</var></th>
<td>Display the basic user line for every user who inhibits checkpoints.</td></tr>

<tr>
<th><var>ACTIVE | ACTV</var></th>
<td>Display only the Online servers that have active users.
An active user is one who is executing a command or running a request and that command or request has not yet completed. Such a user is not OFFI (OFF queue, invisible, blocked In) or OFFO (OFF queue, invisible, blocked Out) as shown by <code>[[MONITOR command|MONITOR ACTIVE]]</code>.</td>
</table>

==Usage notes==
The following syntax is supported:
MONITOR SERV
MONITOR SERV SL
MONITOR (s1,s2,s3...)
MONITOR CHKP USERLIST SERV
MONITOR SUBTRAN USERLIST SERV SL


==Example==
Only servers, in order by definition, are reported. If <code>NSERVS=20</code>, only twenty lines of output are produced. If any server is occupied by a user, standard user information is also provided:
USER SVR USERID TSRVSIZE SIZREQD FUNC CNCT CPU SEQIO QUE WT FLGS
1 111000 77400 WTUS
2 222000 117000 WTUS
5 3 CCAD01 128800 28792 EVAL 320 0.308 25 REDY
1 4 CCAD02 777000 97296 DISP 1 0.000 8 BLKI 3 60
5 85000 85000 WTUS
6 6 SUPERKLUGE 666000 117000 25 0.021 3814 RUNG
9 7 CCAB08 777000 747000 EVAL 0 0.202 3 BLKI 24 68
8 8 USER01 840000 47016 EDIT 94 0.003 81 BLKI 3 66


This display shows all servers (<code>NSERVS=8</code>), in order by definition, defined to this Online. Included on each line are the <var>SERVSIZE</var> for each server and the current number of bytes in use (<var>LSERVER</var>). Three servers, 1, 2, and 5, are waiting for user WTUS.

[[Category: System administrator commands]]
[[Category:Commands]]

MONITOR command: SERVSIZE, LSERVER and server number

2023-11-16T00:04:07Z

JDamon:

==Summary==
<dl>
<dt>Privileges
<dd>System administrator
<dt>Function
<dd>Displays information regarding servers defined to the Online. <var>TSRVSIZE</var> and <var>SIZREQD</var> are displayed for each server defined, and if the server is currently occupied by a user, standard user information is also provided.
</dl>

TSRVSIZE - is the total server size defined using <var>[[SERVSIZE_parameter|SERVSIZE]]</var>, <var>[[SERVGSZ_parameter|SERVGSZ]]</var>, and <var>[[SERVNSSZ_parameter|SERVNSSZ]]</var>.
SIZREQD - is the total server size required using the viewable parameters <var>[[LSERVER_parameter|LSERVER]]</var>, <var>[[LSERVERN_parameter|LSERVERN]]</var>, <var>[[LSERVERG_parameter|LSERVERG]]</var>. Those parameters,
in turn, are determined by the size of each of the server tables - LSTBL, LNTBL, LQTBL, LVTBL, etc. and whether
they area allocated below-the-bar, above-the-bar or in the non-swappable, above-the-bar area.


==Syntax==
MONITOR (s1, s2, s3...) SERV [SL] [CHKP | SUBTRAN] [USERLIST] [ACTIVE|ACTV]


Where: 
<table>
<tr>
<th><var>SERV</var></th>
<td>Display information regarding all servers defined to the Online.</td>
</tr>

<tr>
<th nowrap><var>(s1, s2, s3...) SERV</var></th>
<td>Display information for only the named servers defined to the Online.</td>
</tr>

<tr>
<th><var>SL</var></th>
<td>Display the since-last statistics.</td>
</tr>

<tr>
<th><var>CHKP | SUBTRAN</var></th>
<td>Display information regarding transaction checkpoints (CHKP) or both transaction and sub-transaction checkpoints (SUBTRAN). See [[MONITOR command: Checkpoints-transaction and sub-transaction|MONITOR: Checkpoints-transaction and sub-transaction]] for more details and examples.</td>
</tr>

<tr>
<th><var>USERLIST</var></th>
<td>Display the basic user line for every user who inhibits checkpoints.</td></tr>

<tr>
<th><var>ACTIVE | ACTV</var></th>
<td>Display only the Online servers that have active users.
An active user is one who is executing a command or running a request and that command or request has not yet completed. Such a user is not OFFI (OFF queue, invisible, blocked In) or OFFO (OFF queue, invisible, blocked Out) as shown by <code>[[MONITOR command|MONITOR ACTIVE]]</code>.</td>
</table>

==Usage notes==
The following syntax is supported:
MONITOR SERV
MONITOR SERV SL
MONITOR (s1,s2,s3...)
MONITOR CHKP USERLIST SERV
MONITOR SUBTRAN USERLIST SERV SL


==Example==
Only servers, in order by definition, are reported. If <code>NSERVS=20</code>, only twenty lines of output are produced. If any server is occupied by a user, standard user information is also provided:
USER SVR USERID TSRVSIZE SIZREQD FUNC CNCT CPU SEQIO QUE WT FLGS
1 111000 77400 WTUS
2 222000 117000 WTUS
5 3 CCAD01 128800 28792 EVAL 320 0.308 25 REDY
1 4 CCAD02 777000 97296 DISP 1 0.000 8 BLKI 3 60
5 85000 85000 WTUS
6 6 SUPERKLUGE 666000 117000 25 0.021 3814 RUNG
9 7 CCAB08 777000 747000 EVAL 0 0.202 3 BLKI 24 68
8 8 USER01 840000 47016 EDIT 94 0.003 81 BLKI 3 66


This display shows all servers (<code>NSERVS=8</code>), in order by definition, defined to this Online. Included on each line are the <var>SERVSIZE</var> for each server and the current number of bytes in use (<var>LSERVER</var>). Three servers, 1, 2, and 5, are waiting for user WTUS.

[[Category: System administrator commands]]
[[Category:Commands]]