m204wiki - User contributions [en]

DISPLAY DSNAMES command

2026-07-02T21:16:56Z

JDamon: /* Example 2 */

==Summary==
<dl>
<dt>Privileges
<dd>System manager
<dt>Function
<dd>Displays DSNAME, VOLSER, DSORG, RECFM, BLKSIZE, LRECL UNITS (space), PRIMARY (space) for each DDNAME selected.
</dl>

==Syntax==
DISPLAY DSNAMES [pattern] or
D DSN [pattern]


Where
<var class="term">pattern</var> is a simple pattern that limits the number of DDNAMES displayed. A simple pattern is a character string with no wildcard or special characters. Any DDNAME whose first characters match the pattern is displayed.

==Usage notes==
<ul>
<li><var>DISPLAY DSNAMES</var> is available as of version 8.0 of <var class="product">Model 204</var>.
<li><var>DISPLAY DSNAMES</var> is not supported under VSE or CMS.
<li>Space information is displayed only for Model 204 files and only those that are open. The space value displayed is for the entire Model 204 file only. If the file is a multi-dataset file, each dataset is listed but not the space allocated to each dataset - only the space allocated to the entire Model 204 file across all datasets. If the Model 204 file is a single dataset file, then the space listed will be the space allocated to that single dataset but will appear only on the line that represents the entire Model 204 file.
</ul>

==Example 1==
26.182 JUL 01 19.00.34.72 PAGE 20
DISPLAY DSNAMES
JOBNAME=ROCKM80T, STEPNAME=V800TEST

DDNAME DSNAME VOLSER DSORG RECFM BLKSIZE LRECL UNITS PRIMARY
CCAJRNL ROCKET1.V800.CCAJRNL.M204 M2P102 PS U 6749 6749
CHKPOINT ROCKET1.V800.CHKPOINT.M204 M2P100 PS F 6184 6184
CCAPRINT ROCKET1.ROCKM80T.J0353345.D0000103.? PS VBA ? 137
CCAAUDIT ROCKET1.ROCKM80T.J0353345.D0000104.? PS VBA ? 137
CCASNAP ROCKET1.ROCKM80T.J0353345.D0000105.? ? ? ? ?
SYSUDUMP ROCKET1.ROCKM80T.J0353345.D0000106.? ? ? ? ?
SYSMDUMP ROCKET1.CCAMDMP0.M204 M2P103 ? ? ? ?
CCASYS CYL 2
CCASYS ROCKET1.CCASYS.M204 M2P103 PS U 6184 6184
CCAGRP CYL 1
CCAGRP ROCKET1.CCAGRP.M204 M2P102 PS U 6184 6184
DSNLIST BLK 20008
DSNLIST ROCKET1.DSNLIST.M204 M2P103 PS U 6184 6184
DSN1MEG TRK 6500
DSN1MEG ROCKET1.DSN1MEG.M204 M2P104 PS U 6184 6184
DSN1OF3 ROCKET1.DSN1MEG.ONEOF3.M204 M2P104 PS U 6184 6184
DSN2OF3 ROCKET1.DSN1MEG.TWOOF3.M204 M2P104 PS U 6184 6184
DSN3OF3 ROCKET1.DSN1MEG.THREEOF3.M204 M2P104 PS U 6184 6184

==Example 2==
26.182 JUL 01 19.16.58.63 PAGE 31
D DSN CCA
JOBNAME=ROCKM80T, STEPNAME=V800TEST

DDNAME DSNAME VOLSER DSORG RECFM BLKSIZE LRECL UNITS PRIMARY
CCAJRNL ROCKET1.V800.CCAJRNL.M204 M2P102 PS U 6749 6749
CCAPRINT ROCKET1.ROCKM80T.J0353345.D0000103.? PS VBA ? 137
CCAAUDIT ROCKET1.ROCKM80T.J0353345.D0000104.? PS VBA ? 137
CCASNAP ROCKET1.ROCKM80T.J0353345.D0000105.? ? ? ? ?
CCASYS CYL 2
CCASYS ROCKET1.CCASYS.M204 M2P103 PS U 6184 6184
CCAGRP CYL 1
CCAGRP ROCKET1.CCAGRP.M204 M2P102 PS U 6184 6184
CCASTAT ROCKET1.CCASTAT.M204 M2P103 PS U 13030 13030
CCAIN ROCKET1.ROCKM80T.J0353345.D0000102.? ? FB 80 80

[[Category:System manager commands]]

DISPLAY DSNAMES command

2026-07-02T21:14:56Z

JDamon: /* Example 1 */

==Summary==
<dl>
<dt>Privileges
<dd>System manager
<dt>Function
<dd>Displays DSNAME, VOLSER, DSORG, RECFM, BLKSIZE, LRECL UNITS (space), PRIMARY (space) for each DDNAME selected.
</dl>

