Files, groups, and reference context

Overview

A Model 204 file consists of a collection of records and their associated index pointers. See Files for a discussion of the composition of a Model 204 file. A file group is a collection of Model 204 files that Model 204 treats as a logical single file. A group can be permanent, temporary, or ad hoc.

A file or group must be opened before it can be processed by Model 204. Several files or groups can be opened by a terminal user during a single Model 204 session.

You can refer to any open files or groups within a single request and can cross-reference any records contained in these files or groups. (Cross-referencing is discussed in Cross-referencing and also in Cross-referencing.)

The file and group commands discussed in this topic are described in detail in List of Model 204 parameters and List of Model 204 commands.

Parallel Query Option/204

Parallel Query Option/204 (PQO) is a Model 204 distributed processing facility that allows the sharing of data between two or more copies of Model 204.

In addition to the information provided here, Parallel Query Option/204 is described in detail in PQO: Overview of Parallel Query Option/204 and the information it references.

Remote files

Parallel Query Option/204 provides to SOUL applications the potential for accessing data stored in remote files. A single SOUL request can read and/or update multiple remote files.

Scattered groups

Parallel Query Option/204 also supports file groups consisting of files residing on different nodes. A group that contains one or more remote files is a scattered group. 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 SOUL IN clause or the CREATE GROUP command. The authority required to define a scattered group is no different from that required for a non-scattered Model 204 group.

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.

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. 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. These terms are discussed in more detail in PQO: Managing files and groups.

DML limitations

Not all Model 204 commands, statements and retrieval conditions can be used with Parallel Query Option/204. Using Model 204 file and group commands lists the file and group specification commands that you can use with remote files and groups. DML statements in Parallel Query Option/204 contains listings of supported and non-supported SOUL statements and retrieval conditions.

Using Model 204 file and group commands

The following "Commands for files and groups" table lists file and group commands, their corresponding meanings, and what type of user can issue the command. This list comprises the only commands that support remote file specification.

Commands for files and groups

Command	Meaning	Type of user
CLOSE (file or group)	Closes a group.	Any user
CREATE PERM GROUP	Creates a permanent group.	System manager
CREATE TEMP GROUP	Creates a temporary group.	Any user
DEFAULT	Specifies a new default, which can be either a Model 204 file or group	Any user
DEFINE FILE	Creates a file synonym, defined locally, for the actual name of a local or remote file and its location.	System manager or User 0
DELETE PERM GROUP	Deletes a permanent group.	System manager
DELETE TEMP GROUP	Deletes a temporary group.	Any user
DISABLE SUBSYSTEM	Marks a service subsystem file or group as disabled, making it unavailable to users who try to access it through the subsystem.	System manager
DISPLAY (field, group, or record)	Displays information about one or more objects.	Any user
ENABLE SUBSYSTEM	Enables a disabled subsystem remote file or group.	System manager
MONITOR SUBSYSTEM	Displays information about Parallel Query Option/204 service subsystem files and groups.	Any user
OPEN[C] FILE	Opens a file. Multiple files can be open simultaneously during a Model 204 session. OPEN changes the existing default. OPENC does not.	Any user
OPEN[C] GROUP	Opens a group. Multiple groups can be open simultaneously during a Model 204 session. OPEN changes the existing default. OPENC does not.	Any user
START (file or group)	Reverses the effect of the STOP command.	System manager
STATUS	Displays recovery information about remote Model 204 files that were opened during an online run.	Any user
STOP (file or group)	Prevents a remote file or permanent scattered group from being opened. The STOPped file or group cannot be opened until it is STARTed. STOP and START cannot be used with temporary groups.	System manager
VIEW	Displays the current settings of Model 204 parameters.	Any user

Also supported in PQO are the BUMP, LOGWHO, and MONITOR commands, as well as network control and definition commands and subsystem control commands.

The OPEN[C] FILE, OPEN[C] GROUP, CLOSE, DEFAULT, and DELETE GROUP commands are discussed in this page. For more information on the other commands in the "Commands for files and groups" table, see:

• List of Model 204 parameters and List of Model 204 commands
• PQO: Managing files and groups

File groups

This section describes the composition and advantages of using Model 204 file groups, then discusses how you create, access, and manipulate file groups.

Composition of a Model 204 group

A file group is a collection of Model 204 files that Model 204 treats logically as a single file. File groups do not contain data and pointers, but rather a list of files, each of which contains its own data and pointers. When a group is defined, Model 204 creates an entry in an internal table. This entry contains the names of the files that make up the group.

Commands and statements that refer to a group actually cause operations to be performed on each member file. An individual file can be a member of several different groups and a group can contain up to 256 Model 204 files.

File groups are particularly helpful in working with cyclic data and in organizing independent but similar files. File groups also provide an alias facility.

Using a group to work with cyclic data

Suppose that the file group WEEK consists of the files SUNDAY, MONDAY, TUESDAY, WEDNSDAY (maximum eight letters), THURSDAY, FRIDAY, and SATURDAY. While the union of these seven files is available under the name WEEK, each daily file continues to be accessible as an individual file. The data is not duplicated; an internal table relates WEEK to its member files. WEEK can be defined to include member files that do not yet exist, but it cannot be opened until all member files have been created.

Suppose you want the group WEEK to always contain data from the most recent seven-day period. The conventional approach to this problem is to perform an expensive daily update, adding the newest day's data to a file and deleting the oldest day's data. However, the group facility provides a more efficient and convenient alternative.

Each time a new daily file is created, the older daily file (of the same name) is taken off line and archived. If the files must be preserved in chronological order, the definition of the group is modified to reflect the seven most recent daily files. This approach does not require data deletion, file reorganization, or program changes. The archived daily files can be saved permanently in their Model 204 format and can be restored easily to operating status.

Using groups to work with independent but similar data

Data concerning individual states or similar subdivisions is often kept in separate files. However, users sometimes require reports by various regional groupings or by an entire country.

With file groups, one user can select a report to be run against a single file, for example, OHIO, while another user can generate a report from the regional collection, for example, OHIO, INDIANA, and ILLINOIS. A third user's report might take into account all 50 states (a group can contain as many as 256 files).

All three of these reports can be generated by the same SOUL request, using a different group definition or by specifying an alternative OPEN command.

Using groups as file aliases

A group can consist of only one file, and can have the same name as an existing file. These two facts allow a group name to act as an alias for a Model 204 file. This allows for the possibility of users addressing a single file by many different names.

Suppose several application programs have been written to operate on a file named FILEA. This file is subsequently merged with FILEB, and the new combined file named FILEC. None of the field names in the combined file have been changed, so application programs could continue to run with the new file. However, those programs open the file named FILEA, not the combined file named FILEC.

The file group feature provides a technique that enables application programs to access the correct file without undergoing a program change. The system manager can define a permanent file group named FILEA that is made up only of the file named FILEC. The application programs need not be changed. When they run, they automatically access the FILEA group.

A similar strategy can be helpful when testing programs with test files that have different names from those that are used during production.

Types of groups

There are three types of groups:

• Permanent groups are created by the system manager with CREATE. The group name and member list are stored permanently in a Model 204 file until explicitly deleted by the system manager.

Any user can open a permanent group, unless the group requires a password, in which case the user must know the password. See the discussion about group passwords in File and group passwords.

• Temporary groups are created by an individual user with the CREATE command and can be referenced only by that user.

Temporary group names exist only during the current login session and are deleted automatically when you log out, unless you delete them during the session.

• Ad hoc groups have no name and are created within a SOUL request by prefacing a statement with the clause:

IN file1 [,file2 ...]

Ad hoc groups exist only for the current request. They allow record retrieval from many files at once without defining a group in advance. As in any IN clause, all of the files in an ad hoc group must be opened before the group is mentioned. Ad hoc groups are discussed in more detail in Ad hoc groups.

Creating groups

The CREATE command is used to create both permanent and temporary file groups. Only the system manager can create a permanent group.

Any user can create a temporary group by entering:

CREATE [TEMP] GROUP groupname FROM filename [,filename ...] [PARAMETER parameter list] . . . END

At least one file name is required. The following parameters can be included in the list. They are discussed in the description of the CREATE command, in CREATE command: Temporary group and CREATE command: Permanent group.

• UPDTFILE — Defines the group's update file.
• PROCFILE — Defines the group's procedure file.
• BLDGFT — Creates a group's field table.

Specifying PROCFILE = * creates a group in which any files can contain procedures.

Deleting groups

The DELETE command is used to delete both permanent and temporary groups (only the system manager can delete a permanent group):

DELETE [PERM | TEMP] [GROUP] name

You must close a group before you can delete it.

Examples

The following example shows the creation of a temporary group.

CREATE GROUP REGION FROM DELAWARE, MARYLAND, - VIRGINIA PARAMETER PROCFILE = VIRGINIA, BLDGFT = NO END

The following example creates a permanent group with multiple procedure files:

