PQO: Managing files and groups

Overview

This topic describes how to set up a symbolic file name definition for client users and how to set permission to access a remote file at a server location. These tasks are performed by the file manager.

The topic also includes a description of how to define groups that include remote files and how to stop and start remote files and scattered groups.

For information about working with remote files and scattered groups in application subsystems, see PQO: Scattered APSY subsystems.

Defining file synonyms

Parallel Query Option/204 supports the use of symbolic names for referencing a remote file. To use a symbolic file name, a file synonym definition (DEFINE FILE command) is required.

The DEFINE FILE command maps a file synonym defined by a local user against the actual name of a local or remote file, using the location where the file resides.

Once the DEFINE FILE command has been issued, local users can refer to the file using the synonym name, as described in Using a file synonym.

DEFINE FILE command

The syntax of the DEFINE FILE command is:

Syntax

DEFINE FILE name [LIKE previousname] WITH SCOPE=SYSTEM FILENAME=actualfilename LOCATION={locationname | '='}

where the rules for parameters are as follows:

Parameters

• name is required, and is the symbolic name (file synonym) assigned to the file. The name must be from 1-8 characters in length. If name is already in use as a file synonym for this copy of Model 204, DEFINE FILE name gives name a new definition.
• LIKE is optional and gives the file synonym currently being defined the attributes of the file referred to by previousname, where previousname is a symbolic name that was previously defined.

  If used, LIKE previousname assigns an additional file synonym, and the FILENAME and LOCATION parameters are not required.

• SCOPE=SYSTEM is required and indicates that this definition is available to all users of this copy of Model 204 for the entire length of the run.
• A FILENAME setting is required if LIKE previousname is not specified in the definition. actualfilename is the file's name as specified in a Model 204 CREATE FILE command on the node to which the file belongs.
• LOCATION is required if LIKE previousname is not specified in the definition. locationname refers to the location of the node on which the actual file resides.

  An equal sign (=) between single quotation marks indicates that the location is the client node, meaning that the file is local.

  The location name also might be required to match a value that is specified in the DESTINATION parameter of a local CCAD2C process definition: If the CCAD2C DESTINATION name is specified in processgroup-symbolic name format, locationname must match a specified symbolic name.

  For example, corresponding to a CCAD2C process definition that includes:

  DESTINATION=(PGRP1,BOSTON)

  the system manager defines a synonym for a remote file by specifying the following location name in a file definition:

  LOCATION=BOSTON

  For more information about the DESTINATION parameter, see Client process DESTINATION parameter.

Using the DEFINE FILE command

The DEFINE FILE command requires User 0 or system manager privileges, and can be issued in any of the following ways:

• Inside the CCAIN input file in the User 0 stream of the client copy of Model 204
• At the user terminal, with the necessary privileges
• Inside a SOUL procedure, with the necessary privileges

You can use DEFINE FILE to define multiple synonyms for the same file, and you can reissue DEFINE FILE with the same name in the same Online or batch run. However, you cannot use multiple synonyms for the same file in a group or subsystem definition.

Redefining file synonyms for group members

Since Model 204 maps file synonyms when the first user opens a permanent or temporary group, changes to file synonyms have no effect on permanent groups previously opened in the run or temporary groups previously opened in the session. If you want to redefine a file synonym for a member of an already open group, you must:

1. Issue a new DEFINE FILE command.
2. Close the group.
3. Delete the group.
4. Issue a new CREATE GROUP command.
5. Open the group again.

Creating scattered groups

PQO supports file groups consisting of files residing on different nodes. A group that contains remote files is a scattered group. Model 204 ad hoc, temporary, and permanent groups can be scattered groups. With no additional requirements, ad hoc groups allow remote file synonyms and remote file specifications. With some additional parameter requirements, temporary and permanent groups allow remote file synonyms and remote file specifications.

Availability, a file status that concerns scattered groups, refers to whether a group member can be opened and, if not, whether the group can be opened. See File and group availability.

Scattered group members are optional or mandatory. If a mandatory member is unavailable, the group cannot open. You specify whether members are optional or mandatory in the group definition. See Creating ad hoc scattered groups.

A scattered group is a local entity: You cannot create a group for a remote node, and you cannot refer to a group defined on a remote node. As for all Model 204 groups, you define a scattered group with the CREATE GROUP command or the SOUL IN clause. The authority required to define a scattered group is no different from that required for a nonscattered group.