==Syntax==
DISPLAY DSNAMES [pattern] or
D DSN [pattern]


Where
<var class="term">pattern</var> is a simple pattern that limits the number of DDNAMES displayed. A simple pattern is a character string with no wildcard or special characters. Any DDNAME whose first characters match the pattern is displayed.

==Usage notes==
<ul>
<li><var>DISPLAY DSNAMES</var> is available as of version 8.0 of <var class="product">Model 204</var>.
<li><var>DISPLAY DSNAMES</var> is not supported under VSE or CMS.
<li>Space information is displayed only for Model 204 files and only those that are open. The space value displayed is for the entire Model 204 file only. If the file is a multi-dataset file, each dataset is listed but not the space allocated to each dataset - only the space allocated to the entire Model 204 file across all datasets. If the Model 204 file is a single dataset file, then the space listed will be the space allocated to that single dataset but will appear only on the line that represents the entire Model 204 file.
</ul>

==Example 1==
26.182 JUL 01 19.00.34.72 PAGE 20
DISPLAY DSNAMES
JOBNAME=ROCKM80T, STEPNAME=V800TEST

DDNAME DSNAME VOLSER DSORG RECFM BLKSIZE LRECL UNITS PRIMARY
CCAJRNL ROCKET1.V800.CCAJRNL.M204 M2P102 PS U 6749 6749
CHKPOINT ROCKET1.V800.CHKPOINT.M204 M2P100 PS F 6184 6184
CCAPRINT ROCKET1.ROCKM80T.J0353345.D0000103.? PS VBA ? 137
CCAAUDIT ROCKET1.ROCKM80T.J0353345.D0000104.? PS VBA ? 137
CCASNAP ROCKET1.ROCKM80T.J0353345.D0000105.? ? ? ? ?
SYSUDUMP ROCKET1.ROCKM80T.J0353345.D0000106.? ? ? ? ?
SYSMDUMP ROCKET1.CCAMDMP0.M204 M2P103 ? ? ? ?
CCASYS CYL 2
CCASYS ROCKET1.CCASYS.M204 M2P103 PS U 6184 6184
CCAGRP CYL 1
CCAGRP ROCKET1.CCAGRP.M204 M2P102 PS U 6184 6184
DSNLIST BLK 20008
DSNLIST ROCKET1.DSNLIST.M204 M2P103 PS U 6184 6184
DSN1MEG TRK 6500
DSN1MEG ROCKET1.DSN1MEG.M204 M2P104 PS U 6184 6184
DSN1OF3 ROCKET1.DSN1MEG.ONEOF3.M204 M2P104 PS U 6184 6184
DSN2OF3 ROCKET1.DSN1MEG.TWOOF3.M204 M2P104 PS U 6184 6184
DSN3OF3 ROCKET1.DSN1MEG.THREEOF3.M204 M2P104 PS U 6184 6184

==Example 2==
26.182 JUL 01 19.16.58.63 PAGE 31
D DSN CCA
JOBNAME=PSDAM80T, STEPNAME=V800TEST

DDNAME DSNAME VOLSER DSORG RECFM BLKSIZE LRECL UNITS PRIMARY
CCAJRNL PSDAMON.V800.CCAJRNL.M204 M2P102 PS U 6749 6749
CCAPRINT PSDAMON.PSDAM80T.J0353345.D0000103.? PS VBA ? 137
CCAAUDIT PSDAMON.PSDAM80T.J0353345.D0000104.? PS VBA ? 137
CCASNAP PSDAMON.PSDAM80T.J0353345.D0000105.? ? ? ? ?
CCASYS CYL 2
CCASYS PSDAMON.CCASYS.M204 M2P103 PS U 6184 6184
CCAGRP CYL 1
CCAGRP PSDAMON.CCAGRP.M204 M2P102 PS U 6184 6184
CCASTAT PSDAMON.CCASTAT.M204 M2P103 PS U 13030 13030
CCAIN PSDAMON.PSDAM80T.J0353345.D0000102.? ? FB 80 80

[[Category:System manager commands]]

DISPLAY DSNAMES command

2026-07-01T23:24:08Z

JDamon: /* Syntax */

==Summary==
<dl>
<dt>Privileges
<dd>System manager
<dt>Function
<dd>Displays DSNAME, VOLSER, DSORG, RECFM, BLKSIZE, LRECL UNITS (space), PRIMARY (space) for each DDNAME selected.
</dl>

==Syntax==
DISPLAY DSNAMES [pattern] or
D DSN [pattern]


Where
<var class="term">pattern</var> is a simple pattern that limits the number of DDNAMES displayed. A simple pattern is a character string with no wildcard or special characters. Any DDNAME whose first characters match the pattern is displayed.