CREATE PERM GROUP REGION FROM DELAWARE, MARYLAND, - VIRGINIA PARAMETER PROCFILE = *, BLDGFT = NO END

Opening and closing Model 204 files and groups

Two ways to open files and groups

OPEN/OPENC can be used as either a command or statement to open Model 204 files and groups.

• For a discussion of OPEN/OPENC as a statement, see OPEN or OPENC statement. For a discussion of error handling, see Handling errors in file/group open statements.
• For a discussion of OPEN/OPENC as a command, see the List of Model 204 commands.

Using OPEN/OPENC as a command

When used as a command, OPEN/OPENC opens a file or group and allows retrievals or other references to fields or data records for the file or group in the same request. It also allows updates to a file to be deferred. As a command, OPEN/OPENC can be used within a procedure but must be outside of the request (outside the BEGIN and END statements).

Using OPEN[C] as a statement

When used as a statement, OPEN/OPENC opens a file or group but does not allow retrievals or other references to fields or data records for the file or group in the same request. It does not allow updates to a file to be deferred. As a statement, OPEN/OPENC must appear within the request (between the BEGIN and END statements).

Opening multiple files or groups

You can open two or more Model 204 files or groups concurrently. When multiple files and/or groups are open, you can let Model 204 operate on the default file or group, or direct Model 204 to operate on a specific file or group. Within a single request, you can refer to any open files or groups and can cross-reference records contained in them. Each of these remains open until you issue a CLOSE command or the $Close function for it, or issue the CLOSE ALL command.

Opening a remote file

You open a remote file by issuing the OPEN FILE command using either the AT location clause or a file synonym. You can also use an OPEN GROUP command if the file is a member of a scattered group.

File context

You can open a file in single file context or in permanent group context. A file open as a member of a temporary group is considered open in single file context. You can open in a different context an already open file. Therefore, a remote file can be open in any or all of the following contexts at the same time:

• Single file
• Permanent group
• Multiple permanent group

File locking behavior

The locking behavior of the OPEN FILE command for a remote file is identical to that for a local file with regard to:

• Shared direct access storage devices (DASD)
• System level resources
• Application subsystems

See Resource locking for information about resource locking.

Field definition is restricted

When the OPEN FILE command is successfully executed and a remote file is opened, the status of the file is open. The remote file's Table A is stored on the client system for as long as the file remains open.

While a remote file is open to any remote user, the fields cannot be redefined, deleted, or renamed on the server. Server online users receive a message that the file is in use. New fields, however, can be defined.

Opening deferred update data sets

A file that is not in deferred update mode can be opened remotely.

A file that is in deferred update mode can be opened remotely only when the file is a member of a service application subsystem. If a remote deferred update data set is specified in the OPEN FILE command, the open is rejected.

Opening a scattered group

You open a remote file that is a member of a scattered group by issuing the OPEN GROUP command. OPEN GROUP for scattered temporary and permanent groups has the same syntax as for non-scattered groups. Password requirements and privileges for member files are also the same for scattered and non-scattered groups.

In scattered group context, OPEN GROUP causes Model 204 to allocate conversations with each of the nodes that contain members of the scattered group (if such conversations do not already exist).

If scattered groups are defined to allow update privileges, all member files are opened with the indicated privileges when the group is successfully opened. For each remote file opened in group context, Model 204 displays a confirmation message with the file's name (non-synonym) and location, stating whether updates are allowed.

Opening non-Model 204 files

Non-Model 204 files can be opened within a request by using the form of the OPEN statement described in OPEN statement.

File and group passwords

Whether you must enter a password when you open a files or permanent group depends on which of the following access types was assigned to it:

• Public
• Semipublic
• Private

If file or permanent group is...	Model 204...
Public	Opens it without asking for a file password when the OPEN command is issued.
Semipublic or private	Asks you to enter a password during the OPEN operation. For: Private file or permanent group, you must enter a password in order to open it. Semipublic files and permanent groups, the password is optional.

Passwords are specified differently for temporary file groups. Opening a temporary group is functionally equivalent to opening a series of files. As each file is opened, you are prompted for the file password, if one is required. The temporary group is opened only after all the files have been opened.

File and group privileges

The file manager determines the privileges associated with each password associated with a file or permanent group. The assigned privileges determine which operations you can perform on the data and procedures stored in the file or group.

The file manager also determines the default privileges that are granted for public and semipublic files and permanent groups. The system manager must enter all file passwords and privileges into the system.

The privileges for a temporary group are the most restrictive combination of member file privileges. This combination is defined through a logical AND of the privileges of the individual files in the group.

For an explanation of how the granting of privileges depends on the reference context of a command or a statement, see Privileges according to reference context. See File security for details.

Displaying file and group information

You can display information about one or more open files or groups with the DISPLAY command:

DISPLAY [FILE | [PERM | TEMP] GROUP] [(option [, option ...])] {ALL | name [, name ...]}

If you enter:

DISPLAY FILE ALL

Model 204 displays the file name and file parameters for all files that you currently have open. If the DISPLAY command is issued by a file manager, the display includes file data set names. You can also use DISPLAY to display selected or abbreviated file parameters for files, by specifying them as display options.

If you enter:

DISPLAY GROUP ALL

Model 204 displays the group name, status (permanent or temporary), member files, and group parameters for all permanent groups and for your temporary groups. You can request that the command display only a list of group names and their status.

Closing files and groups

During a single Model 204 session, you can open several files and/or groups. These remain open until you issue a CLOSE command, as follows:

CLOSE [ALL | [FILE | [PERM | TEMP] GROUP] name [AT location]]

Closing a permanent group closes each file in the group that was opened by a group OPEN. But it does not close files that were opened as individual files or as members of other groups. Closing a temporary group does not close the files in the group.

You can also close a file or group (with some restrictions) within a SOUL request using the $Close function.

Open statement and OpenC statement

The Open and OpenC statements are useful for opening a file, either for subsequent requests, or to allow the request to take actions based on the file parameters of the file.

The effect of executing the Open[C] statement, like any SOUL statement, takes place during evaluation of the request. Therefore, if the file was not open during compilation, most SOUL statements, such as DML statements (Find, For, Store Record, etc.) cannot refer to the file within the request.

Some SOUL operations, such as obtaining file parameters, do not require a file to be opened during compilation. Thus, after an Open[C] statement, the request can obtain the status of the file by using the $View function to return the value of the FISTAT parameter.

After a Open[C] statement, a subsequent request may access the data in the file.

The Open and OpenC statements are supported in remote context. The use of filename synonyms is fully supported.

Syntax

The format of the Open or OpenC statement is:

Open[C] [File | [Perm | Temp] Group]
{name [At {location | %variable | =}] | %variable}
[Password {value | %variable}]

Where:

• Open specifies that the specified file or group becomes the new default file or group context.

  OpenC specifies that the previous default file or group is preserved when the specified file or group is opened.

  Default files and groups are discussed later in this page.

• The File keyword specifies that the file to be opened is a Model 204 file.
• The Perm keyword specifies that the group to be opened is a Model 204 permanent group.
• The Temp keyword specifies that the group to be opened is a Model 204 temporary group.
• The Group keyword specifies that the file to be opened is a Model 204 group.
• name is the name of the Model 204 file or group to be opened. The file or group name can be provided in a %variable or as a quoted or unquoted string.
• The At keyword specifies that the file to be opened is a remote file. Only individual files (or group members) can be specified using the At keyword. An entire group cannot be treated as a remote object. Thus none of the keywords Perm, Temp, or Group can be used with At.

  A remote file can also be opened using a file synonym (without the At clause) or by opening a scattered group of which the file is a member.

• location is the name of the remote node where the file is located. The location can be provided in a %variable.

  The equal sign (=) directs Model 204 to open a local file. Since it is possible for two files at different nodes to have identical file names, the equals sign gives you the ability to explicitly use the local file instead of the remote file with the same name.

• The Password clause specifies a valid password for the file or group to be opened. The password value can be provided in a %variable or as a quoted or unquoted string.

Usage notes

• If the Group keyword is specified without a Perm or Temp keyword, Model 204 searches for the name first among temporary groups, then among permanent groups. If no keyword is specified, Model 204 searches for the name among temporary groups first, then permanent groups, and finally Model 204 files.
• The following message is produced for a SOUL Open[C] statement if the Open fails:

  *** M204.1521: fileOrGroupName does not exist or requested access not authorized

  Message 1521 is a counting error and when encountered during APSY processing invokes the APSY error procedure.

Handling errors in file/group open statements

Error conditions encountered during the processing of the OPEN or OPENC statement generate Model 204 error messages that are not displayed on the terminal. The request should check for errors after the execution of each OPEN or OPENC statement by using the $Status function. The text of the most recently issued error message can then be retrieved by the $ErrMsg function.

The values that can be returned by the $Status function for the OPEN or OPENC statement are listed in the following table:

