PQO: Scattered APSY subsystems

Overview

With Parallel Query Option/204, application subsystem definitions and requests can refer to remote files or scattered groups.

This page explains how to manage, run, and maintain client and service subsystems that run under the Application Subsystem Facility (APSY). Emphasis is on features and concepts that are specific to Parallel Query Option/204. Basic knowledge of Model 204 subsystem management is assumed.

Required system parameters

The following parameter settings are required to run APSY subsystems with distributed data:

• The SYSOPT=X'01' bit must be set on all nodes that the client subsystem will access.
• The LGTBL parameter on the service thread should be reset to at least 132 whenever a user is logged into a service subsystem. This parameter is used to set the size of the Global Variable Table (GTBL). GTBL contains name/value strings for global variables and is used by procedures included by APSY to support subsystem processing.

Client and service subsystems

PQO provides access to remote files under APSY by allowing the system manager to define client and service subsystems:

• Client subsystem is the subsystem a user is running in when requesting access to remote data.
• Service subsystem is the subsystem on a server node that a client user's service thread is logged in to.

A service subsystem definition is stored in the CCASYS file on each node that the client subsystem accesses. The name of a subsystem must be the same at each node. The location of the client node is included in the subsystem name to uniquely identify it to the server node.

Node availability

A server node can be available or unavailable to a client APSY subsystem.

An APSY node is available if the service subsystem has been successfully started. If the service subsystem has not been started, it does not have a subsystem definition structure accessible to the client and is, therefore, unavailable.

A node can be marked unavailable during start processing only if there are mandatory members on a server node and the service subsystem cannot be started. If this happens, start processing also fails on the client node.

Client subsystems attempting to access service subsystems that are not started receive an error message from the server node.

A previously available node can become unavailable when:

• Resumption of communication fails after recovering from a system failure
• User attempts to log in to the service subsystem by logging in to the client subsystem, the service subsystem definition is not found, and at least one mandatory member resides on that node
• User attempts to open a file on a node where the user was not previously logged in

The user is automatically logged in to all associated service subsystems when entering a subsystem that contains remote files. If the service subsystem is unavailable on a node, the user cannot be logged in.

For details on operational parameters that affect logon processing, see Operational Parameters screen (service definition).

File and group availability

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.

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 or OPENC operation succeeds. If OPEN or OPENC 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
• location is the value of the client CCAIN LOCATION parameter (which is also the value of the CLNT field in the LOGWHO command output)

Note: 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 STOP 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
• 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.

Trust

As an alternative to the privilege settings normally available through the Subsystem Management facility, each service subsystem manager can control access by specifying that the client subsystem is trusted. If a client subsystem is trusted, its definition is unmodified and used as is at the service node (with possible maximum values specified for file privileges and field security).

Why use a trust definition?

Using full or partial trust relieves the system administrator from having to create and maintain the file and SCLASS definitions for remote subsystems. (Full or partial trust requires entries on just one screen, rather than the five screens needed for a subsystem service definition.)

Trust information resides on the service node and is controlled by the service subsystem manager or administrator. For example, the administrator of a service node in Chicago creates and manages trust definitions for any client nodes linked to the Chicago service node.

Parallel Query Option/204 offers four levels of trust, as described in the following table.

Parallel Query Option/204 trust levels

Level	Meaning
Full trust	Only the subsystem name, location, and status (active or suspended) appear on the service node's definition, which you create on the Subsystem Trust screen.
Partial trust	Along with the subsystem name, location, and status, you can specify maximum privileges. The client subsystem is trusted, but the maximum file privileges and field level security levels specified on the Subsystem Trust screen cannot be exceeded: If a user requests file privileges that would exceed the maximum, the attempt to open the file fails. If a user requests a field level access that would exceed the maximum, PQO automatically resets the request to the allowed level (the maximum), and opens the file.
Restricted trust	For a subsystem with restricted trust, the subsystem service definition is based on entries you make on these five screens: Subsystem Activity Subsystem File Use Operational Parameters Subsystem Classes Subsystem Class Users The client subsystem's access is determined by the SCLASS, user, and file privileges that you specify on these screens. For a subsystem that has restricted trust, you do not make any entries on the Subsystem Trust screen. You can specify full or partial trust, or specify restricted trust.
No trust	On the service node, if there is neither a subsystem service definition nor a trust definition for the client subsystem. The client subsystem cannot access any files on the service node as subsystem files. However, the files on the service node can be accessed from within a client subsystem as individual, nonsubsystem files, if the following criteria are met: PQO is installed at both sites, and there are link, processgroup, and process definitions connecting the client node to the service node. Horizon Interface is installed at both sites, and there are link, processgroup, and process definitions connecting the client node to the service node. OPENCTL parameter setting allows remote access for any given file (with a setting of `08,' `04,' or `02'). For information about the OPENCTL parameter, see Allowing access to remote files and OPENCTL parameter.