==Usage notes==
<ul>
<li><var>DISPLAY DSNAMES</var> is available as of version 8.0 of <var class="product">Model 204</var>.
<li><var>DISPLAY DSNAMES</var> is not supported under VSE or CMS.
<li>Space information is displayed only for Model 204 files and only those that are open. The space value displayed is for the entire Model 204 file only. If the file is a multi-dataset file, each dataset is listed but not the space allocated to each dataset - only the space allocated to the entire Model 204 file across all datasets. If the Model 204 file is a single dataset file, then the space listed will be the space allocated to that single dataset but will appear only on the line that represents the entire Model 204 file.
</ul>

==Example 1==
26.182 JUL 01 19.00.34.72 PAGE 20
DISPLAY DSNAMES
JOBNAME=PSDAM80T, STEPNAME=V800TEST

DDNAME DSNAME VOLSER DSORG RECFM BLKSIZE LRECL UNITS PRIMARY
CCAJRNL PSDAMON.V800.CCAJRNL.M204 M2P102 PS U 6749 6749
CHKPOINT PSDAMON.V800.CHKPOINT.M204 M2P100 PS F 6184 6184
CCAPRINT PSDAMON.PSDAM80T.J0353345.D0000103.? PS VBA ? 137
CCAAUDIT PSDAMON.PSDAM80T.J0353345.D0000104.? PS VBA ? 137
CCASNAP PSDAMON.PSDAM80T.J0353345.D0000105.? ? ? ? ?
SYSUDUMP PSDAMON.PSDAM80T.J0353345.D0000106.? ? ? ? ?
SYSMDUMP PSDAMON.CCAMDMP0.M204 M2P103 ? ? ? ?
CCASYS CYL 2
CCASYS PSDAMON.CCASYS.M204 M2P103 PS U 6184 6184
CCAGRP CYL 1
CCAGRP PSDAMON.CCAGRP.M204 M2P102 PS U 6184 6184
DSNLIST BLK 20008
DSNLIST PSDAMON.DSNLIST.M204 M2P103 PS U 6184 6184
DSN1MEG TRK 6500
DSN1MEG PSDAMON.DSN1MEG.M204 M2P104 PS U 6184 6184
DSN1OF3 PSDAMON.DSN1MEG.ONEOF3.M204 M2P104 PS U 6184 6184
DSN2OF3 PSDAMON.DSN1MEG.TWOOF3.M204 M2P104 PS U 6184 6184
DSN3OF3 PSDAMON.DSN1MEG.THREEOF3.M204 M2P104 PS U 6184 6184

==Example 2==
26.182 JUL 01 19.16.58.63 PAGE 31
D DSN CCA
JOBNAME=PSDAM80T, STEPNAME=V800TEST

DDNAME DSNAME VOLSER DSORG RECFM BLKSIZE LRECL UNITS PRIMARY
CCAJRNL PSDAMON.V800.CCAJRNL.M204 M2P102 PS U 6749 6749
CCAPRINT PSDAMON.PSDAM80T.J0353345.D0000103.? PS VBA ? 137
CCAAUDIT PSDAMON.PSDAM80T.J0353345.D0000104.? PS VBA ? 137
CCASNAP PSDAMON.PSDAM80T.J0353345.D0000105.? ? ? ? ?
CCASYS CYL 2
CCASYS PSDAMON.CCASYS.M204 M2P103 PS U 6184 6184
CCAGRP CYL 1
CCAGRP PSDAMON.CCAGRP.M204 M2P102 PS U 6184 6184
CCASTAT PSDAMON.CCASTAT.M204 M2P103 PS U 13030 13030
CCAIN PSDAMON.PSDAM80T.J0353345.D0000102.? ? FB 80 80

[[Category:System manager commands]]

DISPLAY DSNAMES command

2026-07-01T23:19:52Z

JDamon: /* Usage notes */

==Summary==
<dl>
<dt>Privileges
<dd>System manager
<dt>Function
<dd>Displays DSNAME, VOLSER, DSORG, RECFM, BLKSIZE, LRECL UNITS (space), PRIMARY (space) for each DDNAME selected.
</dl>

==Syntax==
DISPLAY DSNAMES [pattern] or
D DSN [pattern]


Where
<var class="term">pattern</var> is a simple pattern that limits the number of DDNAMES displayed. A simple pattern is
a character string with no wildcard or special characters. Any DDNAME whose first characters match the pattern is displayed.

==Usage notes==
<ul>
<li><var>DISPLAY DSNAMES</var> is available as of version 8.0 of <var class="product">Model 204</var>.
<li><var>DISPLAY DSNAMES</var> is not supported under VSE or CMS.
<li>Space information is displayed only for Model 204 files and only those that are open. The space value displayed is for the entire Model 204 file only. If the file is a multi-dataset file, each dataset is listed but not the space allocated to each dataset - only the space allocated to the entire Model 204 file across all datasets. If the Model 204 file is a single dataset file, then the space listed will be the space allocated to that single dataset but will appear only on the line that represents the entire Model 204 file.
</ul>