Value	Meaning
0	The operation was successful. A return code of 0 also clears the message buffer; therefore, the $Errmsg function, if called returns a null string.
2	A serious error occurred. The error can be retrieved by using the $Errmsg function to receive the last counting or cancellation message produced by Model 204.

If OPEN GROUP is issued as a SOUL statement (from within a request), the result of the open operation is indicated with one of three $Status values:

$Status	Description
0	All members of the group were successfully opened.
1	One or more optional members could not be opened.
2	A mandatory member could not be opened, MAXFAIL members could not be opened, or all members are missing.

Example

BEGIN . . . OPEN PERM GROUP REGISTERED.AUTOS IF $Status NE 0 THEN PRINT 'OPEN ERROR ON AUTO FILE' PRINT $ERRMSG STOP ELSE . . .

For more information about $Status, see Horizon conversation interface.

If the DDNAME of the file to be opened is greater than eight characters, the command is rejected and the following message is issued:

M204.1903: %C EXCEEDS 8 CHARACTERS IN LENGTH

Error conditions relating to remote files

Using the AT keyword with the PERM, TEMP, or GROUP keywords (or with the OPEN DATASET, OPEN EXTERNAL, or OPEN [EXTERNAL] TERMINAL statements) causes the following error message:

M204.1497: REMOTE SPECIFICATION CONFLICTS WITH OPEN TYPE

If, when attempting to open a remote file, Model 204 cannot establish a conversation with the remote node, the following error message displays:

M204.1984: COMMUNICATION ERROR ON REMOTE NODE PROCESSING FILE filename AT location

If a %variable is used to indicate the location of a remote file, and its value is found to be null, the value of the $Status function is set to 2 and the following error message is generated:

M204.2003: LOCATION MISSING FOR REMOTE FILE

Error conditions relating to scattered groups

• If a mandatory member of a scattered group cannot be opened, the OPEN operation fails for the entire group.
• If an optional member of the group cannot be opened, an error message is issued stating that the file is unavailable. The OPEN operation continues as if the file were not included in the group definition. Storage is still allocated in various internal data structures, however.
• If the CREATE GROUP command MAXFAIL parameter value is exceeded, the group open fails and any successfully opened files are closed. An error message is issued stating that more than MAXFAIL optional files cannot be opened.

If all a scattered group's files are optional and unavailable, a group open fails, even if MAXFAIL is not exceeded. An error message is issued stating that the open failed because all group members are missing.

Closing a remote file

You can close a remote file by issuing the CLOSE command using the AT location clause or a file synonym, using CLOSE ALL, or, if the remote file is the default file, using CLOSE by itself. If the file is a member of a permanent scattered group, you can close the files in the group with CLOSE GROUP.

When a CLOSE command for a remote file is successful, the file is closed on the server node on which the file resides. Model 204 displays a message confirming the close to the user on the client node. The message identifies the file name and location.

If the file being closed is your last open file on the server node, the conversation with the server is terminated.

A loss of communications with a remote node during or just prior to your attempt to close a remote file results in the following:

• The file is closed on your local node, and you receive a communications error message. The service thread is restarted, which closes the file on the server.
• If the file is a member of a scattered group and you issue CLOSE GROUP, the file is closed on your local node, and Model 204 attempts to close as usual the rest of the files in the group.
• If the file was disabled for you prior to the CLOSE, the file is closed only on your local node.

Using DEFAULT and DELETE GROUP

The Model 204 DEFAULT command, which establishes the current default file or group, applies to remote file synonyms, remote file specifications, and scattered groups.

The Model 204 DELETE GROUP command, which deletes an existing permanent or temporary group, applies to scattered groups.

Reference context

The reference context of a statement or command is the file or group in which the statement or command is to operate. If the reference context is a file, the context also involves the way in which the file was opened. The file or group on which a command or a SOUL statement operates is known as the current file or group.

When many files and groups are open, you must establish a single file or group context for commands and SOUL statements. You can specify a file or group or can allow the system to operate on the default file or group.

This section discusses how you specify the file or group reference context, how the reference context affects the privileges that accompany an OPEN of a file or group and the results of a CLOSE command, and procedure file and update file references.

For additional information about features relating to setting the reference context, refer to:

• IN clause
• IN GROUP MEMBER clause
• $CURFILE and $UPDATE functions

Establishing the default file or group

Unless the user refers to a specific file or group in a command or a SOUL statement, Model 204 operates on the default. Only one default can be in effect at any one time. The default can be either a file or a group.

You can establish the default in one of the following ways:

• OPEN command. The Model 204 file or group opened in the most recent OPEN command becomes the default.
  • However, the default file context is updated only after the request containing the OPEN statement has been evaluated. Therefore, the new default is in place only for subsequent requests.
  • If OPENC is issued instead of OPEN, a new default is not established and the previous default is preserved.
• DEFAULT command. Using the DEFAULT command, you can specify either a file or a group.
• IN clause. The default file/group context during compilation of a request is used, throughout the request, as the file/group context for statements that do not have their own context specification. An IN clause on a BEGIN or MORE command sets a default context that remains in effect only for compilation of that request.

Explicitly specifying the reference context

You can specify the file or group context of a SOUL statement in these ways:

• Explicitly referring to a FIND or SORT statement or to a list
• Using the IN clause
• Placing a statement within a record loop

Statements that do not fall into one of these categories operate on the default file or group established for the request. This can be established either by default or by an IN clause on the BEGIN or MORE command.

File and group OPENs and CLOSEs

A file can be an individual file, a member of a permanent group, a member of a temporary group, or any combination of these. When a file is referenced in a command or in a SOUL statement, Model 204 determines whether the file also is a member of an open group. The privileges available for a file can change along with its group membership.

If an OPEN command has been issued for a file or for a temporary group that contains the file, the privileges for that file are the same as those previously established for that file, regardless of whether the file also is a member of a permanent group. However, if a permanent group is opened, but no individual OPEN has been specified for a particular file in that group, the privileges available for that file, when an IN file reference is specified, are the same as those associated with the permanent group. The discussion on privileges and reference context on the next page lists all of the possible file/group combinations.

When a file or group is closed with the CLOSE command, Model 204 determines which OPENs have been issued for the file or group, as follows:

A CLOSE for...	Closes...
Individual file	Individual file. If the file also was opened as a permanent group member, it is still available for reference as a group member or in an IN file clause.
Permanent group	All files in that group, except those that have been opened as individual files or that also are members of other groups.
Temporary group	None of the files in the group.

Privileges according to reference context

The privileges associated with individual files and groups can be granted and combined in different ways, depending upon the reference context:

When you reference...	Your set of privileges are...
Individual file	Those granted by Model 204 when the file was opened. These are privileges associated with the specified file password or, if the password was not required or was specified incorrectly, the default file privileges. With application subsystems, user privileges are those associated with the user class or are the default file privileges.
Temporary or ad hoc group	Derived from the logical intersection of the individual privileges associated with the files that make up the group. Model 204 combines the privileges of all of the member files. You are granted only the privileges common to all the files in the group.
Permanent group	Those granted by Model 204 when the group was opened. These are the privileges associated with the specified group password or, if the password was not required or was specified incorrectly, the default group privileges.
File that is concurrently a member of two permanent groups and has not been opened as an individual file	Derived from the logical union of the privileges associated with the groups. Model 204 appends the privileges of each of the open groups of which the file is a member. A privilege granted to any of the groups is granted to the file.
File that has been opened both as an individual file and as a member of a permanent group	Those associated with the file, not the group. An open group has no effect on the file privileges.

When a file that is a member of a permanent group is not opened individually, its privileges are the same as those granted for the group. It still can be referenced individually in a command or in a SOUL statement. A file that is a member of a permanent group can also be opened individually.

Procedure file and update file references

When operating on a group, certain commands and SOUL statements refer to the procedure file or the update file associated with the group.

The group procedure file is the file in which procedures for the group are stored and from which procedures are retrieved or deleted. If an explicit procedure file is not defined with the PROCFILE parameter in the CREATE GROUP command, the procedure file can be specified in an IN clause. The IN clause also can be used to override the group procedure file specification.

The group update file is the file in which records for the group are stored with the SOUL STORE RECORD statement. If an explicit update file is not defined in the UPDTFILE parameter in the CREATE GROUP command, an update file can be specified in an IN clause. The IN clause also can be used to override the group update file specification.

Example

This request illustrates the various methods of context specification:

OPEN CLIENTS OPENC CLAIMS90 BEGIN GET.RECS: FIND ALL RECORDS FOR WHICH SETTLEMENT DATE IS LESS THAN 900401 END FIND PROCESS: FOR EACH RECORD IN GET.RECS DRIVER: %DRIVER = DRIVER INVOLVED MATCH.REC: IN CLAIMS90 FIND ALL RECORDS FOR WHICH DRIVER ID = %DRIVER END FIND COMPUTE: FOR EACH RECORD IN MATCH.REC IF STATE EQ 'FLORIDA' THEN %TOT = %TOT + 1 END IF END FOR END FOR PROCESS PRINT '1ST QUARTER, 1990: ' WITH %TOT - ' FLORIDA DRIVERS INVOLVED IN ACCIDENTS' END