In the "Subsystems and trust level" figure below, Subsystem D has no trust, because neither an active trust definition nor a subsystem service definition for it exist on the service node.

Where to create definitions

To create a definition that has...	Make entries on...
Full trust or Partial trust	Subsystem Trust screen
Restricted trust	Subsystem Activity screen Subsystem File Use screen Operational Parameters screen Subsystem Classes screen Subsystem Class Users screen

For details on adding, modifying, suspending, and deleting trust definitions, see Managing the trust definition.

Store trust definitions associated with remote users in the CCASYS file.

Subsystems and trust level

Subsystem command processing

This section describes aspects of START and STOP SUBSYSTEM processing that are unique to distributed applications.

The TEST SUBSYSTEM command works the same way with distributed and nondistributed applications.

START SUBSYSTEM command processing

When a subsystem defined to support remote access is started, a service subsystem of the same name is started when the first file on the node is opened during automatic open processing. With the START request, each server node receives all necessary subsystem definition information, such as a location ID to uniquely identify it within the network.

If all remote file references on the client node are to manual members, the service subsystem is not started until the first manual member is opened. If any remote files need to be opened automatically on the server node, then the following message is written to the server node audit trail for each service subsystem that is successfully started:

M204.2330: SUBSYSTEM subsysname FROM location STARTED

CREATE GROUP command must precede the START command

If a CREATE GROUP command is required for an automatic and mandatory group, the command must be issued before starting the subsystem. This is necessary so that all remote nodes containing group members can be included in START processing. Group definitions must be local, but files in a group can be remote.

File privileges

User file privileges for remote files are partially determined by the SCLASSes and PRIVDEF settings defined on the server node. Privileges defined on the server node serve as the maximum privileges a client user can request. This mechanism gives the service subsystem administrator control over maximum privileges to ensure file security. If a client user requests more than the maximum privileges defined on the server node, then the file open fails.

Procedure dictionary allocation

During START processing, an in-core procedure dictionary is allocated and built on the client and on each server node. The size of the client procedure dictionary is used for all server node dictionaries. There is no procedure file on the remote node, but the procedure dictionary is allocated anyway to keep track of saved compilations.

File and group definitions

File synonyms, including those used indirectly through a group, and permanent group definitions are locked in share mode once a subsystem is started. This prevents the definitions from changing after a subsystem has been successfully started at a remote node. If such a change is needed, the subsystem must be stopped and restarted so that all the internal structures can be rebuilt and retransmitted.

Automatic and optional members

During START processing, APSY tries to open subsystem automatic members. If an automatic mandatory member cannot be opened, START processing is terminated. If an automatic optional member cannot be opened, the member is marked as disabled and START processing continues.

STOP SUBSYSTEM command processing

The STOP SUBSYSTEM command stops both client and service subsystems.

When a STOP command specifies a subsystem that uses remote files, the following actions are taken:

• Subsystem definition on the client node is examined to determine whether the user has STOP command privileges.
• If the user does not already have a conversation, a conversation is established with each remote node on which the subsystem has been started.
• If there are no remaining users in the subsystem, the service subsystems are stopped.
• If there are remaining users in the subsystem, the service subsystems are placed in a drain state and the usual message is produced on the client node.
• If there is a communication failure with any node accessed by the client subsystem, the client subsystem is stopped or placed in a drain state. The following error message is produced for each failure:

  M204.nnnn: SUBSYSTEM subsysname COULD NOT BE STOPPED AT location