==Example 1==
26.182 JUL 01 19.00.34.72 PAGE 20
DISPLAY DSNAMES
JOBNAME=PSDAM80T, STEPNAME=V800TEST

DDNAME DSNAME VOLSER DSORG RECFM BLKSIZE LRECL UNITS PRIMARY
CCAJRNL PSDAMON.V800.CCAJRNL.M204 M2P102 PS U 6749 6749
CHKPOINT PSDAMON.V800.CHKPOINT.M204 M2P100 PS F 6184 6184
CCAPRINT PSDAMON.PSDAM80T.J0353345.D0000103.? PS VBA ? 137
CCAAUDIT PSDAMON.PSDAM80T.J0353345.D0000104.? PS VBA ? 137
CCASNAP PSDAMON.PSDAM80T.J0353345.D0000105.? ? ? ? ?
SYSUDUMP PSDAMON.PSDAM80T.J0353345.D0000106.? ? ? ? ?
SYSMDUMP PSDAMON.CCAMDMP0.M204 M2P103 ? ? ? ?
CCASYS CYL 2
CCASYS PSDAMON.CCASYS.M204 M2P103 PS U 6184 6184
CCAGRP CYL 1
CCAGRP PSDAMON.CCAGRP.M204 M2P102 PS U 6184 6184
DSNLIST BLK 20008
DSNLIST PSDAMON.DSNLIST.M204 M2P103 PS U 6184 6184
DSN1MEG TRK 6500
DSN1MEG PSDAMON.DSN1MEG.M204 M2P104 PS U 6184 6184
DSN1OF3 PSDAMON.DSN1MEG.ONEOF3.M204 M2P104 PS U 6184 6184
DSN2OF3 PSDAMON.DSN1MEG.TWOOF3.M204 M2P104 PS U 6184 6184
DSN3OF3 PSDAMON.DSN1MEG.THREEOF3.M204 M2P104 PS U 6184 6184

==Example 2==
26.182 JUL 01 19.16.58.63 PAGE 31
D DSN CCA
JOBNAME=PSDAM80T, STEPNAME=V800TEST

DDNAME DSNAME VOLSER DSORG RECFM BLKSIZE LRECL UNITS PRIMARY
CCAJRNL PSDAMON.V800.CCAJRNL.M204 M2P102 PS U 6749 6749
CCAPRINT PSDAMON.PSDAM80T.J0353345.D0000103.? PS VBA ? 137
CCAAUDIT PSDAMON.PSDAM80T.J0353345.D0000104.? PS VBA ? 137
CCASNAP PSDAMON.PSDAM80T.J0353345.D0000105.? ? ? ? ?
CCASYS CYL 2
CCASYS PSDAMON.CCASYS.M204 M2P103 PS U 6184 6184
CCAGRP CYL 1
CCAGRP PSDAMON.CCAGRP.M204 M2P102 PS U 6184 6184
CCASTAT PSDAMON.CCASTAT.M204 M2P103 PS U 13030 13030
CCAIN PSDAMON.PSDAM80T.J0353345.D0000102.? ? FB 80 80

[[Category:System manager commands]]

DISPLAY DSNAMES command

2026-07-01T23:18:43Z

JDamon: /* Example 1 */

==Summary==
<dl>
<dt>Privileges
<dd>System manager
<dt>Function
<dd>Displays DSNAME, VOLSER, DSORG, RECFM, BLKSIZE, LRECL UNITS (space), PRIMARY (space) for each DDNAME selected.
</dl>

==Syntax==
DISPLAY DSNAMES [pattern] or
D DSN [pattern]


Where
<var class="term">pattern</var> is a simple pattern that limits the number of DDNAMES displayed. A simple pattern is
a character string with no wildcard or special characters. Any DDNAME whose first characters match the pattern is displayed.

==Usage notes==
<ul>
<li><var>DISPLAY DSNAMES</var> is available as of version 8.0 of <var class="product">Model 204</var>.
<li><var>DISPLAY DSNAMES</var> is not supported under VSE or CMS.
<li>The following is an example of the listing produced by <var>DISPLAY DSNAMES</var>.
<li>Space information is displayed only for Model 204 files and only those that are open. The space value displayed is for the entire Model 204 file only. If the file is a multi-dataset file, each dataset is listed but not the space allocated to each dataset - only the space allocated to the entire Model 204 file across all datasets. If the Model 204 file is a single dataset file, then the space listed will be the space allocated to that single dataset but will appear only on the line that represents the entire Model 204 file.
</ul>