In the preceding request, the OPEN command opens the CLIENTS file or group. The OPENC command also opens a file or group, in this case CLAIMS90. However, the OPENC command does not establish a new default.

The GET.RECS (default) and PROCESS (explicit reference) statements operate on CLIENTS. The DRIVER statement operates on CLIENTS because it is within the record loop for records from CLIENTS. The MATCH.REC (IN clause) and COMPUTE (explicit reference) statements operate on CLAIMS90.

IN clause

The IN clause precedes SOUL statements to override the default file or group. A special form also creates ad hoc groups.

A variation of the IN clause, IN GROUP MEMBER, restricts Clear List, Find, For Record Number, and Store Record statements to one member file in a group context. See IN GROUP MEMBER clause for more information.

Syntax

The basic form of the IN clause is:

IN [FILE | [PERM | TEMP] GROUP] {filename | groupname} MEMBER %member [AT {location | =}] statement-clause

If no FILE or GROUP option is specified, Model 204 searches for the name among open temporary groups first, then open permanent groups, and finally open files.

Specifying a remote file

A statement or command that references a file using the AT clause is called a remote file specification. The AT clause is valid only for single remote files or remote members of a scattered group explicitly referenced by an IN GROUP MEMBER clause (see IN GROUP MEMBER clause). Use an unquoted equal sign to instruct Model 204 to look for the file locally.

Note: The For Record Number statement does not support remote files.

The location names of remote nodes are established with the DEFINE PROCESS command. See PQO: Remote files and scattered groups for more on creating location names.

The location name in the AT clause can be coded as a dummy string inside a SOUL procedure. Using a dummy string allows the application programmer to code a single file reference in the procedure. Then, at run time, the user can enter a valid remote node name or an equal sign (=) to access different versions of the same file (having the same name), either remotely or locally. See Procedures for a detailed discussion of dummy strings.

A remote file can also be specified using a file synonym. A file synonym is a symbolic name for a remote file that references both the actual file name and the location name. Therefore, when using a file synonym, you do not use the AT clause. Even though a file synonym has been defined, you can still use the full remote file specification, as described above.

File synonyms are discussed in detail in PQO: Managing files and groups.

Ad hoc groups

The form of the IN clause shown below creates an ad hoc group:

IN file1[,file2] ...

This form can be used with FIND, FIND AND PRINT COUNT, FIND AND RESERVE, CLEAR LIST, and FOR EACH VALUE statements. The group consists of the listed files, which must already be open. The ad hoc group has no name and exists only for the duration of the request and any request continuations.

Remote files which are members of ad hoc groups can be specified OPTIONAL or MANDATORY. These keywords can be abbreviated OPT and MAN, respectively, as in this example:

IN file1 (OPT), file2 (MAN) ...

If you want to refer to an ad hoc group you created earlier in a request, you must repeat the earlier IN clause. If all of the required conditions for duplicate ad hoc groups are met, repetition of the IN clause does not create a second, identical ad hoc group. It only calls on the original ad hoc group definition stored in FTBL.

Duplicate ad hoc groups

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.

Duplicate groups do not require additional server table space or network traffic.

Clearing lists

The CLEAR LIST statement normally clears an existing list; no IN clause is required. When CLEAR LIST appears in a request before the first reference to the list, an IN clause might be necessary to create the list in the same context as the later references. References to an existing set of records in the CLEAR LIST or FIND statement override the IN clause.

IN GROUP MEMBER clause

The IN GROUP MEMBER clause can be used with CLEAR LIST, FIND ALL RECORDS (and its variants), FIND ALL VALUES, For Record Number (or FRN), and STORE RECORD statements; they are restricted to one member file in a group context.

Syntax

The format of the IN GROUP MEMBER clause is:

IN [TEMPORARY | PERMANENT] GROUP groupname MEMBER {%member | filename [AT {location | =] statement

Where:

• groupname is the name of the file group
• %member is a valid %variable, image, or screen item that indicates the group member for the CLEAR LIST, FIND, For Record Number (FRN), or STORE RECORD statement.
• filename specifies the name of a file where location indicates a valid remote node name or the equal sign (=) indicates that you want Model 204 to look for the named file only locally.

  Note: The For Record Number option does not support remote files.

• statement is one of the following:

  CLEAR LIST

  FIND ALL RECORDS

  FIND ALL VALUES

  For Record Number (FRN)

  STORE RECORD

Examples

Suppose, for example, that the group JANSALES consists of several files corresponding to sales regions. The following statement retrieves a set of records for a single region. The file to be searched has been specified by screen input.

FDREG: IN GROUP JANSALES MEMBER %SSCREEN:REGION - FIND ALL RECORDS FOR WHICH TOT GT 500 END FIND

The following example illustrates using a For Record Number (FRN) option:

BEGIN %GRPMEMBER='AUGUST' FD: IN GROUP YR2001 MEMBER %GRPMEMBER FRN 164 PRINT FULLNAME WITH DOB AT 35 WITH SSN AT 50 END FOR END

Uses for the IN GROUP MEMBER clause

The most common use of the IN GROUP MEMBER clause is to improve the efficiency of FIND statements when it is known in advance that some group members contain no records that meet the FIND criteria. For example, if Red Sox caps are only sold in the Northeast, the FIND statement labeled 'GETNE' below avoids a search through all the regional files.

Another possible use of the IN GROUP MEMBER clause is to build a list by processing one file at a time. Suppose, for example, that a department store chain wants to analyze sales of Boston Red Sox caps in regions other than the Northeast. The selective IN syntax could be used to create the appropriate list by subtraction, as follows:

GETCAPS: IN GROUP JANSALES FIND ALL RECORDS - FOR WHICH ITEM = 'SOXCAP' CAPLIST: PLACE RECORDS IN GETCAPS ON LIST FARFANS %X = 'NOREAST' GETNE: IN GROUP JANSALES MEMBER %X - FIND ALL RECORDS FOR WHICH ITEM = 'SOXCAP' FARLIST: REMOVE RECORDS IN GETNE FROM LIST FARFANS

Use with lists

Lists can be created from the results of group FINDs. Records from a group FIND (not using the IN GROUP MEMBER clause) cannot be placed on a list created by an individual file FIND, even if the file is a member of the group, and vice versa.

However, records found using the IN GROUP MEMBER clause can be added to or removed from the same list as records from group FINDs that do not involve using the IN GROUP MEMBER clause.

Use with $CURFILE and $UPDATE

You cannot use an IN clause that includes both MEMBER and $CURFILE or $UPDATE.

$Curfile and $Update functions

Use with IN clause

The IN clause also can be specified as shown here:

IN {$CURFILE | $UPDATE}

$Curfile and $Update are the only functions that can be used outside of normal function syntax.

• $Update can be used to satisfy the IN clause requirements of INCLUDE and STORE RECORD.
• $Curfile can be used to satisfy the IN clause requirements for STORE RECORD only.

$Curfile function

The $Curfile function returns the name of the current file in a record loop. The current file is defined as the file from which the current record has been selected when the record loop refers to a group. You can use an IN $Curfile clause only within a record loop.

An IN $Curfile clause can add records to a file based on other data in that file, without regard for the actual file name. The file need not be a member of a group.

$Update function

The $Update function returns the name of the update file in the current group or, if a current group does not exist, the name of the current file. If no update file for the current group was specified, an IN $Update clause elicits an error message.

Restrictions for $Curfile and $Update

You cannot use an IN clause that includes both MEMBER and $Curfile or $Update.

Example 1

This sequence illustrates the use of a temporary group with an update file:

CREATE TEMP GROUP FISCAL FROM FY89, FY90, FY91 PARAMETER UPDTFILE = FY91, PROCFILE = FY89 END OPEN GROUP FISCAL BEGIN GET.ACCT.NO: %A = $READ('ENTER ACCT NO OR "CR"') IF %A EQ " THEN JUMP TO TOT.CT END IF %B = $READ('ENTER AMOUNT') IF %B EQ " THEN JUMP TO TOT.CT END IF FIND.ACCT.RECS: IN $UPDATE FIND ALL RECORDS FOR WHICH ACCT NO = %A END FIND CT: COUNT RECORDS IN FIND.ACCT.RECS IF COUNT IN CT GT 1 THEN PRINT 'ACCT MULTIPLY DEFINED' AND %A JUMP TO END.REQUEST END IF COMPUTE.B: FOR EACH RECORD IN FIND.ACCT.RECS %B = %B + AMT CHANGE AMT TO %B JUMP TO GET.ACCT.NO END FOR ADD.REC: STORE RECORD ACCT NO = %A AMT = %B END STORE GET.NEXT: JUMP TO GET.ACCT.NO TOT.CT: FIND AND PRINT COUNT END.REQUEST: END

The request searches the group update file (FY91) for an account number to match the one entered by the user.

• If there is more than one record with that number, the request ends.
• If a single record exists, the amount entered by the user is added to that record. The request then asks for a new account number.
• If no record exists with a particular account number, the FOR loop falls through to the ADD.REC statement. The STORE RECORD statement does not contain an IN clause and thus stores the new record in the update file, FY91.

When the user indicates that updating is finished by pressing a carriage return in response to the first prompt, execution proceeds to the TOT.CT statement. The TOT.CT statement contains neither an explicit reference to another statement nor an IN clause, so the request prints a single combined count of the number of records in the three files in the group.

Example 2

The next example creates an ad hoc group from the open files HISTORY and FY90. The COMPUTE.TOT statement causes the amount fields from both files to be added to a grand total to be printed at the end of the request. The CHANGE.CAT statement uses the $CURFILE function to limit the budget category change to records in the history file.

BEGIN A.CAT: IN HISTORY, FY80 FIND ALL RECORDS FOR WHICH BUDGET CAT = A OR AA END FIND FOR EACH RECORD IN A.CAT COMPUTE.TOT: %TOT = AMT + %TOT CHANGE.CAT: IF $CURFILE EQ 'HISTORY' AND - BUDGET CAT EQ 'AA' THEN CHANGE BUDGET CAT TO 'A' END IF END FOR PRINT 'TOTAL DOLLARS THRU 1990: ' WITH %TOT END

Context when using statements outside record loops

Most SOUL statements that appear outside record loops can operate in either a file or group context.

A few statements (such as the two listed below) require further specification in group context. Sometimes the specification appears in the group definition; in other cases, an IN clause is used to override a group default.

• INCLUDE requires a group procedure file or an IN clause.
• STORE RECORD requires a group update file or an IN clause.

Groups with multiple procedure files

If you specify "PROCFILE = *" when a group is created, then that group can contain more than one procedure file. When a procedure is included, search order is determined by the order in which the files were specified in the CREATE GROUP command.

The use of multiple procedure files in application subsystem development is explained in Application Subsystem development. For more information, see CREATE GROUP command information.

Cross-referencing

Cross-referencing means using data from one place to determine retrieval or update operations in another.

Example

This example illustrates cross-referencing between a group and a file. The temporary group FISCAL is the group defined earlier in this page.

OPEN FILE HISTORY OPEN GROUP FISCAL BEGIN A.CAT: FIND ALL RECORDS FOR WHICH BUDGET CAT = A END FIND PLACE RECORDS IN A.CAT ON LIST REMAINDER FOR EACH RECORD ON LIST REMAINDER %ACCT = ACCT NO MATCH: FIND ALL RECORDS ON LIST REMAINDER FOR WHICH ACCT NO = %ACCT END FIND REMOVE RECORDS IN MATCH FROM LIST REMAINDER HIST.MATCH: IN HISTORY FIND ALL RECORDS FOR WHICH ACCT NO = %ACCT END FIND HIST.CT: COUNT RECORDS IN HIST.MATCH IF COUNT IN HIST.CT NE 0 THEN PRINT %ACCT WITH ' FOUND IN HISTORY' JUMP TO NEXT.REC END IF PRINT %ACCT WITH ' NOT FOUND IN HISTORY' NEXT.REC: *GO TO NEXT RECORD ON LIST END FOR END

The A.CAT statement finds a set of records from the default group FISCAL. Records from the group are placed on a list. As records are processed, other records in the set that have identical account numbers are removed so that each account number is printed only once. Until the HIST.MATCH statement, all statements refer to FISCAL.

The HIST.MATCH statement uses the account number from the current record in FISCAL to search the single file HISTORY. The HIST.MATCH through HIST.CT statements refer to the HISTORY file. A message is displayed to indicate whether or not the history file contains records with the current account number.

Group operations in SOUL

The following discussion summarizes the ways in which file groups affect the following SOUL operations:

• Find statement
• Sorted files
• Sort statement
• Lists
• Record numbers
• For Each Value statements
• Field type variations within a group
• For Each Record statements

FIND statement

When a FIND, FIND AND PRINT COUNT, or FIND AND RESERVE statement is used in a group context, Model 204 performs a series of individual file FINDs; however, the group FIND results in one set of records instead of several sets. Records in the set are arranged by file in the order in which the members were listed when the group was created. Any record loop statement referring to this set automatically switches files at the appropriate time. Once a record is selected by the loop, operations are performed only on that record and the file that contains it.

Sorted files

Files with sort key organization can be used as members of groups. However, there is no group sort sequence. Therefore, the SFL$ and SFGE$ conditions cannot be used in a group FIND. The IN ORDER clause is not allowed in a For Each Record statement that refers to a group.

SORT statement

The SORT statement can refer to a group FIND or a group list. The entire set of records is sorted across file boundaries to produce a single, temporary set of records. These records then can be processed with a For Each Record loop. The $CURFILE function can be used to print the original file names of the individual sorted records.

Lists

Lists can be created from the results of group FINDs. Records from a group FIND cannot be placed on a list created by an individual file FIND, even if the file is a member of the group, and vice versa. Records from different groups cannot be placed on a single list.

An individual record within a For Each Record loop on a group can be added to or removed from a list.

Record numbers

The $CURREC function and the POINT$ condition of the FIND statement are not recommended for use in a group context. Both $CURREC and POINT$ refer to the internal record numbers of a file; these numbers are assigned to records on a file basis as records are added. At a group level, the record numbers have no meaning because the record numbers are not unique within a group. POINT$ cannot be used as a condition in a group FIND. The $CURREC function can be used, but you must ensure that the number is used only in reference to the file from which the record came.

The value form of the For Record Number statement can be used in group context. When a value is specified and group context is desired, the statement must be preceded by an IN clause in order to indicate the name of the file in which the record number occurs.

FOR EACH VALUE statement

When the FOR EACH VALUE statement refers to a group, the values are supplied in order. If, in at least one of the group members, the value field is ORDERED NUMERIC, the values are supplied in numerical order. Otherwise, they are supplied in order according to the standard EBCDIC collating sequence.

Field type variations within a group

It is possible that a given field name might not have the same properties in every file in a group. A field name, for example, can have the NUMERIC RANGE attribute in some files, but not in others. Furthermore, a field that appears in one or more files of a group might not exist in any of the others.

KEY and NON-KEY fields

Within a group, a field can be defined as KEY in some files and NON-KEY in others. When this occurs in a group FIND condition, the FIND statement performs a key search based on the index in those files in which the field is defined as KEY, and it does a direct search of the data records in the files in which it is defined as NON-KEY.

NUMERIC RANGE and NON-RANGE fields

The FIND statement operates in a similar manner when a numeric retrieval is specified for a group in which some files have the field defined as NUMERIC RANGE, and others have it defined as NON-RANGE. Records in files that have the field defined as NUMERIC RANGE are retrieved through the index, and records in the other files are retrieved by a direct search.

Absent fields

When some files in a group do not contain a specified field, records in those files are handled as if they contained the absent fields. If none of the files contain a specified field, any statement referring to that field is rejected.

PRINT and SORT statements

Another field type conflict affects PRINT and SORT statements. When specified fields have the INVISIBLE attribute in some files and not in others, records that contain INVISIBLE fields are handled as if the field does not exist. If the field is INVISIBLE in all the files, the PRINT or SORT statement is rejected.

Processing

Suppose you attempt to change a field described as LENGTH 3 to the value COLORADO. In group context, this change is rejected during compilation only if it is invalid in all of the files in the group. Otherwise, the reference is accepted during compilation. It is rejected during evaluation only if an attempt is made to change a field that is too short to contain the new value.

In general, references in group context are rejected during compilation only if they are invalid for every file in the group. Otherwise, all validity checks are made at the file level during evaluation.

FOR EACH RECORD statement

The For Each Record In Order By form of the For Each Record statement is not allowed in group context.

Referencing remote files in requests

Request compilation is initiated when Model 204 encounters a BEGIN command. A request that refers to a remote file is compiled on both client and server nodes. Model 204 initiates compilation on the remote server system when a reference to a remote file is first encountered.

During compilation, as remote references are encountered, the client system sends data manipulation language (DML) calls to the participating server node, or nodes, to be compiled.

Example

The following example below shows an excerpt from a procedure that references a Model 204 file (named VEHICLES) residing at a remote location (whose symbolic name is defined as BOSTON).

Prior to accessing a remote file, the following conditions must be met:

• The Parallel Query Option/204 network is defined on both the client and server systems.
• The OPEN LINK command is successfully issued by the Model 204 system manager (or User 0) on both the client and server systems, so that the connection for the Parallel Query Option/204 conversation is enabled.

DEFINE FILE CARS WITH SCOPE=SYSTEM - FILENAME=VEHICLES - LOCATION=BOSTON OPEN CARS . BEGIN . FD: IN CARS FD MAKE=FORD END FIND . . . FR: FR IN FD PAI END FOR . . . END

Input/output operations that involve network transmissions are entailed in using the OPEN, FIND, and FOR statements to reference a remotely located file.

In the previous example:

• OPEN

The user request to open a remote file (CARS) initiates activity at the remote location (BOSTON) where the file resides.

The server sends a copy of the Model 204 file information (Table A) to the user's (client) node so that compilation can proceed.

• FIND (FD)

The client sends FIND criteria (FORD vehicle records) to the remote location for evaluation.

• FOR EACH RECORD (FR)

The client processes records using a For Each Record loop.

The server sends records from the found set to the user's node, one page of records at a time. Only records in the found set are transmitted.

The previous example shows remote file references using a file synonym. As an alternative, if no DEFINE FILE command is issued on the client system, you can reference the remote file using a remote file specification (AT clause).

For example, instead of OPEN CARS, you use:

OPEN VEHICLES AT BOSTON

Instead of IN CARS FD, you use:

FD: IN VEHICLES AT BOSTON FD

See PQO: Remote files and scattered groups for additional information.

Request continuation is not supported

Remote file reference is not supported in a request continuation.

The MORE command and END MORE statement are not supported if the continued request refers to a remote file.

Errors during compilation and evaluation

Compilation and evaluation errors in Parallel Query Option/204 applications are discussed in separate sections below. Both sections discuss how Model 204 handles noncommunications errors and communications errors when a remote file is referenced.

Compile time error handling

If a noncommunications error occurs during compilation when a client application references a file on a server node:

• Model 204 prints on the client node the current line in the client procedure and the error message that was generated on the server node.
• Compilation continues on the client node only, regardless of the number of errors encountered on server nodes.

If a communications problem occurs during compilation, in any remote file or group context:

• The compilation is terminated.
• All files at the referenced node are disabled for the client user.

Evaluation time error handling

Model 204 begins to execute a SOUL request even though that request contains a reference to a remote file or group that was already made unavailable to the request prior to evaluation. The action Model 204 takes depends on the context of the file or group referenced in the request:

Context	Action
Remote single file	ON MISSING FILE unit invoked
Scattered group	ON MISSING FILE unit invoked
File member of scattered group	ON MISSING MEMBER unit not invoked

If a noncommunications error occurs on an already opened remote file, the error message generated at the remote node is printed on the client node, and the request is canceled.

If you lose communications during evaluation with an already opened remote file, all files at that node are disabled for you, and Model 204 makes one of three responses:

• Takes no further action, if all of the following are true:
  • File is in group context
  • File is an optional group member
  • MAXFAIL parameter setting in CREATE GROUP is not exceeded
  • Node to which the file belongs has no uncommitted updates
• Invokes one of two ON units:
  • ON MISSING MEMBER
  • ON MISSING FILE
• Invokes the ON ERROR unit (if present) and cancels the request.

Using ON MISSING MEMBER and ON MISSING FILE

The specific behavior of the ON MISSING MEMBER and the ON MISSING FILE units is described below. For a code example with these ON units, see Using file and group availability $functions.

Using the ON MISSING MEMBER unit

ON MISSING MEMBER handles errors involving the availability of scattered group members. It obeys the same scoping rules as all other ON units. Its format follows:

ON MISSING MEMBER . . . END ON

ON MISSING MEMBER is invoked whenever the following are all true:

• An operation in group context fails against a remote optional member of the group.
• The member was not previously unavailable to the request.
• The MISSING FILE condition is not raised.

When ON MISSING MEMBER is invoked, these consequences follow for all the user's member files at that server node:

• The group member is made unavailable to the group (both during and after request execution).
• The group member is considered disabled.
• Subsequent references to the group in the same request for files at that server do not invoke ON MISSING MEMBER.

If an operation in group context fails against a remote optional member of a group and no ON MISSING MEMBER unit is active, the member is made unavailable to the group and the operation completes as if the member were not part of the group definition.

When control is passed to an ON MISSING MEMBER unit, you can return control to the request with a RETRY, BYPASS, or JUMP TO statement.

ON MISSING MEMBER units cannot be nested.

Communications failures during ON MISSING MEMBER

If a communications failure occurs while communicating with a different node within an ON MISSING MEMBER unit, the ON ERROR unit is invoked or the request is cancelled.

If a communications failure occurs while receiving records from a remote node in a For Each Record loop in scattered group context, you can use either the CONTINUE statement or the BYPASS statement to instruct Model 204 how to proceed:

• The CONTINUE statement causes the FOR loop to continue processing records from the next available group member. All unavailable files are skipped, but the remaining available files are processed. Note that you cannot use the CONTINUE statement with an ON MISSING MEMBER unit unless the return value of the $MISSTMT function is FOR.
• The BYPASS statement tells Model 204 to exit the FOR loop, ignoring any unprocessed group members, and continuing request execution with the statement immediately following the END FOR which closes the current FOR loop.

Using the ON MISSING FILE unit

ON MISSING FILE handles errors involving the availability of remote files in single file context, and involving mandatory and MAXFAIL conditions of remote files in group context. It obeys the same scoping rules as all other ON units. Its format follows:

ON MISSING FILE . . . END ON

ON MISSING FILE is invoked for any of the following circumstances:

• An operation in single file context fails against a remote file.
• An operation in group context fails against a remote mandatory member.
• An operation in group context fails against a remote optional group member and the number of missing members is greater than the MAXFAIL parameter (CREATE GROUP).

When ON MISSING FILE is invoked, these consequences follow:

• The file or group is made unavailable to the request.
• The file or group is disabled for the user.
• All future references to the file or group in the same request cause the request to be canceled.

If an operation that normally calls for an ON MISSING FILE unit fails, and no MISSING FILE unit is active, the ON ERROR unit is invoked. If no ON ERROR unit is active, the request is canceled.

When control is passed to an ON MISSING FILE unit, you can return control to the request with a BYPASS or JUMP statement. RETRY is not allowed.

ON MISSING FILE units cannot be nested.

Communications failures during ON MISSING FILE

If a communications error failure occurs while communicating with a different node within an ON MISSING FILE unit, the ON ERROR unit is invoked or the request is canceled.

Clearing ON MISSING MEMBER and ON MISSING FILE

Like other ON units, you can clear ON MISSING MEMBER and ON MISSING FILE with the CLEAR ON command, according to the following syntax:

CLEAR ON [MISSING FILE | MISSING MEMBER}

Using retrieval statements with remote files

This section describes the individual SOUL retrieval statements (and any usage restrictions) that you can use with a remote file or group.

Using the FIND ALL RECORDS statement

All forms of the FIND ALL RECORDS statement are supported in remote file and scattered group context.

A FIND statement in remote context produces a record set on each of the server nodes to which the statement refers.

All record locks are maintained on the server nodes. If a record locking conflict occurs, partial found sets are dequeued (on several nodes if necessary), and the normal FIND CONFLICT action is taken.

See the discussion of LOCATION$ on Using retrieval conditions for information about restricting group context FIND results.

Using the FOR EACH RECORD statement

All forms of the For Each Record statement are supported in remote file and scattered group context except for the IN ORDER clause, which is not supported in scattered group context.

Except for the following cases, when a FOR statement is executed, it retrieves from each record only the fields that are referred to in the loop. Data is handled differently by the server in the following cases:

• If the FOR loop references a field name variable, such as %%fieldname, or if it contains a PAI statement, the entire record is transmitted from the server node.
• If a subscripted field reference is used in a FOR loop, all occurrences of the field are transmitted from the server node.

A CODED field is decoded before being transmitted from the server node.

OPTIMIZING FNV option

Use the OPTIMIZING FNV option with the For Each Record statement to optimize retrievals with field name variables. You can abbreviate this option to OPT FNV. OPTIMIZING FNV prevents FOR loop retrievals with field name variables from triggering the retrieval of all fields and all occurrences.

Specify OPT FNV in one of two places:

• Before the WHERE or WITH option and after all other options
• At the end of the FOR statement when the WHERE or WITH option is not present

When you use OPTIMIZING FNV, only the initial value of the field name variables (%%variables) at the start of the FOR loop are used to select the fields that are retrieved and shipped to the client node. Therefore, the field name variable must have the proper value at the time the FOR loop is first executed. Each time the FOR loop is entered (after the loop has completed), the field name variable values are reset.

If the field name variable is changed in the FOR loop to the name of another field that was not explicitly referenced, the other field is not retrieved and a default value of null is used for the field name variable reference. See Field name variable optimization.

Using the For Record Number statement

All forms of the For Record Number statement are supported in remote file and scattered group context, although For Record Number and For Record Number In label might have different results if you are working with records that are not locked.

For Record Number In label refers to a preceding For Each Record statement. In Parallel Query Option/204, the records retrieved for the For Each Record loop are copied and sent to the client when the For Each Record statement is evaluated. If the records are not locked after the retrieval, by the time the For Record Number In label statement is executed, the record copy to which you are referring might no longer match the record at the server.

However, if you use For Record Number without In label, Model 204 locks the record to which you are referring and sends a copy to the client during For Record Number execution. Only the fields referred to by For Record Number are sent.

You can also use the OPTIMIZING FNV option with the For Each Record Number statement. If you do so, the information provided in Using the FOR EACH RECORD statement is valid, with this exception: you must specify the Opt FNV option at the end of the statement.

Using the FOR EACH VALUE statement

All forms of the For Each value statement are supported in remote file and scattered group context.

Using the RELEASE statement

The RELEASE ALL RECORDS and RELEASE RECORDS IN or ON statements are performed on the server system, causing any remotely held found sets to be released.

Using the SORT RECORDS statement

The SORT RECORDS statement is supported in remote file and scattered group context. However, the SORT RECORDS k option is ignored. If you use SORT k RECORDS, all the records referred to, not just the first k records, are sorted.

Sort operations for remote file data are executed on each affected server node and the results are merged. Sort keys can include fields that are not defined in all members of a scattered group.

Using LIST functions

List processing functions are supported in remote context. List operations for remote file data are performed on the server node on which the file resides. For scattered groups, a list is created on each node that contains a member of the group.

The following example is commented to show the resulting conversation elements:

IN PARTS AT DETROIT BEGIN CLEAR LIST XYZ (Send CLEAR LIST function to DETROIT) A: FD PTYPE='XYZ' (Send FIND function to DETROIT) B: FR A (Retrieve records) PLACE RECORD ON LIST XYZ (Send PLACE RECORD function to DETROIT) . . .

Note that PLACE RECORDS IN A ON LIST XYZ would have the same effect but requires only one network operation.

Using the PRINT statement

The PRINT *ID statement cannot be used in remote file context. All other forms of the PRINT statement can be used to print field values for remote files, with the exception of Large Object Data stored in Table E. You can print the Large Object Data locator stored in Table B.

Printing preallocated fields with a PAI statement

PAI or PAI INTO normally displays preallocated fields first in its output. In Parallel Query Option/204, however, some update operations store new preallocated field values at the end of the record, which is displayed by PAI.

PQO/204 ships a copy of all of the fields that are referenced in the FOR loop to the client node. If you change or add a preallocated field value, this value will be placed at the end of the buffer on the client that contains the copies of the fields from the server Online where the file actually resides and the original updates have been made.

PAI of this record, for performance reasons, will not ship the fields again, and simply takes the field data from the local buffer, and shows that the preallocated field value is at the end of the record.

In fact, the record on the remote file has been updated properly with the preallocated fields at the beginning of the record.

Fields in a remote file update are transferred to the local node in the non-preallocated format. Some updates to preallocated fields that take place within a FOR loop (for instance, ADD) store new values at the end of the record.

If preallocated fields are not updated within a FOR loop, the output of the PAI statement is the same as in the non-distributed case.

Using retrieval conditions

Except as described below for FILE$ and LOCATION$, retrieval conditions act the same in remote context as they do locally. In scattered groups, retrieval conditions can include fields that are not defined in all members of the group.

The following retrieval conditions are supported in remote context:

FILE$ FIND$ LIST$ LOCATION$ POINT$ SFGE$ SFL$

Using FILE$

The FILE$ condition is valid only in group context. It can accept remote file specifications and remote synonyms. For example, the following FIND results are restricted to values in the STUDENTS file whose location is NYC:

IN GROUP STUDENTS FD FILE$ 'STUDENTS' AT NYC AND SEX = 'F'

Valid FILE$ argument formats for remote files are:

• Literal remote file specifications or file synonyms
• Literal remote file specifications or file synonyms following dummy strings
• The equality symbol (=) to point to the node on which the request is running

Invalid FILE$ argument formats for remote files are:

• %Variables
• Remote file specifications enclosed entirely in quotes ('STUDENTS AT NYC' is not valid)

Using LOCATION$

You can use the LOCATION$ condition to restrict group context FIND results to a particular node. Used like FILE$, LOCATION$ is valid only in group context. The following FIND results are restricted to files in the STUDENTS group whose location is either MA or VT:

IN GROUP STUDENTS FD (LOCATION$ MA OR LOCATION$ VT) AND COLOR = 'BLUE'

The location referred to by LOCATION$ is the location name used in file synonyms and remote file specifications — the symbolic name specified in the DESTINATION parameter of a client DEFINE PROCESS command (described in PQO: Defining a PQO network).

Valid LOCATION$ argument formats are:

• Literal location names
• Literal location names following dummy strings
• The equality symbol (=) to point to the node on which the request is running

LOCATION$ arguments cannot be %variables.

If an optional member of a scattered group is unavailable, no records are found for that file and processing continues.

Using update statements with remote files

With Parallel Query Option/204, you can execute single-node updates only; each Model 204 transaction can update data on only one node.

If the current transaction has updated a node (either local or remote) that is different from the node referred to by another update statement within the transaction, Model 204 displays an error message stating that you violated the single-node update rule. The current transaction is backed out and the request is canceled. This restriction is checked at evaluation time.

An application program must end the current transaction (either commit it or back it out) before the application can update files on a different node (either remote or local).

This section discusses the SOUL update statements that you can use with a remote file or group and includes a discussion of updating records that are not locked.

Updating unlocked record sets

In a typical Parallel Query Option/204 remote update, a client issues a Find statement to retrieve a set of records from a service node file. A client For Each Record statement triggers the transfer of a copy of the record set to the client node. The client application loops through and updates the records on the service node and the client node copy.

If the service node records are not locked (for example, you use FIND WITHOUT LOCKS) during the update processing, other users might make changes on the service node to the records in the copied set. Changes that happen after the set is copied and before the update is finished can introduce inconsistencies between the client copy and the actual server data. Such changes make obsolete the client copy of the record set.

For example, some field-level operations depend on the current state of a record: if there are three occurrences of a field, CHANGE fieldname(6) adds a fourth occurrence. If there are six or more occurrences, the same statement changes the sixth occurrence.

A client issues this CHANGE anticipating six or more occurrences. Before the CHANGE is processed, users on the server delete all but three occurrences. The CHANGE is processed and the service node file ends up with three occurrences unchanged and four occurrences altogether; the client copy has no deletions and a changed sixth occurrence.

If the client user prints the record information after the CHANGE but within the same For Each Record loop, the display shows the client's view of the record. The client does not detect that this view does not match the current server data.

If the print of the record information is after the CHANGE but within a new For Each Record loop, the display is a refreshed view of the actual current server record. The client can detect at this point that the expected result of the CHANGE did not occur.

Though updates like CHANGE lock a record, they alone do not prevent inconsistencies between the client's view of the record and the actual state of the record on the server. For unlocked record processing, you need to use For Record Number.

Note: Always lock a record before updating it. If an unlocked record set or list is being processed, use the For Record Number statement to lock the record, as shown below:

%X = $CURREC FOR RECORD NUMBER %X

For Record Number locks, copies, and sends the record to the client when the For Record Number statement is executed. Using For Record Number In label is not sufficient, as explained in Using the For Record Number statement.

Using ON FIELD CONSTRAINT CONFLICT $functions

If a field constraint violation occurs on a remote node and there is an active ON FIELD CONSTRAINT CONFLICT (ON FCC) unit, clients can issue the $functions that report about the constraint. For more information on the following FCC $functions, refer to SOUL functions:

• $UNQREC
• $UPDFILE
• $UPDFLD
• $UUPDOVAL
• $UPDREC
• $UPDSTAT
• $UPDSTMT
• $UPDVAL

Using ADD, CHANGE, INSERT, and DELETE

The following update statements are supported in remote file and in scattered group context with the limitation explained below:

ADD CHANGE DELETE DELETE EACH DELETE RECORD INSERT

Using the BACKOUT statement

The BACKOUT statement backs out a transaction against data on a remote node if the current transaction is remote. In addition to backing out the transaction on the remote node, BACKOUT processing includes backing out the effects of the transaction on the local copy of the remote data.

A remote transaction is backed out automatically in the same situations in which Model 204 backs out a local transaction.

Using COMMIT and COMMIT RELEASE statements

The COMMIT statement commits a transaction on a remote node if the current transaction is remote.

A remote transaction is committed automatically in the same situations in which Model 204 automatically commits a local transaction.

The COMMIT RELEASE statement commits a transaction on a remote node and releases found sets on all nodes, local and remote.

Using the DELETE RECORDS statement

The DELETE RECORDS statement is supported in remote file context and in scattered group context. The functionality of this statement depends on the setting of the PQOOPT parameter, which allows DELETE RECORDS to perform multiple-node updates.

If PQOOPT is not set for multi-node updates, DELETE RECORDS can be used in scattered group context only if either of the following conditions is true:

• All files in the group reside on the same remote node.
• The group found set to which either statement applies is restricted to a single node — the found set was created by:

  IN GROUP groupname MEMBER %var FIND ...

  where:

  %var specifies a particular file (%var is not an asterisk (*)).

Using FILE RECORDS

The FILE RECORDS statement is supported in remote file context and in scattered group context. The functionality of this statement depends on the setting of the PQOOPT parameter, which allows FILE RECORDS to perform multiple-node updates.

If PQOOPT is not set for multi-node updates, FILE RECORDS can be used in scattered group context only if all group members reside on the same node.

If PQOOPT is set for multiple-node updates and an optional member of a scattered group is unavailable, it is skipped. The records are not filed on that node and the old index entries for the targeted field name = value pair are not deleted, but the statement executes (completes) successfully.

Using STORE RECORD

All forms of the STORE RECORD statement are supported in remote file and scattered group context.

Field-value pairs specified by statements that are between STORE RECORD and END STORE are sent to and stored on the remote node.

After a record is stored on a remote node, you can access it by requests using either Find or For Record Number statements.

Using $CURREC, you can extract the record number of the record you most recently stored.

The file in a scattered group in which STORE RECORD stores records cannot be resolved until evaluation time, so the statement might have to be compiled on multiple nodes. For storage files pointed to by the following IN clauses, STORE RECORD is compiled on all nodes in the group; at evaluation time, it is executed on one node only.

• IN GROUP groupname MEMBER, in temporary or permanent scattered group context
• IN $CURFILE, in temporary or permanent scattered group context
• IN GROUP groupname (where the group update file is the implied storage file), in temporary scattered group context

Using UPDATE RECORD

The UPDATE RECORD statement improves performance when you are executing a set of field-level update operations against the current record. UPDATE RECORD is allowed in remote and non-remote contexts.

Syntax

The UPDATE RECORD syntax is:

UPDATE RECORD field-level-operation-1 field-level-operation-2 . . . field-level-operation-N END UPDATE

where a field-level operation is one of the following:

ADD fieldname = value CHANGE fieldname [(subscript)] [= value] TO newvalue DELETE fieldname [(subscript)] [= value] INSERT fieldname [(subscript)] = value

All field-level operations between UPDATE RECORD and END UPDATE are packaged and sent to the remote node in one call. Without UPDATE RECORD, the same set of operations require one call per operation.

If there are no field-level operations between UPDATE RECORD and END UPDATE, Model 204 ignores the UPDATE RECORD statement.

Note: DELETE EACH fieldname is not allowed in an UPDATE RECORD statement.

Usage

Model 204 handles errors that occur during UPDATE RECORD the same as those that occur during STORE RECORD. For more information about STORE RECORD error handling, see Storing values in preallocated fields.

If a field constraint violation occurs, the entire UPDATE RECORD statement is backed out. The $UPDSTMT function returns the type of statement that caused the conflict: ADD, CHANGE, or INSERT.

If an ON unit is invoked during the execution of UPDATE RECORD and the ON unit is exited with a BYPASS statement, the request execution continues with the statement that follows the END UPDATE statement.

Using $functions with remote files

Except for the following functions, all file-related $functions that applied to local files or groups apply to remote files and scattered groups as well.

$LSTPROC $RDPROC $View (works only for certain remote file parameters)

$View is valid in remote file context with the following file parameters:

ASTRPPG FITRANS ATRPG HASHKEY CURLOC LOCATION CURFILE OPENCTL FICREATE RECSCTY FILEORG SORTKEY

If $View is issued in remote file context with any other file parameter, Model 204 processes the request but the result of $View is unreliable.

If $LSTPROC or $RDPROC is coded in a SOUL statement that is in remote context, Model 204 displays an error message at evaluation time.

This section describes $functions that are new or whose use in Parallel Query Option/204 requires comment.

Using $CURFILE, $RLCFILE, $UPDATE, and $UPDFILE

The output of the $CURFILE, $RLCFILE, $UPDATE, and $UPDFILE functions issued in remote context is the remote file specification (filename At location). Each of these functions returns the string:

filename At location

Where:

location is a name for the node where the remote file resides.

You can use $SUBSTR to extract the name or the location.

Using $FDEF and $LSTFLD functions

You can use these $functions in local or remote file context. They recognize the following keywords in the file-name argument string: FILE, AT. You also can use a file synonym.

Using $ITSOPEN function

The $ITSOPEN function indicates whether the current file or group is open. Its format is:

$ITSOPEN(name)

where name is a %variable or literal character string representing a file name, file synonym, or group name. This argument string can include the keywords AT, FILE, GROUP, PERM, or TEMP.

$ITSOPEN can be issued in any context. It returns 1 if the file or group is open; it returns 0 if the file or group is closed.

Using $ITSREMOTE function

The $ITSREMOTE function indicates whether the current file or group is remote or scattered. Its format is:

$ITSREMOTE(name)

where name is a %variable or literal character string representing a file name, file synonym, or group name. This argument string can include the keywords AT, FILE, GROUP, PERM, or TEMP.

$ITSREMOTE can be issued in any context. It returns 1 if the context is remote file or scattered group; it returns 0 if the context is local.

Using file and group availability $functions

The $functions in Using file and group availability $functions and Using file and group availability $functions provide information about file and group availability. The $functions in Using file and group availability $functions report on scattered group members. The $functions in Using file and group availability $functions are for files or groups but are valid only in an ON MISSING MEMBER or ON MISSING FILE unit.

An example in which these $functions are used is shown on Using file and group availability $functions.

The index parameter in some of the $functions in Using file and group availability $functions and Using file and group availability $functions is assigned internally by Model 204 when those $functions are issued. Unavailable files are assigned index numbers in the order in which the files are listed in the CREATE GROUP command.

For example, if unavailable fileA appears earlier in the CREATE GROUP list of files than unavailable fileB, fileA is assigned a lower index number than fileB. If fileA appears the earliest in the CREATE GROUP list, it always has the index value 1 when it is unavailable. And when fileA is available, another file has 1.

Scattered group $functions

The $functions in Using file and group availability $functions are supported only in group context. If you do not use them in group context, Model 204 cancels the request which calls the $function.

You can ensure the group context by specifying a group name (groupname in syntax in Using file and group availability $functions) as an argument of the $function. If you do not specify a group name, the context of the current statement is used.

The index parameter is an integer from one to the value of $GRNMISS. If index is less than one or greater than $GRNMISS, Model 204 cancels the request.

$functions for groups

$function syntax	Returns...
$GRMLOC(index [,groupname])	Location of the missing (unavailable) group member identified by the index parameter.
$GRMNAME(index [,groupname])	Name of the missing (unavailable) group member represented by the index parameter.
$GRNLEFT[(groupname)]	Number of remaining available optional group members that can fail before the MAXFAIL parameter value (CREATE GROUP command) is exceeded. (MAXFAIL specifies the maximum number of optional members that might be unavailable.)
$GRNMISS[(groupname)]	Number of optional group members that are unavailable to the request.

ON MISSING unit $functions

The $functions in Using file and group availability $functions are valid only in an ON MISSING MEMBER or ON MISSING FILE unit. Any other use of these functions is treated as a compilation error.

The index parameter is an integer from one to the value of $MISNUM. If index is less than one or greater than $MISNUM, Model 204 cancels the request.

$functions for ON MISSING units

$function	Returns...
$MisGrup	String containing the name of the group, if the error that invoked the ON unit occurred in group context. Otherwise, it returns the null string.
$MisLoc(index)	String containing the location of the unavailable file indicated by the index parameter.
$MisName(index)	Name of the unavailable file identified by the index parameter.
$MisNum	Number of files in the group that are newly unavailable (that have become unavailable since the last time the ON MISSING unit was invoked).
$MisStmt	String containing the type of SOUL statement that failed, for example, 'DELETE ALL RECORDS'.

ON MISSING FILE unit example

The following ON MISSING FILE unit example uses the $functions in Using file and group availability $functions and Using file and group availability $functions. The example works for an ON MISSING MEMBER unit as well.

ON MISSING FILE %C IS STRING LEN 255 %D IS STRING LEN 255 %C = $MisGrup IF %C = '' THEN * This is file context because $MisGrup returned nulls * %C = 'MISSING FILE ' WITH $MISNAME(1) WITH ' AT ' WITH $MISLOC(1) PRINT %C ELSE %GROUPNAME = %C %C = 'MISSING GROUP ' WITH %C WITH ' FILES FOLLOW: ' FOR %JUNK FROM 1 TO $MISNUM BY 1 %C = %C WITH $MISNAME(%JUNK) WITH ' AT ' WITH $MISLOC(%JUNK) END FOR %C = %C WITH ' ON STATEMENT ' WITH $MISSTMT PRINT %C %D = 'COMPLETE LIST OF MISSING FILES FOR' WITH $MisGrup WITH ': ' FOR %INDEX FROM 1 TO $GRNMISS BY 1 %D = %D WITH $GRMNAME(%INDEX,%GROUPNAME) WITH ' AT ' %D = %D WITH $GRMLOC(%INDEX,%GROUPNAME) END FOR PRINT %D END IF BYPASS END ON