Note: It is important to remember that before you create any Model 204 permanent group, scattered or not, you must create a CCAGRP file with the CREATEG command, as described in Storing and using file group definitions (CCAGRP).

For more information, see CREATEG command.

CREATE GROUP command

The CREATE GROUP command syntax and scattered group parameter options are described as follows:

Syntax

CREATE [PERM | TEMP] GROUP groupname FROM {filename [(OPTIONAL) | (MANDATORY)]} ,... [PARAMETER parameter[=value] [, parameter[=value]] ...] [PARAMETER parameter[=value] [, parameter[=value]] ...] . . . END

where the rules for parameters are as follows:

Parameters

• If neither PERM nor TEMP is specified, the default TEMP is assumed.
• If you are specifying remote files, filename must include a remote location (AT location) or be a defined file synonym.

  You cannot specify multiple identifiers for the same file: You cannot include two synonyms for the same file, and you cannot include a synonym and a remote file specification for the same file. Duplicate identifiers for a local file are detected when Model 204 tries to open the group. A Model 204 message tells you the name of file duplicates that result from using file synonyms.

• You cannot specify more than 27 remote file members in a group.
• OPTIONAL or MANDATORY indicates whether group operations can proceed in the absence of the member. The default is MANDATORY. Valid abbreviations are OPT and MAND. You cannot specify OPTIONAL for local files.

  If too many optional files are unavailable, group operations cannot proceed. See the MAXFAIL parameter, below.

  You cannot open a group if a mandatory member is unavailable.

• parameter specifies Model 204 group parameters. Any number of PARAMETER clauses can follow, and each can contain as many parameters in any order as can fit on one input line.

  Valid parameters are described in CREATE command: Permanent group and CREATE command: Temporary group. All but PRIVATE, PUBLIC, and SEMIPUB must be followed by a value.

  PARAMETER clause PROCFILE parameter (if present) must refer to a local file. You cannot access or use remotely stored procedures. If the group is scattered, the value of PROCFILE cannot be an asterisk (*).

  PARAMETER clause MAXFAIL parameter specifies the maximum number of optional members that can be unavailable. If more than MAXFAIL files are unavailable, the group fails to open or operations on the group are aborted. The value of MAXFAIL must be one of the following:

  • Integer between one and the number of optional group members.
  • Asterisk (*), which is equivalent to the number of optional members in the group. This setting means that the group can function without any of its optional members. This is the default.

  For ad hoc scattered groups, MAXFAIL is always set to the default.

  The PARAMETER clause BLDGFT parameter is ignored for groups that include remote members.

  The PARAMETER clause UPDTFILE parameter can refer to either local or remote files. If the update file you are naming is a remote file, you can include its remote file specification (AT location).

CREATE GROUP example

The following CREATE GROUP command creates a permanent scattered group with four local members and four remote members. Five members are mandatory, and the MAXFAIL setting (*) is equivalent to MAXFAIL=3 (the group has three optional members). The update file is a remote member.

CREATE PERM GROUP GRP1 - FROM INSURE89, OWNERS AT DALLAS(MAND), AUTOS AT DETROIT, - DETTMP1 AT DETROIT(OPT), DETTMP2 AT DETROIT(OPT), - DALTMP3 AT DALLAS(OPT), CLNTPROC(MAND), INSURE90 PARAMETER PROCFILE=CLNTPROC, UPDTFILE=AUTOS AT DETROIT PARAMETER MAXFAIL=* END

Creating ad hoc scattered groups

You use the following IN clause syntax to create an ad hoc scattered group:

Syntax

IN file [(OPTIONAL | MANDATORY)], {file [(OPTIONAL | MANDATORY)]} ,...

• If you are specifying remote files, file must include a remote location (AT location) or be a defined file synonym.

  You cannot specify multiple identifiers for the same file: You cannot include two synonyms for the same file, and you cannot include a synonym and a remote file specification for the same file.

• You cannot specify more than 27 remote file members in a group.
• OPTIONAL and MANDATORY are the same as in CREATE GROUP command.

Example and discussion of an ad hoc scattered group

In the ad hoc group created in the following example, CLIENTS is a local file, CARS is a remote file synonym, and SALES AT DETROIT is a remote file specification:

IN CLIENTS, CARS, SALES AT DETROIT (OPTIONAL)

If you want to refer to an ad hoc group you created earlier in a request, you must repeat the earlier IN clause. Model 204 considers two ad hoc groups as duplicates if all the following are true:

• Their IN clauses contain the same set of files.
• Their IN clauses list the files in the same order.
• Corresponding files in their IN clauses are both optional or both mandatory.

The following IN clause is issued later in the same request as the previous example. Model 204 considers this ad hoc scattered group a new group, because the SALES file below is mandatory (by default), not optional:

IN CLIENTS, CARS, SALES AT DETROIT

Because this group is not a duplicate, it requires extra server table space and extra network traffic.

File and group availability

Unlike typical Model 204 file groups, scattered groups do not require that all members of the group can be opened (available) at the time the group is opened and for all subsequent operations.

In the CREATE GROUP command, you specify the members, if any, that are optional. With the MAXFAIL parameter of CREATE GROUP command, you specify how many of the optional files in the group can be unavailable before group processing is stopped.

The terms in the following table describe file or group availability with respect to a user. For more information about availability for files and groups that are members of application subsystems, see PQO: Scattered APSY subsystems.

File or group status terms

Term	Description
available	The file is an open member of an open group.
closed	The file or group is not currently open. If a CLOSE command is issued for a disabled file, the file's status is changed to closed to the user.
disabled	If communications with the user's service thread fails, all remote files on that node are disabled for the user. If the MAXFAIL parameter for an open group is exceeded, or if a mandatory member is unavailable, the group becomes disabled for the user.
open	When a remote file is opened in single file or group context, its status is open.
unavailable	If an optional file in an open group fails to open or becomes disabled, the file is unavailable to the group for the user who has the group open. All group context operations behave as if the unavailable member is not a part of the group, with the exception of ON units specifically designed to handle such situations.

Allowing access to remote files

Before users can access a remote file, the file must be defined as a transaction backout (TBO) file, and it might require a new OPENCTL parameter setting.

This section also discusses using the PQOSYS parameter to generate record security keys for remote users.

If the file is a member of a service application subsystem, the server system manager must determine what kind of access to the file to allow. This is discussed in PQO: Scattered APSY subsystems.

Parallel Query Option and Large Object data

The Parallel Query Option does not support access to actual Large Object data: neither BLOBs nor CLOBs. For PRINT ALL INFORMATION statements of a remote record, the Table B portion of the Large Object field is displayed, but not the data itself. In this way, you can identify remote records that have Large Object fields, although you will need to access the file locally to work with the Large Object data.

Defining transaction backout files

PQO allows only transaction backout files to be remotely accessed. Any attempt to open a non-TBO file in remote context fails.

To enable the transaction backout mechanism for a file, turn off bit settings in the file parameters FOPT and FRCVOPT, as described in the wiki topic Transaction back out file parameter settings.

Setting the OPENCTL parameter

For files that are not application subsystem members, PQO file security is the same as Model 204 file security except for remote files that you do not want to protect with a password.

For such files, public or semipublic, you must use a special setting of the OPENCTL parameter. Otherwise, remote public files do not open and remote semipublic files do not open without a correct password.

Normal Model 204 file security settings apply to remote private files. The OPENCTL parameter is part of the file definition statement that specifies a password option at file open time. It is set at the server node initially at file creation. Its settings do not affect application subsystem files.

Use one of the OPENCTL settings in the following table for remote access of non-subsystem public and semipublic files on a server.

OPENCTL settings

Setting	Meaning	Password handling
X'08'	File may be accessed remotely (PQO) without valid password	If the file is public, no password is requested and the file is opened remotely with default privileges. If the file is semipublic, a password is requested. If the password is missing or invalid, the user is granted default file privileges. If the file is semipublic or private and a valid password is presented, the file is opened only if the X'02' bit is on.
X'04'	File can be accessed remotely (PQO) as permanent group member	No effect.
X'02'	File can be accessed remotely (PQO) with a valid password	The user who specifies a valid password for the private or semipublic file is allowed to open the file remotely.

OPENCTL can be reset after file creation.

OPENCTL is ignored when a file defined in an application subsystem is opened within that subsystem. File privileges are specified in the subsystem definition.

The PQO remote access settings (X'08', X'04', X'02') have no effect on files that are only accessed locally.

For more information about the OPENCTL parameter, see OPENCTL parameter or File security levels.

Record security for remote users: the PQOSYS parameter

The CCAIN SYSTEM parameter PQOSYS lets you direct Model 204 to generate a special record security key for remote users.

PQOSYS has two settings:

• X'00' (the default)

  Your system manager is responsible for assigning unique record security IDs to all users and subsystems with remote access to files with record security. If IDs are not unique, record security might fail to distinguish users from different nodes with the same user ID (for example, SMITH from BOSTON might access records stored by SMITH from CHICAGO).

• X'80'

  Model 204 provides a special record security key for remote users.

  The STORE, FIND, and FOR RECORD NUMBER statements use a record security key that is a concatenation of the user's record security ID (either their login user ID or their record security key from a subsystem definition) with a period (.) followed by the value of the CCAIN LOCATION parameter of the user's node.

  Trailing blanks are stripped from both the record security ID and the LOCATION part of the record security key.

  For local users, the record security key is the user's usual record security ID (without any concatenation).

Setting PQOSYS to X'80' requires extra disk space, because the value of each record security key stored by the system includes the period sign and the LOCATION parameter from the remote node. Setting PQOSYS to the default minimizes disk space use.

PQOSYS is set in the User 0 part of the CCAIN stream on the node where the file is located. It cannot be reset after the Model 204 run is initialized.

Explicitly stored record security keys

If you are explicitly storing an occurrence of the record security field (with SOUL, HLI, or a File Load program) for a user who accesses the file remotely, you need to append a period and the value of the LOCATION parameter of the other user's node to the usual record security ID (the user's login user ID or the record security key of the user's application subsystem).

Record security fields with the BINARY or FLOAT attribute

If the record security field is BINARY or FLOAT and PQOSYS is X'80', Model 204 stores as character strings the record security values stored by remote users. If the file is also a NUMERIC VALIDATION file, remote users cannot store records in this file and only those remote users who are allowed to override record security can retrieve records from the file.

Record security keys stored by local users are stored in the BINARY or FLOAT form.

Stopping and starting a remote file or scattered group

You can stop (prevent new opens of) a remote file by issuing the STOP FILE command using the AT location clause or a file synonym. You can stop a permanent scattered group with STOP GROUP.

A stopped file or group cannot be opened until it is restarted.

In remote as in nonremote contexts, a user can continue to reference a file or group that was already open when a STOP FILE or STOP GROUP command is issued.

This section describes the effect of STOP and START commands in remote contexts.

• For complete information about STOP and START commands, see STOP command: Making a file or group unavailable and START command: Making a file or group available.
• For information about STOP SUBSYSTEM and START SUBSYSTEM, see PQO: Scattered APSY subsystems.

Using STOP FILE on a server node

If a STOP FILE command issued on the server refers to a local file that was opened remotely by a client, the file is stopped to all server and client users until started. However, if the file is a mandatory member of an active subsystem (service or nonservice), or a mandatory member of a group that is a mandatory member of an active subsystem, the STOP command fails.

Model 204 frees all precompiled requests and any saved compilations for the file that are on the local node or on the client node after all current users have closed the file. If the file is being used by an active subsystem, it is marked unavailable for future use.

Using STOP FILE on a client node

If STOP FILE issued on the client refers to a remote file, the file is stopped for users on the client node only. However, if the file is a mandatory member of an active subsystem or a mandatory member of a group that is a mandatory member of an active subsystem, the STOP command fails.

If a stopped file was used by a client subsystem that locks its files, STOP unlocks the file, and it can be opened by any user of this client Online after it is started.

Model 204 does not free any compilations on the client or server nodes nor any precompiled requests referring to the stopped file.

If a stopped remote file belongs to a subsystem, the file's file save area is not freed for reuse until after the subsystem is stopped. If the subsystem is not stopped, subsequent starting and opening of the file uses an additional file save area. Be sure to allocate enough file save areas (NRMTFILE is sufficiently large) to avoid being prevented from opening remote files.

Using STOP GROUP

Since a group can be accessed only by local users, a STOP GROUP command can be issued only for a locally defined group, which might be scattered. Also, a STOP GROUP command cannot be used for a temporary scattered (or nonscattered) group.

If a STOP GROUP command is issued for a local scattered group, the group is stopped for all users, and Model 204 frees any compilations on the client or server nodes that refer to the group after all current users have closed the group.

If a scattered group is a member of a subsystem, STOP GROUP does not free the file save areas of remote members of the group.

START FILE and START GROUP

START FILE and START GROUP commands reverse the effects of STOP FILE and STOP GROUP commands, respectively. After a START FILE or START GROUP command is issued, a remote file can be opened.

A START GROUP command cannot be used for a temporary scattered (or nonscattered) group.

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