==Example 1==
26.182 JUL 01 19.00.34.72 PAGE 20
DISPLAY DSNAMES
JOBNAME=PSDAM80T, STEPNAME=V800TEST

DDNAME DSNAME VOLSER DSORG RECFM BLKSIZE LRECL UNITS PRIMARY
CCAJRNL PSDAMON.V800.CCAJRNL.M204 M2P102 PS U 6749 6749
CHKPOINT PSDAMON.V800.CHKPOINT.M204 M2P100 PS F 6184 6184
CCAPRINT PSDAMON.PSDAM80T.J0353345.D0000103.? PS VBA ? 137
CCAAUDIT PSDAMON.PSDAM80T.J0353345.D0000104.? PS VBA ? 137
CCASNAP PSDAMON.PSDAM80T.J0353345.D0000105.? ? ? ? ?
SYSUDUMP PSDAMON.PSDAM80T.J0353345.D0000106.? ? ? ? ?
SYSMDUMP PSDAMON.CCAMDMP0.M204 M2P103 ? ? ? ?
CCASYS CYL 2
CCASYS PSDAMON.CCASYS.M204 M2P103 PS U 6184 6184
CCAGRP CYL 1
CCAGRP PSDAMON.CCAGRP.M204 M2P102 PS U 6184 6184
DSNLIST BLK 20008
DSNLIST PSDAMON.DSNLIST.M204 M2P103 PS U 6184 6184
DSN1MEG TRK 6500
DSN1MEG PSDAMON.DSN1MEG.M204 M2P104 PS U 6184 6184
DSN1OF3 PSDAMON.DSN1MEG.ONEOF3.M204 M2P104 PS U 6184 6184
DSN2OF3 PSDAMON.DSN1MEG.TWOOF3.M204 M2P104 PS U 6184 6184
DSN3OF3 PSDAMON.DSN1MEG.THREEOF3.M204 M2P104 PS U 6184 6184

==Example 2==
26.182 JUL 01 19.16.58.63 PAGE 31
D DSN CCA
JOBNAME=PSDAM80T, STEPNAME=V800TEST

DDNAME DSNAME VOLSER DSORG RECFM BLKSIZE LRECL UNITS PRIMARY
CCAJRNL PSDAMON.V800.CCAJRNL.M204 M2P102 PS U 6749 6749
CCAPRINT PSDAMON.PSDAM80T.J0353345.D0000103.? PS VBA ? 137
CCAAUDIT PSDAMON.PSDAM80T.J0353345.D0000104.? PS VBA ? 137
CCASNAP PSDAMON.PSDAM80T.J0353345.D0000105.? ? ? ? ?
CCASYS CYL 2
CCASYS PSDAMON.CCASYS.M204 M2P103 PS U 6184 6184
CCAGRP CYL 1
CCAGRP PSDAMON.CCAGRP.M204 M2P102 PS U 6184 6184
CCASTAT PSDAMON.CCASTAT.M204 M2P103 PS U 13030 13030
CCAIN PSDAMON.PSDAM80T.J0353345.D0000102.? ? FB 80 80

[[Category:System manager commands]]

DISPLAY DSNAMES command

2026-07-01T22:58:35Z

JDamon: /* Usage notes */

DISPLAY DSNAMES command

2026-07-01T22:41:41Z

JDamon: /* Summary */

DISPLAY DSNAMES command

2026-06-15T18:41:35Z

JDamon: /* Usage notes */

==Summary==
<dl>
<dt>Privileges
<dd>System manager
<dt>Function
<dd>Displays DSNAME, VOLSER, DSORG, RECFM, BLKSIZE, LRECL for each DDNAME selected.
</dl>

==Syntax==
DISPLAY DSNAMES [pattern] or
D DSN [pattern]


Where
<var class="term">pattern</var> is a simple pattern that limits the number of DDNAMES displayed. A simple pattern is
a character string with no wildcard or special characters. Any DDNAME whose first characters match the pattern is displayed.

==Usage notes==
<ul>
<li><var>DISPLAY DSNAMES</var> is available as of version 8.0 of <var class="product">Model 204</var>.
<li><var>DISPLAY DSNAMES</var> is not supported under VSE or CMS.
<li>The following is an example of the listing produced by <var>DISPLAY DSNAMES</var>.
</ul>

==Example 1==
<code>DISPLAY DSNAMES CCA</code> displays only those DDNAMES starting with <code>CCA</code>:
JOBNAME=PSDAM80T, STEPNAME=V800TEST