• If the subsystem is not active on any of the nodes accessed by the client subsystem, the following error message is produced for each node:

  M204.nnnn: SUBSYSTEM subsysname NOT ACTIVE AT location

• If the service subsystem is placed in a drain state, then it is stopped when the last user leaves the client subsystem. This happens either through normal exit conditions or through thread timeouts, which can occur depending on the setting of the TIMEOUT parameter.

STOP SUBSYSTEM stops or places in a drain state the local subsystem and all service subsystems with the same name on their nodes.

The following syntax is available for stopping only the service subsystems associated with a specific client node(s):

STOP SUBSYSTEM subsysname FROM location

where:

• subsysname is the name of the subsystem being stopped.
• location is the value of the CCAIN LOCATION parameter of the client node that activated the subsystem (which is also the value of the CLNT in the LOGWHO command output), or is the symbolic name specified by the process definition.

Stopping a subsystem from a remote node where a mandatory file resides causes the node to become disabled to the subsystem.

When client users try to log in to the service subsystem after it has been stopped, a remote START SUBSYSTEM call is sent if there are no mandatory members on the node. If there are mandatory members, the user is not allowed to enter the subsystem on the client until it is stopped and restarted on the client.

Stopping a subsystem from a remote node requires system manager privileges.

Compiling and running procedures

When a non-precompiled procedure that references remote files is invoked, one or more remote nodes participate in the compilation and evaluation. When a precompiled procedure is invoked, Model 204 loads the procedure on each of the nodes that participated in the original compilation.

When a subsystem member becomes unavailable during evaluation, the appropriate ON unit is activated.

Error messages associated with remote procedure processing while loading a request have the prefix RMT in the global error variable.

Saving compilations

As part of the compilation process, a list of remote nodes referenced in the request is generated with the compiled code. When compilation is complete, the compilation is saved along with the list of nodes. Each remote node referenced in the request is sent a signal to save the compilation.

If for any reason a compilation cannot be saved by a server node, the entire save operation fails.

Loading saved compilations

At the client node, the saved remote node reference list is checked to see which nodes are to load the request. When the request is loaded on the client, a signal is transmitted to each referenced server node to load the compilation.

New and missing nodes

A temporary group can be changed so that a node is new (not previously referenced) or missing (referenced but no longer available). The following table shows how new and missing nodes affect recompilations and saves.

Temporary groups with new and missing nodes

	And there are missing nodes...	And there are no missing nodes....
If there are new nodes...	Recompile the procedure, do not save	Recompile and save again
If there are no new nodes...	Just load and evaluate	Just load and evaluate

Recompiling saved requests

Saved requests are always recompiled if a new node is introduced into a temporary group. Recompilation can cause a noticeable delay in response time.

In addition, the following changes in the composition of a subgroup also force recompilation of a request. A subgroup is the group of files at a server node referenced as a part of a group.

Recompilation is required when:

• number of files in the subgroup has increased (for example, if a user's request includes a file that was unavailable to the previous user)
• maximum number of segments in a subgroup has increased

The need to recompile a request is decided automatically.

SUBSYSMGMT overview

This section shows how to define server and client subsystems using the SUBSYSMGMT interface. The screen examples show definitions for a subsystem called SALES. The client system is in Boston and it accesses remote files in Dallas.

The following changes to the SUBSYSMGMT interface are specific to PQO application subsystems:

• To add, modify, suspend, or delete trust definitions, use the Subsystem Trust screen, available from the Subsystem Management Menu screen.
• Several screens have From fields denoting location of client subsystems. You enter a From value on the Activity screen when defining a service subsystem; the From field is then prefilled on secondary screens.
• There are Location fields on the File Use and Subsystem Classes screens. You enter them to indicate the location of remote files to be used by the client subsystem.
• Fields on the File Use screen indicate automatic and mandatory subsystem members.
• Operational Parameters screen has a field indicating whether a client subsystem can access remote files.

The section Parameters and login/logout processing explains the effect of various parameters on login and logout processing in a distributed environment.

For complete information on SUBSYSMGMT, see Overview of the SUBSYSMGMT interface

Defining a service subsystem

Subsystem Trust screen

Subsystem Trust screen

Use the Subsystem Trust screen to view or manage trusted subsystem definitions. The Status field tells you the definition status:

• A= Active
• S= Suspended

Managing the trust definition

To manage trust definitions, you must have system manager privileges at the service node.

Adding a trust definition

1. Enter A, for Add, in the ACT column. The line you choose might be blank or it might already contain information for another definition.
2. Specify the subsystem name and location.
• If you are assigning full trust, stop here.
• If you are assigning partial trust, continue to step 3.
3. If necessary, specify maximum file privileges. For information about valid PRIVDEF settings, see Establishing and maintaining security.
4. If necessary, specify maximum access levels. If you enter an access level value, you must enter information in each of the access level fields.
5. When you are finished entering trust definitions, press Enter or scroll in either direction to update the file, and then use the END function (PF12 key) to return to the Subsystem Management Facility screen.

Modifying a trust definition

You can modify:

• Status, active or suspended
• File privileges
• Access levels

If you change the status of a trust definition to suspended, you temporarily remove trust for the subsystem. The CCASYS trust definition is marked as unavailable, and is not deleted from the CCASYS file.

You cannot modify the name or location of an existing definition; you must delete the old definition and add a new one with the correct name and location for the subsystem:

1. Find the definition to be modified. If necessary, use the PF7 and PF8 keys to scroll through the list.
2. Enter M, for Modify, in the ACT column.
3. Modify status, file privileges, and/or access levels.
4. When you are finished modifying trust definitions, press Enter to save your work and then use the END function (PF12 key).

Deleting a trust definition

1. Find the definition to be deleted.
2. Enter D, for Delete, in the ACT column. Be sure to save your work before exiting the screen with the END function (PF12 key).

The trust definition is deleted from the CCASYS file, for the subsystem name and location specified. Because the trust definition is used only at subsystem start, deletion does not affect a subsystem that is already started.

Handling errors

If PQO encounters an error, it displays a message and positions the cursor at the line causing the error. All changes to lines preceding the one in error are automatically saved and processed.

Subsystem Activity screen (service definition)

Subsystem Activity screen

The Subsystem Activity screen is the primary SUBSYSMGMT screen, used to access all SUBSYSMGMT functions.

The From fields specify the location of the client subsystem. If a From field is specified, the Subsystem Name field might not be blank.

If you are going to the Subsystem Trust screen, the From and Subsystem Name values are used to determine the starting position in the scrollable list of trusted subsystems, which are listed in order by name and location.

The From field is prefilled on all the secondary screens and protected from input.

To define the service subsystem:

1. Select Add on the Main Menu, specifying the subsystem name and the From location.
2. Select the FILeuse, OPEration, SYSclass, and USErdef functions and fill in the appropriate fields as shown in the following sections.

Subsystem File Use screen (service definition)

Subsystem File Use screen

The only definitions allowed when defining a service subsystem are file name, deferred name, and ordered index name. All other fields are defined in the client subsystem and protected from input when you are entering service definitions.

Operational Parameters screen (service definition)

Operational Parameters screen

Selecting PF4 on the Activity screen brings up the Operational Parameters screen. Use it to specify the operating parameters of the subsystem.

The From field specifies the location of the client node that the definition is being created for. It is prefilled with the From value on the Main Menu and protected from input.

Only the Status, Lock File/Groups, Account, Privileges, and Start Login privileges fields can be modified for the service subsystem. All options that are not allowed for service subsystem definitions are protected from screen input. These fields are defined in the client subsystem.

Message Display is not modifiable on the server node, because messages are not displayed on the service thread.

Subsystem Classes screen (service definition)

Subsystem Classes screen

Command and file privileges are defined for each class of subsystem users on the Subsystem Classes screen. 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.

The Location field is protected from input because there is no remote access on the server node. The files shown here, CLIENTS and PRODUCTS, are local (they reside on the service node).

Parts of this screen pertaining to procedure files are masked, because PQO does not support remote procedure files.

Subsystem Class Users screen (service definition)

Subsystem Class Users screen

User accounts assigned to a specific class are defined on the Subsystem Class Users screen. 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 (with different privileges) in each subsystem.

Each user must be in the same class in the client and service subsystems. Otherwise the login fails when the service subsystem login call is sent.

Duplicate account entries result in the display of the class in which the original name resides.

The client and server nodes must have separate CCASYS files. Technical Support recommends that CCASYS files not be shared by different Onlines.

If users have different SCLASSes on the client and server nodes, the following error messages are generated:

M204.2314: Error on remote node location name: error text M204.2309: User not defined in SCLASS sclass name

Defining a client subsystem

Subsystem Activity screen (client definition)

Subsystem Activity screen

To define a client subsystem that accesses remote files:

1. Select Add on the Main Menu. Do not specify a From input value for the client.
2. Select the FILeuse, OPEration, SYSclass, and USErdef functions and fill in the appropriate fields as shown in the following sections.

Subsystem File Use screen (client definition)

Subsystem File Use screen

New flags indicate automatic and mandatory members. If the Automatic flag is N, then the Mandatory flag must be N.

The File Location field specifies the location of each file. If this new field is omitted, then the file is assumed to be local. Specify location only for client subsystems.

If you are referring to remote files by means of file synonyms, then it is not necessary to specify remote location.

This example shows the remote files CLIENTS and PRODUCTS at location DALLAS.

Operational Parameters screen (client definition)

Operational Parameters screen

When you are defining a client subsystem, you can modify any of the fields on this screen. For information about parameters, see Operational Parameters screen.

The field Subsystem Can Access Remote Files is new. N is the default. Change the value to Y if you want the subsystem to access remote files.

Parameters and login/logout processing

The following subsystem operational parameters affect the way users can log into and out of a subsystem:

• Automatic start has no bearing on the service subsystem because the service subsystem is started by Model 204 when the client starts.
• Specifying Automatic Login causes the user to be logged out of Model 204 (but not disconnected) and logged back in with a login ID equal to the subsystem name.

  Any remote files that the user had open prior to entering the subsystem are closed and all the user's service threads are logged out. The client subsystem establishes new service threads for the user on the appropriate remote nodes.

  The user's logon privileges, account, and record security key are reset to those specified for the subsystem. The user is then logged in to the service subsystems associated with the client using the new privileges, login ID, account, and record security key.

  When the user leaves an Automatic Login subsystem, all local and remote files are closed and the user's service threads are logged out.

• Specifying Automatic Logout causes the user to be logged out of Model 204 and disconnected if the SYSOPT disconnect bit is on. Service threads are logged out if the corresponding users were in a subsystem that accessed remote files.
• If you specify Automatic Commit, the client node determines that a commit is required due to execution of a SOUL statement, an end of request, or a return to command level.

Locked files

If a remote file is opened by a subsystem that locks its files, the file is locked on the client node (only users of this subsystem can use the file on this node). Users of other nodes can also open and use the file.

If the service subsystem locks its files, the file is locked on the service node (only users of the client subsystem can open and use it through the service subsystem).

If a subsystem locks its files and an optional member of a subsystem group cannot be locked because it is already open outside of the subsystem, the group can still be opened provided that the number of unavailable group members does not exceed the value of the MAXFAIL parameter.

Subsystem Classes screen (client definition)

Subsystem Classes screen

When you define a client subsystem, you can modify any of the fields on this screen. In the client definition, the Location field value refers to the node where a file is located. This example shows CLIENTS and PRODUCTS at location DALLAS.

Subsystem Class Users screen (client definition)

Subsystem Class Users screen

Users who are authorized to access remote files must be included in the same subsystem class definitions for both the client and service subsystems.

The only difference in screen contents on the client side is that the From field is not prefilled.

See also

• PQO: Overview of Parallel Query Option/204
• PQO: Defining a PQO network
• PQO: Managing the PQO network
• PQO: Managing files and groups
• PQO: Remote files and scattered groups
• PQO: Scattered APSY subsystems
• PQO: Three-node network example