System requirements for Application Subsystems

Overview of CCASYS

CCASYS is a system file used in conjunction with Dictionary/204 and the Subsystem Management facility (SUBSYSMGMT). It contains the procedure names, file names, and parameters that create a subsystem definition. When a subsystem is executed, Model 204 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 CREATE command). The formula for calculating the size of CCASYS is given in the Model 204 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. Model 204 opens CCASYS during initialization when the SYSOPT parameter setting includes the X'01' bit (see 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 Model 204 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 FISTAT 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:

• Set the SYSOPT X'01' bit on in the JCL PARM field to enable CCASYS.

  The SYSOPT X'01' bit automatically increments NFILES, NDCBS, and NDIR to allow use of the subsystems.

  If the SYSOPT parameter is set to an even value, CCASYS is not opened by Model 204 and subsystems are unavailable.

  You must set the SYSOPT X'01' bit on all nodes that the client subsystem accesses. (For Parallel Query Option/204)

• Specify a CCASYS DD statement for running the subsystem.

File security

You can add additional file security to the security provided by user privileges in the CCASYS file by:

• Resetting the OPENCTL parameter
• Entering passwords for the CCASYS file entries in the password table (CCASTAT). See Using CCASTAT.

Maintaining CCASYS

Periodically back up CCASYS. Like other Model 204 files, CCASYS can participate in recovery and transaction back out processing.

As necessary, include 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 Model 204 installation guide for your operating system.

Recovering CCASYS

If CCASYS is used in a run, you can recover it with a RESTART command without resetting the SYSOPT 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 Model 204 files or non-APSY CCATEMP pages. This can reduce disk I/O for both CCATEMP and other Model 204 files. The APSYPAGE 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 APSYPAGE parameter disable the APSYPAGE feature by setting APSYPAGE to 0. Instead of APSYPAGE, use the RESPAGE parameter for storage above the bar.

To activate the APSY Precompiled Procedures in Storage feature in a job, users must set the APSYPAGE parameter in the User 0 CCAIN stream. The APSYPAGE parameter specifies the number of virtual storage pages to allocate.

Note: While APSYPAGE looks very much like TEMPPAGE, the units are somewhat different:

• APSYPAGE refers to 4096-byte virtual storage pages
• TEMPPAGE refers to 6184-byte Model 204 file pages

There are several reasons to use the APSYPAGE parameter instead of, or in addition to, the TEMPPAGE parameter:

• APSYPAGE 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 APSYPAGE to save frequently loaded APSY compilations in real storage.
• 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.
• When APSYPAGE is set, the large Model 204 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.

Storage improvements for APSY subsystem saved precompilation

If not otherwise set, DSPOPT defaults to X'00'. When a saved compilation page is moved to the APSYPAGE 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 TEMPPAGE parameter. This reduces in-memory CCATEMP storage requirements by approximately (N/1.50), where N is the number of 4K-byte pages of APSYPAGE that are used. In memory CCATEMP size is defined by the TEMPPAGE parameter.

Setting the DSPOPT X'80' bit and setting TEMPPAGE greater than zero causes saved compilations to be saved in both CCATEMP and APSYPAGE. 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 APSYPAGE greater than zero causes APSY subsystem precompiled pages to be saved in storage. If TEMPPAGE 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 DSPOPT is set to include the X'80' bit. With both those settings, Model 204 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 MONITOR DATASPACE 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 (DSPOPT 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 NSERVS is set to 40 and APSYPAGE is set to a nonzero value, or CCASERVR is kept in storage with DSPOPT 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 DSPOPT parameter depends on your installation:

• 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 (DSPOPT=X'43').
• If this decision causes a large number of CCATEMP reads because z/OS steals a lot of pages from the cache hyperspace, then use DSPOPT=X'23' (no cache hyperspace).
• If there is an excessive paging, eliminate one or both In Storage features.
• If your installation is z/OS, 64-bit real-storage, do not use any hyperspaces options, but use dataspaces instead.

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:

• Assist in the proper setting of the APSYPAGE and RESLTHR parameters.
• 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.

The APSY load statistics are:

Statistic	Tracks the number of APSY loads...
APSYLD	Including internal CCASYS procedures that are run as part of APSY processing.
APSYLDD	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.
APSYLDT	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.

APSY precompiled procedures in storage above the bar

You can store APSY precompiled procedures above the bar by using the RESPAGE parameter to specify a number of 4K operating system pages. See 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 LGTBL 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 UTABLE command into the LOGIN procedure, if LGTBL is insufficient before entering the subsystem.

Overview of the Subsystem Management facility

The Subsystem Management facility (SUBSYSMGMT) is a full-screen Model 204 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. Model 204 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 Model 204 environment to another.

For more information on subsystems, requirements, and options, refer to:

• Dictionary/204 installation guide and Dictionary/204 operation and file maintenance, which discuss the installation and preparation of CCASYS, D204SYS, and Dictionary files
• SUBSYSTEM, which describes the dictionary entries relating to subsystems
• PQO: Overview of Parallel Query Option/204, which describes a Model 204 distributed processing facility
• Application Subsystem development, which gives detailed instructions for designing, developing, and debugging a subsystem

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 Model 204 through the Model 204 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 PQO, members can be either automatic or manual:

• 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.
• A manual member is a group or file that must be opened explicitly by the OPEN or OPENC command.

Members can also be either mandatory or optional:

• A mandatory member must be open in order to access a subsystem. Mandatory members cannot be manual.
• An optional member is not required for subsystem access (start and login processing can succeed without it).

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 START SUBSYSTEM command or by SUBSYSTEM LOGIN. At the end of START processing, each automatic member is open unless either the START or OPEN failed.

Manual members of APSY subsystems are in the closed state at the completion of START SUBSYSTEM processing and must be explicitly opened by the user. Manual members become open to the subsystem if an OPEN operation succeeds. If OPEN 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.

• 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.
• If a STOP FILE (or STOP GROUP) 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.
• If the member is located on the service subsystem node, the file is closed to the service subsystem when either the STOP is complete or the last user closes the file.

Member availability to subsystem users

When a user enters a subsystem, automatic subsystem members are opened.

If a user LOGIN or OPEN 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 LOGIN or OPEN 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 OPEN 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 CLOSE command.

Enabling a disabled subsystem file

If a file is marked as disabled to the subsystem, you can use the ENABLE SUBSYSTEM FILE 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:

• subsysname is the name of the client subsystem.
• name specifies the file or group that supports subsysname.
• location is the value of the client CCAIN LOCATION parameter (which is also the value of the CLNT field in the LOGWHO command output).

You must specify the location; you cannot include local files in an ENABLE SUBSYSTEM 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 DISABLE SUBSYSTEM command.

To disable a subsystem file, use this command:

DISABLE SUBSYSTEM subsysname [FILE | GROUP] name AT location

Where:

• subsysname is the name of the client subsystem.
• name specifies the file or group that supports subsysname.
• location is the value of the client CCAIN LOCATION parameter (which is also the value of the CLNT field in the LOGWHO command output).

The consequence of disabling a subsystem file depends on whether the file is an optional or mandatory group member:

• If you disable a mandatory file, you effectively disable the subsystem, because users attempting to access the disabled file cannot access the subsystem.
• If you disable an optional file, users can log in to the subsystem, but cannot access the disabled file.

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 subsystem command processing.

Subsystem startup

To start the subsystem, either issue the START command. Or, optionally, the first user starts the subsystem automatically, if the Auto Start option is in effect. During subsystem startup, Model 204 performs the following tasks:

1. Finds the subsystem definition stored in CCASYS.
2. Builds an in-core subsystem definition control block.

   For z/OS operating systems, application subsystem control blocks reside above the 16-megabyte line.

3. Opens all required files and groups.
4. Scans the procedure file for locked members that have precompiled procedure prefixes (see Procedure Specifications screen).
5. 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.

6. Adds the subsystem name to the list of active subsystems, if no error occurs.
7. Performs a user-written initialization procedure (optional).
8. Closes all associated files and groups, unless the Auto Start option is in effect.

Login processing

Each time the subsystem is invoked, Model 204 automatically performs the following steps:

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

2. Logs the user in to Model 204 with the subsystem name as the user, account, and record security ID, if the automatic login option (see Operational Parameters screen) is set in the subsystem definition.

   If the automatic login option is not set, the user's Model 204 ID is retained.

3. Opens required subsystem files and groups with the found privileges.
4. Executes the commands and requests, as specified by the login procedure programmed by the user. The login procedure might consist of:
   • Storing current server table sizes in the global variable table for later reference
   • Issuing UTABLE commands to set compiler table sizes for subsystem use
   • Setting the communications global variable to the name of the procedure that displays the initial menu
5. Begins main processing as long as the login procedure specifies the next procedure to include in the communications global variable.

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, Model 204 checks to see if the procedure has been precompiled:

• If the procedure is not a precompilable procedure, Model 204 includes it for compilation and evaluation. Compilation and evaluation are reported in the audit trail under the CMPL and EVAL since-last statistics.
• If the procedure is a precompilable procedure, Model 204 checks to see if the procedure was previously compiled with the set of privileges defined for the user's subsystem class.
• If the procedure is precompiled for the user's privilege set, Model 204 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.
• If the procedure is not precompiled, Model 204 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.
• If the procedure is already precompiled for some other privilege set, Model 204 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.

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, Model 204 proceeds to disconnect processing.

Warning: Rocket advises that when using an INCLUDE 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 SCLASSes.

Requirements for using temporary groups

If a precompiled procedure includes an OPEN of a temporary group, an attempt to load that procedure fails (with the GRP NOT OPEN 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:

• Any temporary group in this situation must be open at the time of the load.
• Such a temporary group must be a TBO group if the procedure accesses a TBO file for update.

Disconnect processing

Disconnect processing is invoked when one of the following conditions occurs:

• Communications global variable is set to the exit value.
• Error occurs with no subsystem error procedure defined.
• User is restarted by Model 204.
• Logout or disconnect commands are issued from a subsystem procedure.

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

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 Model 204 ID (if previously logged in), and returned to Model 204 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:

• Compilation errors
• Record locking or table-full errors
• Attention interrupts and *CANCEL if no ON ATTENTION unit is specified in the application

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:

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

• No error procedure is specified in the subsystem definition.

Subsystem operating requirements

Meet the following requirements to define and execute a subsystem:

• Install CCASYS, the Model 204 Dictionary, and the subsystem interface SUBSYSMGMT
• Allocate sufficient space for subsystem use in the resource locking table, server tables, CCATEMP, and spare core (SPCORE)

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.

Dictionary/204 files required for subsystem management

File	Description
CCASYS	Subsystem definition
D204SYS	Migrating definitions
DATALINK	Dictionary file
M204PROC	Procedure file
M204TEMP	Internal work file
METADATA	Dictionary file

Resource locking table space

Model 204 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 PROCEDURE, DELETE PROCEDURE, or RENAME PROCEDURE 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:

• Seven additional entries for application subsystem procedures in CCASYS
• One additional entry for each subsystem and permanent group
• One additional entry for each subsystem procedure if LOCK FILE (or GROUP) options are chosen

Minimum server table sizes

Minimum server table lengths, exclusive of any application procedures, for all users invoking subsystems are:

• LGTBL = 288
• LNTBL = 50
• LQTBL = 120
• LSTBL = 250
• LVTBL = 256

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:

• HWM refers to the highwater mark found in the audit trail's since-last compilation statistic for the indicated table.
• ad hoc group FTBL space 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)

• unavailable-file space is the following quantity, not knowable in advance, which you need to estimate (PQO only):

  (4 + (#unavailable group files)) * (#groups with unavailable members)

• XVAR space is required for these SOUL request elements: found sets, lists, and FOR statements with a WHERE clause. The number of bytes per element depends on the file or group context, as follows:

  Transaction context	Bytes required per element
  Single file	8
  Ad hoc or permanent group	8 * (#files in group)
  Temporary group	4 + (8 * (#files in group))

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:

• NRMTFILE and NRMTLOCS are CCAIN parameters that apply to Parallel Query Option/204.
• filemembers are the files that belong to the subsystem.
• SCLASSes is the number of subsystem user privilege classes.
• procedures is the number of precompiled procedures used by the subsystem.
• 40 bytes for each stopped file or group is the number of bytes returned to spare core if the subsystem is stopped or the file or group is started.

Subsystem operating options

Subsystem operating options consist of commands entered on the command line, the AUTOSYS 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.

Summary of subsystem operating options

Option	Method of entry	Purpose
Auto Commit	Operational Parm screen	Controls automatic COMMITs at the END of each procedure
Auto Start	Operational Parm screen	Automatically starts the subsystem when the first user logs in
Automatic Login (Log user in...)	Operational Parm screen	Logs the user in to the subsystem with an account value of the subsystem name
Automatic Logout (Log user out...)	Operational Parm screen	Controls user logout from Model 204
AUTOSYS	CCAIN user line	Invokes the specified subsystem for individual users upon Model 204 login
Commands
DEBUG SUBSYSTEM	Command line	Allows the user issuing the command to change subsystem procedures without stopping and restarting the subsystem
DISABLE SUBSYSTEM FILE	Command line	Makes a file or subsystem temporarily inaccessible
ENABLE SUBSYSTEM FILE	Command line	Makes a file available again after being disabled
START FILE	Command line	Allows a file to be opened and removes the stop flag (if any)
START SUBSYSTEM	Command line	Activates the subsystem, opens files, and performs subsystem startup
STOP FILE	Command line	Prevents opening a specified file or permanent group
STOP SUBSYSTEM	Command line	Stops the subsystem
TEST	Command line	Creates a single user test environment
File/Group	Command line	Specifies the name and attributes of files and groups used by the subsystem
Global variables
Communication	Procedure Spec screen	Specifies the variable name of the next procedure to be executed
Exit Value	Procedure Spec screen	Specifies the communication variable setting for exiting the subsystem
Error Variable	Procedure Spec screen	Names the variable containing the error code
Iterations	Operational Parm screen	Specifies the maximum number of times a procedure can execute consecutively
Lock File/Groups	Operational Parm screen	Controls outside user access to subsystem files when the subsystem is active
Message display
Disconnect	Operational Parm screen	Controls disconnect message display
Informational	Operational Parm screen	Controls the display of informational messages
Error	Operational Parm screen	Controls error message display
Numlk	File Use screen	Specifies the number of files participating in procedure locking
Proc names
Initialization	Procedure Spec screen	Names the first procedure used upon subsystem startup
Login	Procedure Spec screen	Names the first procedure executed for each user
Error	Procedure Spec screen	Names the procedure invoked when an error occurs
Proc prefixes
Non-precompiled	Procedure Spec screen	Identifies the prefix used for procedures compiled each time they are invoked
Precompiled	Procedure Spec screen	Identifies the prefix used for procedures that are saved in CCATEMP for reuse
Procs	File Use screen	Names the file or group containing the subsystem procedures
Security
Account	Operational Parm screen	Specifies an account value that overrides the login account
Account	Subsys Class screen	Specifies an account associated with a specific user class (overrides the account specified on the Operational Parameters screen)
Account	User Matrix screen	Changes an account in any subsystem user class
Command Priv.	Subsys Class screen	Specifies whether the class of users can issue the START, TEST, STOP, and DEBUG subsystem commands
File Priv.	Subsys Class screen	Specifies values for procedure, file, and field-level security parameters
Login Priv.	Subsys Class screen	Overrides privileges on entry to the subsystem and privileges specified on the Operational Parameters screen
Privileges	Operational Parm screen	Specifies user privileges independent of the Model 204 login privileges
Record Security	Subsys Class screen	Overrides the record security ID held upon entry into the subsystem
Start Login	Operational Parm screen	Controls login privileges while starting a subsystem
Status	Operational Parm screen	Specifies the level of availability of the subsystem to users
Sys Class	Subsys Class screen	Specifies the number and name of a subsystem user class that is assigned specific privileges
Subsys Class	Subsys Class Users screen	Specifies subsystem class changes for individual users
Subsys Class	Userdef screen	Identifies a group of subsystem users and specifies the command privilege level applicable to that group

Subsystem commands

The following list summarizes commands relating to a subsystem.

• DEBUG SUBSYSTEM allows login to a specified subsystem with the DEBUG and STATS options of the TEST command. Individual programmer changes to subsystem procedures can be made without stopping and restarting the subsystem. Changes are limited to the programmer issuing the DEBUG SUBSYSTEM command. More than one user can execute the DEBUG command against the same subsystem at the same time.

  DEBUG SUBSYSTEM displays the value of the communications global variable and since-last statistics. Prompts are issued for changes to the variable.

  DEBUG is limited to users with either TEST or DEBUG privileges. The DEBUG privilege does not entitle use of the TEST command.

• DISABLE SUBSYSTEM FILE 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 STOP SUBSYSTEM command.
• ENABLE SUBSYSTEM FILE makes a file marked as disabled to the subsystem available again.
• START FILE removes the OPEN restriction set by the STOP command at the system and subsystem levels.
• START SUBSYSTEM activates the subsystem and makes it available for use. Model 204 opens all the files and performs subsystem startup.
• STOP FILE prevents the reopening of a specified file or permanent group. Files or groups open at the time STOP FILE 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. STOP FILE affects only one copy of Model 204. Another copy of Model 204 can process the file or group.

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

• STOP SUBSYSTEM 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 STOP SUBSYSTEM is issued when there are active users, the system remains active until the last user disconnects (drain state).

• TEST creates a single user test environment. The subsystem must be stopped to enter the TEST mode and the user must have TEST privileges. DEBUG privileges are not sufficient to execute the TEST command.

  TEST without the DEBUG option simulates execution of the subsystem.

AUTOSYS parameter

The AUTOSYS parameter, specified on user lines in CCAIN, invokes a subsystem for individual users upon login to Model 204. The same subsystem is generated for each subsequent user line until a different subsystem name is specified, or AUTOSYS is set to C' '.

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 main menu and from the 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 (===>). 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:

Commands common to SUBSYSMGMT screens

Command	PF key	Purpose
HELP	F1	Displays online Help text for the screen.
QUIT	F3	Terminates processing without saving screen input. QUIT returns to the previous level.
END	F12	Saves input and returns to the previous level.
	F11	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.

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.

SUBSYSMGMT facility screens

Screen	Purpose
Primary screen
Activity	Provides a menu from which to select subsystem definition activities
Secondary screens
Command Privileges	Changes the command privileges for a set of subsystems
Operational Parameters	Defines the subsystem operating parameters
Procedure Specifications	Defines subsystem procedure specifications
Subsystem File Use	Defines file names used by the subsystem
Subsystem Classes	Defines command and file privileges for each class of subsystem user
User Definitions	Defines the users of the subsystem when used in conjunction with the Subsystem Class User screen
Subsystem Class Users	Defines assignments of specific user accounts to specific user classes
User Matrix	Changes the definition of a single account in a user class
Subsystem Administration	Defines user and administrative privileges
Subsystem Trust	(PQO only) Views or manages trusted subsystem definitions

Using secondary screens

The following considerations apply to all secondary screens:

• Use secondary screens in any order.
• Use PF keys to move from screen to screen.
• You must fill in all screens, except those for public and semi-public subsystems with only one class, to complete a subsystem definition.
• Public and semi-public subsystems with only one class do not require the use of the User Definitions (Userdef) screen.
• 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.)

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

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

Overview of activities

The following options are initiated from the Activity screen and completed through the selected secondary screens:

• Add a new subsystem definition
• Modify an existing subsystem definition
• Browse without updating an existing subsystem definition

The following options are initiated and completed from the Activity screen:

• Copy an existing subsystem definition to a newly named subsystem definition
• Rename an existing subsystem with a new, unique name
• Delete an entire existing subsystem definition
• Import subsystem definitions
• Export subsystem definitions
• Export Delete a subsystem from the D204SYS file

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 START, STOP, TEST, DEBUG, RESUME, SUSPEND, REFRESH 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:

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

• If Subsystem Name is left blank, the following error message is displayed:

  SUMnnn: Subsystem name or pattern is required.

SUBSYSMGMT Command Privileges screen

The subsystem management command privileges screen is shown below:

Subsystem COMMAND PRIVILEGES screen

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 (*) 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 Y or N in one or more of the subsystem command privilege fields. In addition, the subsystem class must be selected by putting an X 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 X 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.

PF keys

PF Key	Command	Purpose
1	HELp	Display Help information on this screen
3	QUIt	Exit from Command Privileges Screen, return to main menu for SUBSYSMGMT.
4	LISt	Displays a list of subsystems and classes based on the pattern specification in the Subsystem name and Class fields.
5	DESelect all SELect all	De-select all subsystem names on the list. Select all subsystem names on the list. Toggles between DESelect and SELect.
6	DISplay	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.
7	BACkward	Scroll up on subsystem names list.
8	FORward	Scroll down on subsystem names list.
11	UPDate	Update all subsystem classes with new command privilege. Only the command privileges that are changed are updated.
12	END	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.

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 version of this screen by selecting Manage > Subsystem Management > Operational.

On this screen, only system managers can modify Account, Privileges, and Start Login privileges fields.

Operational Parameters screen

Commands

• 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.
• Pressing the Enter key validates screen input.

A description of each parameter follows.

Parameter descriptions

• Status (1, 2, and 3) determines access availability:
  • PUBLIC (default) allows any user to access the subsystem.
  • 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).

  • PRIVATE requires all users to have an assigned class. No default is allowed.
• Auto Start automatically starts the subsystem when the first user enters the subsystem name. The START command is not required.

  If N (the default) is specified, only a user having the appropriate privileges, as defined on the Subsystem Classes screen, can issue the START command to open the subsystem.

• Lock File/Groups provides control for file access to users outside the subsystem.

  If Y 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 N (default) is specified, users outside the subsystem can open any subsystem file, but cannot DELETE, RENAME, or REDEFINE fields.

• Log user into M204 controls the method of logging the user in to Model 204.

  If Y is specified, the user is logged out of Model 204 and then logged back in to Model 204 with the subsystem name as the user ID when entering the system.

  If N (default) is specified, the user remains logged in under the same Model 204 account name used before subsystem processing.

• Log user out of M204 controls the method of logging the user out of Model 204.

  If Y is specified, the user is logged out of Model 204 upon leaving the subsystem.

  If N (default) is specified and Log user into M204 is Y, the user's logon, account, and record security ID are restored to the values that were present before entering the subsystem.

• Auto Commit controls the issuing of COMMIT statements:
  • If Y (default) is specified, a SOUL COMMIT statement is executed by Model 204 at each procedure END in the subsystem during execution.
  • If N is specified, transactions can span request boundaries (see Transaction boundaries). The application must issue COMMIT statements to commit updates to the database.
• 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. NULL (default) indicates no limit.
• Account (optional) specifies an account value other than that used at logon. As many as 10 characters can be entered. NULL can be used to specify the logon account value.

  The original value is restored when the user exits the subsystem.

• 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 File security.

• 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 File security. NULL indicates that other privilege specifications are not to be overridden.

• Subsystem can access Remote Files pertains to PQO applications. N is the default. Change the value to Y, if you want the subsystem to access remote files.

Message display options

At the bottom of the screen are the message display options:

• Disconnect controls the display of subsystem disconnect messages:
  • If you specify Y (default), the subsystem disconnect message is displayed.
  • If you specify N, the subsystem disconnect message is suppressed.
• Informational controls the display of informational messages:
  • If you specify Y (default), Model 204 informational messages are displayed.
  • If you specify N, Model 204 informational messages are suppressed on the user's terminal and only subsystem messages are displayed. Model 204 messages continue to be printed on the audit trail.
• Error controls the display of error messages on the user's terminal.
• If you specify Y (default), Model 204 error messages are displayed.
• If you specify N, error messages are suppressed, but are still printed on the audit trail.

Procedure Specifications screen

Enter specifications for subsystem procedures on the Procedure Specifications screen. You access the RKWeb version of this screen by selecting Manage > Subsystem Management > Procedure.

Procedure Specifications screen

Commands

• F4, F6, F9, and F11 each validate, save the input, and provide the next secondary screen selection.
• You must use a PF key to quit, save input, or move to a different screen.
• Pressing Enter validates the screen.

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

• Non-precompiled specifies a prefix that identifies procedures that are compiled each time they are invoked.
• 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.

Procedure names

PROCEDURE NAMES require assigned prefixes that indicate if the procedure is or is not precompiled:

• Initialization (optional) is the procedure invoked once when the subsystem is first started.
• Login (required) is the name of the first procedure executed for every user.

  Model 204 automatically includes a subsystem login procedure when a user enters a subsystem. This procedure must issue UTABLE commands to set compiler table sizes.

  Control must be passed to an initial main menu screen if the subsystem is an Online application.

• 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 ON ATTENTION unit is active.

  If no error procedure is supplied, Model 204 disconnects the user from the subsystem when an error occurs.

Global variables

GLOBAL VARIABLES enable you to pass information from one request to another and conditionally include procedures at the Model 204 command level:

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

• 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 XFER. For more details about transferring control, see Transferring control.

  When the application is ready to terminate, a subsystem procedure must set the communications global to the exit value.

• Exit Value (required) specifies the setting of the communications variable for exiting the subsystem.
• 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.

Subsystem File Use screen

The Subsystem File Use screen defines the files, including the procedure file used by the subsystem. You access the RKWeb version of this screen by selecting Manage > Subsystem Management > Files.

Subsystem File Use screen

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:

• 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 CREATE command that defined the group, begins with the leftmost specified member and proceeds to the right.
• 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.
• 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.

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 INCLUDE 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 CREATE command always starts with the leftmost file, TESTPROC, 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, PRODPROC, are locked and cannot be modified while their subsystem is active. But a procedure that is a member of PROD1, for example, can be copied, modified, added to TESTPROC and then included in the subsystem while it is still running.

For more information about the PROCFILE option, see its description in the CREATE TEMP GROUP 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 SIRAPSYF 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:

• Substituting a temporary group for the permanent group defined to the subsystem
• Defining a multiple procedure file to the $LstProc function
• Restrictions on using certain commands with multiple procedure files

Note: Non-system managers can add files to a subsystem if they have been assigned modify privileges (see Administrative Privileges screen).

Commands

• F4, F5, F9, and F11 each validate, save the input, and provide the next secondary screen selection.
• You must use a PF key to quit, save input, or move to a different screen.
• 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.
• Pressing Enter validates the screen.
• You must issue the TOP, BOTTOM, and MAXIMUM commands on the command line. These commands have no corresponding PF keys.
  • TOP scrolls to the first file.
  • BOTTOM and MAXIMUM scroll to the last file.
  • MAXIMUM used with F7 and F8 is equivalent to TOP and BOTTOM, respectively.

File specifications

• 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:

  • TEST or DEBUG privilege is required.
  • 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.
• 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.
• Group Y/N indicates whether or not the data file is a group. The default is N.
• Auto Y/N indicates automatic members (opened automatically at subsystem startup).
• Mandatory Y/N indicates mandatory members (which must be open to access the subsystem).
• 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 N, the value of NUMLK must be NULL. If Group is Y, NUMLK must be given a value.

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

Subsystem Classes screen

Define command and file privileges for each class of subsystem users on the Subsystem Classes screen. You access the RKWeb version of this screen by selecting Manage > Subsystem Management > System Classes.

Each class of user requires a separate screen. User class privileges defined to the subsystem override settings for OPENCTL 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

Commands

• F2, F4, F5, and F9 each validate, save the input, and provide the next secondary screen selection.
• Use a PF key to quit, save input, or move to a different screen.
• F6 displays current PRIVDEF parameter settings and lists options, described in Security specifications, below.
• 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.
• F10 returns to the previous subsystem class. Input is validated and saved before moving to a different class.
• F11 moves to the next subsystem class. Input is validated and saved before moving to a different class.
• Pressing Enter validates the screen.
• You must issue the TOP, BOTTOM, and MAXIMUM commands on the command line. These commands have no corresponding PF keys:
  • TOP scrolls to the first file in this class.
  • BOTTOM scrolls to the last file in this class.
  • MAXIMUM used with F7 or F8 is equivalent to TOP or BOTTOM.

Subsystem name and class

• Subsystem Name specifies the name of the subsystem affected by the definitions entered on the screen.
• 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 DEFAULT, which you can change.

Security specifications

• Command Privileges determines if the user class (SCLASS) can issue the subsystem commands START, TEST, STOP, and DEBUG. The command fields take Y or N, and the default for all fields is N.

  Debug specifies entering the subsystem in DEBUG mode.

• 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 PRIVDEF parameter settings.

  NULL indicates default privileges from the Operational Parameters screen.

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

  NULL indicates the security activated on login.

  The original value of the record security ID is restored when the user exits the subsystem.

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

  NULL indicates the user's login account or the value from the Operational Parameters screen.

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

• Location (PQO only) refers to the node where a file is located.
• Prcldef specifies Model 204 procedure security. Values must be between 0 (default) and 255:
  • 0 specifies no procedure security.
  • 255 specifies the highest security.
• Privdef specifies file privileges. Values are hexadecimal 0 to X'BFFF' (default).
• Sellvl, Readvl, Updtvl, and Addvl specify values for field-level security parameters. Values must be between 0 (default) and 255:
  • 0 specifies all users can access field values.
  • 255 restricts access of field values to users having certain privileges.
• PR specifies the name of the procedure file or group for the subsystem.

User Definitions screen

List user classes on the User Definitions (USErdef) screen for updating or browsing class definitions. You access the RKWeb version of this screen by selecting Manage > Subsystem Management > Operational.

User Definitions screen

Commands

• F2, F4, F5, and F6 display the next secondary screen.
• F7 and F8 allow scrolling backward and forward for listing next or previous subsystem classes.
• Pressing Enter displays the Subsystem Class Users screen for the class selected.
• You must issue the TOP, BOTTOM, and MAXIMUM commands on the command line. These commands have no corresponding PF keys:
  • TOP scrolls to the first class.
  • BOTTOM scrolls to the last class.
  • MAXIMUM used with F7 and F8, is equivalent to TOP and BOTTOM, respectively.

Screen specifications

• Subsystem Name specifies the applicable subsystem.
• Subsystem Classes displays a listing, by class number and name, of the user classes defined on the Subsystem Classes screens.
• ENTER SUBSYSTEM CLASS NUMBER accepts the number of the Subsystem Class whose user list is to be browsed/updated.

Subsystem Class Users screen

Define user accounts assigned to a specific class on the Subsystem Class Users screen. You access the RKWeb version of this screen by selecting Manage > Subsystem Management > Users.

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

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 Model 204 user account identification after the prompt (>).

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:

• 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.
• 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 section, below.
• 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.

• 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.
• Other PF keys function as in other secondary screens.

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

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 Model 204 environment to another via the migration file D204SYS, a Model 204 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 ALL 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. 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 Model 204 Dictionary. To export a subsystem definition:

1. Select option 8 from the Activity screen.
2. Specify the subsystem to be exported.
3. To export SCLASS users, change the default value N to Y on the Export Users line.
4. Press Enter.

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

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:

1. Select option 7 from the primary menu.
2. Specify the subsystem to be imported
3. Press Enter.

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:

1. Select option 9 from the primary menu
2. Specify the subsystem to be deleted from D204SYS
3. Press Enter.

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); 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

Select Usage privileges by entering U on the space provided (U is the default). These privileges correspond exactly to the User Activity privileges in previous releases of Model 204. Selecting U brings up the User Matrix screen described in User Matrix screen.

Select Administrative privileges for a User Account by entering A. The four Admin options are explained in the following section, 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 Model 204 Dictionary subsystem. The privileges granted here supplement but do not override general access privileges granted through DICTADMIN.

Admin options

The Subsystem Administration screen offers four options, described in the following sections.

1. Define Privileges

The Define Privileges option lets the system manager grant administrative privileges to specific users for specific subsystems. Selecting this option brings up the Administrative Privileges screen. To execute Define Privileges, enter 1 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 2 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 3 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 4 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:

• If you leave this field blank, the next screen displays all subsystems.
• If you select a pattern following the 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.

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

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.

PF keys

• F1 (HELp) displays Help text for the screen.
• F2 (TOP) scrolls to the top of the display.
• 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.
• 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.
• F7 (BACkward) scrolls backward through the list of subsystems specified. A maximum of ten subsystems are displayed on the screen at once.
• F8 (FORward) scrolls forward through the list of subsystems specified.
• F12 (END) saves all screen changes and returns the user to the Admin Screen.
• The Enter key has no effect on this screen.

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, or in 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 Subsystem Management Facility screen. The columns are privileges granted, including general system manager privileges. The rows are SUBSYSMGMT functions.

Summary of subsystem privileges

Option	Assigned privilege
	ALL	Modify	Browse	Udef	ADDPRIV member	System manager
Add					X	X
Modify	X	X		X		X
Browse	X	X	X			X
Copy	X				X	X
Rename	X					X
Delete	X					X
Import					X	X
Export	X					X
Export Delete	X					X
Admin						X

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

Commands

• F7 and F8 provide scrolling to and from the first to last Subsystem Class Users screen when more than one screen is required.
• 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.

Specifications

• Subsystem Name specifies the subsystem in which the user account is defined.
• Account Exists In specifies the class in which the account is defined.
• Subsystem Classes commands are entered in a one-character input field that precedes each class displayed:
  • A adds the current account to the class in the subsystem shown.
  • C 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.
  • D 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.

Dynamic APSY support

An application subsystem (APSY) is comprised of Model 204 procedures executed in a logical order. You define the operation of the application using the Model 204 Subsystem Management facility (SUBSYSMGMT). The Model 204 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:

• A subset of application subsystem attributes.
• Precompiled and non-precompiled procedures in files that participate in procedure locking while the subsystem is active.

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:

• If the subsystem is not active, you return to Subsystem Management Facility screen.
• If the subsystem is active, the following Active Subsystem Update screen is displayed:

  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

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.

• To update the active subsystem definition, press F12.
• To keep the active in-core definition unchanged, press F3.

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:

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.

Leaving the active subsystem unchanged

If you press F3 or enter QUIT 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 END 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.

• If the update is successful, you are returned to SUBSYSMGMT main menu screen without any confirmation messages displayed.
• 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

Understanding the Dictionary/204 data definition errors

SUM014 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

SUM015 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:

Operational Parameters you can change

Operational Parameter	Specifies
Log user into M204	The user is logged into Model 204 with the subsystem name as the USERID
Log user out of M204	The user is logged out upon leaving subsystem
Auto Commit	A User Language COMMIT/RELEASE statement is run at the end of each procedure
Maximum Iterations	Maximum number of consecutive times you can invoke the same procedure before the ERROR procedure is invoked
Account	The account value other than the one used at logon
Disconnect	Whether to display a system disconnect message
Informational	Whether to display Model 204 informational messages
Error	Whether to display Model 204 error messages

You can change the following on the Procedure Specifications screen in SUBSYSMGMT:

Procedure	Description
Login	First procedure that is invoked for every user
Error	Procedure that is invoked if an error occurs when a subsystem is running

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 REFRESH SUBSYSPROC 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 REFRESH SUBSYSPROC 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 REFRESH SUBSYSPROC command replaces and refreshes only procedures that participate in procedure locking, based on the NUMLK parameter.

Generating success messages

Successful execution of the REFRESH SUBSYSPROC command generates the following confirmation messages:

M204.2665 procname REFRESHED IN SUBSYSTEM subsystem-name

If a FROM clause is specified, the following message is produced:

M204.2666 procname REPLACED IN FILE filename [IN GROUP groupname]

Generating error messages

The REFRESH SUBSYSPROC command may fail under the following circumstances:

• 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

• 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

• If a procedure is not found in the file named in the FROM 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

• 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

• If another user is processing the procedure, the following message is generated:

  M204.2669: PROCEDURE procname IS IN USE BY SUBSYSTEM subsys-name

Understanding REFRESH SUBSYSPROC command privileges

Privileges to issue the REFRESH SUBSYSPROC command are set on the SUBSYSMGMT Subsystem Classes screen using the Refresh field on the Command Privileges line. The input to this field is either Y or N, where N is the default. To issue the REFRESH SUBSYSPROC command, set the Refresh value to Y.

Subsystem processing

When you refresh an active subsystem procedure, the following occurs:

• Precompiled procedures are recompiled for each SCLASS.
• 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 RFR.

  You must write an error procedure instructing your subsystem how to respond to various errors.

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 SUSPEND SUBSYSTEM 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 SUSPEND SUBSYSTEM command are set in the SUBSYSMGMT "Subsystem Classes" screen:

If you issue a SUSPEND SUBSYSTEM command when...	The subsystem is set to...
No active users are in the application subsystem	Suspended state.
Active users are in the subsystem	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.

Monitoring the subsystem

You can issue a MONITOR SUBSYSTEM 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 STATUS option from the MONITOR SUBSYSTEM command is set to SUSPENDING. When a subsystem is fully suspended with no active users, the STATUS option from the MONITOR SUBSYSTEM command is set to SUSPENDED.

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 SUSPEND SUBSYSTEM command may produce the following messages:

• When a subsystem is successfully suspended, the following message is generated:

  M204.2661 SUBSYSTEM subsys-name SUSPENDED

• When there are still active users in the subsystem, the following message is generated:

  M204.2659 subsys-name SET TO SUSPEND, REMAINING USERS = <n>

• If you issue the SUSPEND SUBSYSTEM command without Subsystem Suspend privileges defined for your SCLASS, the following message is generated:

  M204.0930 REQUIRES SUBSYSTEM COMMAND PRIVILEGE

• The SUSPEND SUBSYSTEM 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

• If the subsystem is in TEST mode, it is locked from other users, so the following message is generated:

  M204.0448 SUBSYSTEM TEST IN PROGRESS, COMMAND REJECTED

• 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

• 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

• If the subsystem requires users to log into Model 204 and you are not logged in, the following message is generated:

  M204.1031 PLEASE LOGIN

• 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

Using the RESUME SUBSYSTEM command

When you have completed refreshing a suspended subsystem, you can reactivate it with a RESUME SUBSYSTEM command.

Privileges to issue the RESUME SUBSYSTEM command are set in the SUBSYSMGMT "Subsystem Classes" screen.

The RESUME SUBSYSTEM command may generate the following messages:

• When a subsystem successfully resumes, the following message is generated:

  M204.2657 SUBSYSTEM subsys-name RESUMED

• If you issue the RESUME SUBSYSTEM command without Subsystem Resume privileges defined for your SCLASS, the following message is generated:

  M204.0930 REQUIRES SUBSYSTEM COMMAND PRIVILEGE

• The RESUME SUBSYSTEM 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

• The RESUME SUBSYSTEM 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

• 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

• 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

• 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

• If the subsystem requires users to be logged in to Model 204 and you are not logged in, the following message is generated:

  M204.1031 PLEASE LOGIN

• 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

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 INCLUDE command to compile and run a SOUL request, the INCLUDE 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 COMMAND is executed.

?&COMMAND

Procedures that include multiple BEGIN/END 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 — CAN, HNG, HRD, or SFT — the error procedure cannot attempt to issue any of the following SOUL statements:

• PRINT
• READ
• READ MENU
• SCREEN
• SKIP
• $$ prompts
• $Read
• Or any other statement that writes to the user's terminal

All other SOUL statements are permitted.