DDNAME DSNAME VOLSER DSORG RECFM BLKSIZE LRECL
CCAJRNL PSDAMON.V800.CCAJRNL.M204 M2P102 PS U 6749 6749
CCAPRINT PSDAMON.PSDAM80T.J0171916.D0000103.? PS VBA ? 137
CCAAUDIT PSDAMON.PSDAM80T.J0171916.D0000104.? PS VBA ? 137
CCASNAP PSDAMON.PSDAM80T.J0171916.D0000105.? ? ? ? ?
CCASYS PSDAMON.CCASYS.M204 M2P103 PS U 6184 6184
CCAGRP PSDAMON.CCAGRP.M204 M2P102 PS U 6184 6184
CCASTAT PSDAMON.CCASTAT.M204 M2P103 PS U 13030 13030
CCAIN PSDAMON.PSDAM80T.J0171916.D0000102.? ? FB 80 80
PSDAM80T>

[[Category:System manager commands]]

DISPLAY DSNAMES command

2026-06-15T18:40:24Z

JDamon: /* Usage notes */

==Summary==
<dl>
<dt>Privileges
<dd>System manager
<dt>Function
<dd>Displays DSNAME, VOLSER, DSORG, RECFM, BLKSIZE, LRECL for each DDNAME selected.
</dl>

==Syntax==
DISPLAY DSNAMES [pattern] or
D DSN [pattern]


Where
<var class="term">pattern</var> is a simple pattern that limits the number of DDNAMES displayed. A simple pattern is
a character string with no wildcard or special characters. Any DDNAME whose first characters match the pattern is displayed.

==Usage notes==
<ul>
<li><var>DISPLAY DSNAMES</var> is available as of version 8.0 of <var class="product">Model 204</var>.
<li><var>DISPLAY DSNAMES</var> is not supported under VSE or CMS.
<li>The following is an example the the listing produced by <var>DISPLAY DSNAMES</var>.
</ul>

==Example 1==
<code>DISPLAY DSNAMES CCA</code> displays only those DDNAMES starting with <code>CCA</code>:
JOBNAME=PSDAM80T, STEPNAME=V800TEST

DDNAME DSNAME VOLSER DSORG RECFM BLKSIZE LRECL
CCAJRNL PSDAMON.V800.CCAJRNL.M204 M2P102 PS U 6749 6749
CCAPRINT PSDAMON.PSDAM80T.J0171916.D0000103.? PS VBA ? 137
CCAAUDIT PSDAMON.PSDAM80T.J0171916.D0000104.? PS VBA ? 137
CCASNAP PSDAMON.PSDAM80T.J0171916.D0000105.? ? ? ? ?
CCASYS PSDAMON.CCASYS.M204 M2P103 PS U 6184 6184
CCAGRP PSDAMON.CCAGRP.M204 M2P102 PS U 6184 6184
CCASTAT PSDAMON.CCASTAT.M204 M2P103 PS U 13030 13030
CCAIN PSDAMON.PSDAM80T.J0171916.D0000102.? ? FB 80 80
PSDAM80T>

[[Category:System manager commands]]

Release notes for Model 204 version 8.0

2026-06-15T18:36:41Z

JDamon: /* New and changed commands */

==Overview==
These release notes contain installation and features information for the Rocket Model 204 version 8.0 release. Before beginning your installation, please read through this information about product installation and changes.

==New in this release==

==Operating system and hardware requirements==

===Operating system requirements===

===Hardware requirements===

===Connect★ compatibility with Model 204===

==SOUL (User Language) enhancements==

==External Call Facility enhancements==

==System enhancements==

==Editor enhancements==

==AUDIT204 enhancements==

==Recovery enhancements==

==Security enhancements==

==Janus product enhancements==

===TLS 1.3 support===
Janus SSL ports now support TLS 1.3 (RFC 8446) for both client and server connections. TLS 1.3 provides improved security and performance over TLS 1.2, including a simplified handshake with fewer round trips, and the removal of legacy features such as renegotiation.

The following TLS 1.3 cipher suites are supported:
<ul>
<li><code>TLS_AES_128_GCM_SHA256</code></li>
<li><code>TLS_AES_256_GCM_SHA384</code></li>
</ul>

Key exchange is performed using X25519 (Curve25519 Elliptic Curve Diffie-Hellman, per RFC 7748). Certificate authentication uses RSA-PSS signatures.

Key derivation uses the HKDF-based key schedule defined in RFC 8446, replacing the PRF-based approach of earlier TLS versions.

TLS 1.3 is enabled by default on ports that allow TLS 1.2. To restrict a port to earlier protocol versions, use the existing <var>SSLVERSION</var> parameter on the <var>[[JANUS DEFINE]]</var> command.

===Imagine Transparency support===
A new facility called [[Imagine Transparency]] is now available to allow files in an <var class="product">Imagine</var> database to be accessed from <var class="product">Model 204</var> as if they were native files.

A new port type, [[JANUS_DEFINE#IMAGINET|IMAGINET]], is now available. It allows <var class="product">Model 204</var> files to be stored on an Imagine server rather than in operating system files. A new parameter is now available on the [[DEFINE DATASET command#IMAGINE|ALLOCATE]] command to indicate that a file is to be accessed via the <var>IMAGINET</var> port rather than from operating system files.

==Debugger enhancements==

==Performance enhancements==

===Hardware-accelerated deflate/inflate compression===
The SOUL compression functions (<var>Deflate</var>, <var>Inflate</var>, <var>Gzip</var>, <var>Gunzip</var>, <var>Zip</var>, and <var>Unzip</var>) now exploit the IBM z15 (and above) DFLTCC (Deflate Conversion Call) hardware instruction when available. This provides significant performance improvement for compression and decompression of longstrings without any application code changes.

Hardware acceleration is used automatically when the processor supports it. On processors without DFLTCC support, the existing software implementation continues to be used transparently.

The DFLTCC instruction handles both the deflate (compress) and inflate (expand) operations natively in hardware, including CRC-32 computation, providing throughput improvements that scale with data size.

==New and changed commands==
<var>[[DISPLAY DSNAMES command]]</var>

==New and changed parameters==

==New and changed statistics==

==Compatibility issues==

==Notes for system manager and installer==

==New products==

==New and changed messages==

[[Category: Release notes]]

DISPLAY DSNAMES

2026-06-15T18:27:11Z

JDamon: JDamon moved page DISPLAY DSNAMES to DISPLAY DSNAMES command: Misspelled title

#REDIRECT [[DISPLAY DSNAMES command]]

DISPLAY DSNAMES command

2026-06-15T18:27:11Z

JDamon: JDamon moved page DISPLAY DSNAMES to DISPLAY DSNAMES command: Misspelled title

==Summary==
<dl>
<dt>Privileges
<dd>System manager
<dt>Function
<dd>Displays DSNAME, VOLSER, DSORG, RECFM, BLKSIZE, LRECL for each DDNAME selected.
</dl>

==Syntax==
DISPLAY DSNAMES [pattern] or
D DSN [pattern]


Where
<var class="term">pattern</var> is a simple pattern that limits the number of DDNAMES displayed. A simple pattern is
a character string with no wildcard or special characters. Any DDNAME whose first characters match the pattern is displayed.

==Usage notes==
<ul>
<li><var>DISPLAY DSNAMES</var> is available as of version 8.0 of <var class="product">Model 204</var>.
<li>The following is an example the the listing produced by <var>DISPLAY DSNAMES</var>.
</ul>

==Example 1==
<code>DISPLAY DSNAMES CCA</code> displays only those DDNAMES starting with <code>CCA</code>:
JOBNAME=PSDAM80T, STEPNAME=V800TEST

DDNAME DSNAME VOLSER DSORG RECFM BLKSIZE LRECL
CCAJRNL PSDAMON.V800.CCAJRNL.M204 M2P102 PS U 6749 6749
CCAPRINT PSDAMON.PSDAM80T.J0171916.D0000103.? PS VBA ? 137
CCAAUDIT PSDAMON.PSDAM80T.J0171916.D0000104.? PS VBA ? 137
CCASNAP PSDAMON.PSDAM80T.J0171916.D0000105.? ? ? ? ?
CCASYS PSDAMON.CCASYS.M204 M2P103 PS U 6184 6184
CCAGRP PSDAMON.CCAGRP.M204 M2P102 PS U 6184 6184
CCASTAT PSDAMON.CCASTAT.M204 M2P103 PS U 13030 13030
CCAIN PSDAMON.PSDAM80T.J0171916.D0000102.? ? FB 80 80
PSDAM80T>

[[Category:System manager commands]]

DISPLAY MODMAP command

2026-06-15T18:18:02Z

JDamon:

==Summary==
<dl>
<dt>Privileges
<dd>System manager
<dt>Function
<dd>Displays the <var class="product">Model 204</var> link map in address order
</dl>

==Syntax==
DISPLAY MODMAP [pattern]
DISPLAY MODMAP UEX

Where
<var class="term">pattern</var> is a simple pattern that limits the number of csects displayed. A simple pattern is
a character string with no wildcard or special characters. Any csect name matching the pattern is displayed.
UEX displays the entry point addresses of all defined user exits.

==Usage notes==
<ul>
<li>The listing produced by <var>DISPLAY MODMAP</var> is identical to that produced in a CCASNAP, except <var>DISPLAY MODMAP</var> shows only one column's worth of csect names.

<li>The <var>DISPLAY MODMAP</var> output column layout is as follows:
address.length name version date-time-of-assembly

<li><var>DISPLAY MODMAP</var> is available as of version 7.5 of <var class="product">Model 204</var>.
<li><var>DISPLAY MODMAP UEX</var> is available as of version 7.7 of <var class="product">Model 204</var>.
</ul>

==Example 1==
<code>DISPLAY MODMAP FUN</code> displays only those csect names starting with <code>FUN</code>:
MODULE LINK MAP BY ADDRESS
------.---- FUNA
------.---- FUNM
------.---- FUNS
------.---- FUNX
------.---- FUNY
------.---- FUNZ
------.---- FUNL
------.---- FUNU1
------.---- FUNU2
------.---- FUNU3
2F34C2A8.0B30 FUNB 7.5.0G 2013-10-07 07:40
2F34CDD8.5C30 FUNC 7.5.0G 2013-10-11 07:48
2F352A08.17D0 FUND 7.5.0G 2013-10-07 07:40
2F3541D8.3C48 FUNE 7.5.0G 2013-10-07 07:40
2F357E20.4F30 FUNF 7.5.0G 2013-10-07 07:40
2F35CD50.04A8 FUNG 7.5.0G 2013-10-07 07:40
2F35D1F8.0208 FUNP 7.5.0G 2013-10-07 07:40
2F35D400.4498 FUNR 7.5.0G 2013-10-07 07:40
2F361898.A010 FUNT 7.5.0G 2013-10-22 14:29
2F36B8A8.05B8 FUNU 7.5.0G 2013-10-07 07:40
2F36BE60.0C70 FUNV 7.5.0G 2013-10-07 07:40
2F36CAD0.1A08 FUNW 7.5.0G 2013-10-07 07:40


==Example 2==
<code>DISPLAY MODMAP UEX</code> displays the entry point addresses of all defined user exits:
USER EXIT MAP
------.---- JANACLFI
------.---- JANACLFO
------.---- CUSTINIT
------.---- CUSTTERM
------.---- CUSTINI0
------.---- CUSTINI1
------.---- CUSTINI2
------.---- CUSTRSTR
------.---- CUSTLOGO
------.---- CUSTOPRC
------.---- UHDRXT
------.---- IEFSD095
------.---- UUPUSRA
------.---- UUPUSRF
------.---- UUPUSRS
------.---- NCRYPXIT
------.---- MERGEJ
------.---- UPLVLUSR
------.---- TLOG
------.---- DDLPRIV
------.---- DMLPRIV
------.---- M204JLOG
------.---- M204CKPX


[[Category:System manager commands]]

DISPLAY DSNAMES command

2026-06-15T18:16:32Z

JDamon: Created page with "==Summary== <dl> <dt>Privileges <dd>System manager <dt>Function <dd>Displays DSNAME, VOLSER, DSORG, RECFM, BLKSIZE, LRECL for each DDNAME selected. </dl> ==Syntax== DISPLAY DSNAMES [pattern] or D DSN [pattern] Where <var class="term">pattern</var> is a simple pattern that limits the number of DDNAMES displayed. A simple pattern is a character string with no wil..."

==Summary==
<dl>
<dt>Privileges
<dd>System manager
<dt>Function
<dd>Displays DSNAME, VOLSER, DSORG, RECFM, BLKSIZE, LRECL for each DDNAME selected.
</dl>

==Syntax==
DISPLAY DSNAMES [pattern] or
D DSN [pattern]


Where
<var class="term">pattern</var> is a simple pattern that limits the number of DDNAMES displayed. A simple pattern is
a character string with no wildcard or special characters. Any DDNAME whose first characters match the pattern is displayed.

==Usage notes==
<ul>
<li><var>DISPLAY DSNAMES</var> is available as of version 8.0 of <var class="product">Model 204</var>.
<li>The following is an example the the listing produced by <var>DISPLAY DSNAMES</var>.
</ul>

==Example 1==
<code>DISPLAY DSNAMES CCA</code> displays only those DDNAMES starting with <code>CCA</code>:
JOBNAME=PSDAM80T, STEPNAME=V800TEST

DDNAME DSNAME VOLSER DSORG RECFM BLKSIZE LRECL
CCAJRNL PSDAMON.V800.CCAJRNL.M204 M2P102 PS U 6749 6749
CCAPRINT PSDAMON.PSDAM80T.J0171916.D0000103.? PS VBA ? 137
CCAAUDIT PSDAMON.PSDAM80T.J0171916.D0000104.? PS VBA ? 137
CCASNAP PSDAMON.PSDAM80T.J0171916.D0000105.? ? ? ? ?
CCASYS PSDAMON.CCASYS.M204 M2P103 PS U 6184 6184
CCAGRP PSDAMON.CCAGRP.M204 M2P102 PS U 6184 6184
CCASTAT PSDAMON.CCASTAT.M204 M2P103 PS U 13030 13030
CCAIN PSDAMON.PSDAM80T.J0171916.D0000102.? ? FB 80 80
PSDAM80T>

[[Category:System manager commands]]

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