PQO: Remote files and scattered groups

Overview

With Parallel Query Option/204, the user can access files that are located on remote Model 204 systems. Special guidelines apply when working with files in remote context.

This topic describes the specific commands, statements, and functions that are available to the Model 204 application programmer, and the rules that apply when referencing files in remote context.

Unless otherwise specified, use these commands, statements, and functions in PQO contexts the same as in typical Model 204 contexts.

Specifying a remote file

You can explicitly reference a remote file in a command or statement using:

Remote file specification
File synonym

You can also implicitly reference a remote file by using the name of a scattered group of which the file is a member. This section describes explicit remote file specification.

Using a remote file specification

A command or statement that references a file by name and includes an AT clause is a remote file specification. The AT clause references the node to which the file belongs (where the file was created). This node can be local or remote.

Remote file specification is valid with all the commands and statements that reference local files except for the DEFINE DATASET command.

Syntax

Remote file specification has the following syntax:

[command | statement] filename AT [location | = ]

where:

filename specifies the actual name of a Model 204 file on the node where the file resides.
location is the symbolic name (as many as eight characters) that refers to the location of the node on which the file resides.
An equal sign without quotation marks (=) specifies a client node, meaning the file is local.

AT location matches DEFINE PROCESS destination

The remote file specification location name must match a symbolic destination name specified in the DESTINATION parameter of a local DEFINE PROCESS command for CCAD2C.

For example, if the definition of a CCAD2C process includes:

DESTINATION=(PGRP1,BOSTON)

the following OPEN FILE command using the AT clause is valid:

OPEN VEHICLES AT BOSTON

where VEHICLES is the name of a file residing at the remote location that is identified by the symbolic name BOSTON. The DESTINATION parameter is discussed in Client process DESTINATION parameter.

AT location not required to match CCAIN parameter LOCATION

The remote file specification location name need not match the value of the server node CCAIN parameter LOCATION. See Setting the LOCATION parameter.

Using a dummy string in the AT clause

The location name in the AT clause can be coded as a dummy string inside a SOUL procedure. At run time, the user can enter an equal sign (=) to specify that the location of the named file is the node on which the command or statement is currently issued, the local node.

Using a dummy string allows the application programmer to code a single file reference in the procedure, and to access different versions of the same file (having the same name), either locally or remotely, at run time. See Dummy strings in procedures for a description of dummy strings in SOUL procedures.

Using a file synonym

Once a DEFINE FILE command has been issued for a particular remote file, a user can refer to the file using the synonym name. The synonym is the symbolic name assigned to the file and is available to local users. See Defining file synonyms.

Even though a file synonym has been defined, you still can use the full remote file specification, as described in Specifying a remote file. When using a file synonym in a file command, the syntax of the command for a remote file is the same as for local files. For example, the following DEFINE FILE command specifies the synonym CARS for the file VEHICLES:

DEFINE FILE CARS WITH SCOPE=SYSTEM FILENAME=VEHICLES LOCATION=BOSTON

You can specify an OPEN FILE command, using the file synonym, as:

OPEN CARS

Using a file synonym provides name and location transparency in SOUL applications. You can reference a file using only a locally assigned name. The system manager maintains the file definition in keeping with any changes in the network definition such as the location specification. Changes to the network definition do not require changes to the application code.

Using Model 204 file and group commands

A remote file or group specification, using either the AT clause or a file synonym, is syntactically valid in most of the same commands that are used to refer to local files or groups. The Model 204 commands you can use to refer to a remote file are shown in the following table.

Commands for remote files or scattered groups
Command	Type of user
CLOSE (for a file or group)	Any user
CREATE PERM GROUP	System manager
CREATE TEMP GROUP	Any user
DEFAULT	Any user
DEFINE FILE	User 0 or system manager
DELETE PERM GROUP	System manager
DELETE TEMP GROUP	Any user
DISPLAY (for a field, group, or record)	Any user
MONITOR SUBSYSTEM	Any user
OPEN FILE	Any user
OPEN GROUP	Any user
START (for a file or group)	System administrator
STATUS	Any user
STOP (for a file or group)	System administrator
VIEW	Any user

These are the only file or group commands that support remote file specification.

Supported in PQO but not included in the previous table are BUMP, LOGWHO, MONITOR, the network control and definition commands, and the subsystem control commands. See #Restricted commands, $functions, and DML statements for a list of unsupported commands. Most of the commands in the previous table are described in PQO: Managing the PQO network and PQO: Managing files and groups. The following commands are described in this section:

OPEN FILE OPEN GROUP CLOSE (for a file or group) DEFAULT DELETE GROUP

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. See Opening a scattered group for a discussion.

Successful attempts to open

When you first successfully issue a command to open a remote file at a given node, a conversation is initiated with that server and a service thread is activated to support the conversation. If a conversation is already established with that remote node and is available, the conversation continues and is used for the request to open the file.

If a conversation is available, you are prompted to enter a password if the file is private or semipublic. If the OPENCTL setting for the file allows remote access, any password gains access to a semipublic file. Private files require the correct password. Application subsystem files are protected by APSY security. See Allowing access to remote files for a description of the OPENCTL parameter.

When a remote file is opened, Model 204 displays a confirmation message with the file's name (nonsynonym) and location, stating whether updates are allowed.

Unsuccessful attempts to open

If a conversation cannot be allocated, Model 204 displays the error message:

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

If an OPEN FILE or OPENC FILE statement issued from within a SOUL request fails, the $STATUS return codes indicate the error condition. A $STATUS value of 2 is returned for an open failure. For more information about $STATUS return codes, see Files, groups, and reference context.

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

For information, see 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 nonscattered groups. Password requirements and privileges for member files are also the same for scattered and nonscattered 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 (nonsynonym) and location, stating whether updates are allowed.

Unsuccessful attempts to open

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.

Using an OPEN GROUP statement

If an OPEN GROUP command 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.

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

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:

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.

Referencing remote files in a SOUL request

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

SOUL example

The following example shows an excerpt from a SOUL procedure that is submitted locally and 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:

You must define the PQO network on both the client and server systems.
Model 204 system manager (or User 0) must successfully issue the OPEN LINK command on both the client and server systems, so that the connection for the PQO 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 SOUL 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, a page at a time.

SOUL 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 Defining file synonyms and Specifying a remote file for additional information.

Request continuation is not supported

Remote file reference is not supported in a SOUL request continuation. The SOUL MORE and END MORE statements are not supported if the continued request refers to a remote file.

Errors during compilation and evaluation

Compilation and evaluation errors in PQO applications are discussed in the following sections. Both sections discuss how Model 204 handles non communications errors and communications errors when a remote file is referenced.

Compile time error handling

If a non communications 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:

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:

In this context...	Model 204 takes this 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 non-communications 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 units

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 ON MISSING FILE unit example.

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:

Operation in group context fails against a remote optional member of the group.
Member was not previously unavailable to the request.
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:

Group member is made unavailable to the group, both during and after request execution.
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, CONTINUE, BYPASS, or JUMP TO statement.

ON MISSING MEMBER units cannot be nested.

PQO supports use of a CLEAR statement for clearing of an ON unit for ON MISSING MEMBER.

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

If a communications failure occurs while receiving a new portion of records from a remote node in a FOR EACH RECORD loop in group context, you can use one of these statements to tell PQO how to proceed:

CONTINUE
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.
BYPASS
Exits the FOR loop, bypassing the remaining group files against which the FOR loop would have run, and skips to the next instruction after END FOR.

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:

Operation in single file context fails against a remote file.
Operation has failed against a remote file when there was no specific file or group context. This includes the following SOUL statements:
RELEASE ALL RECORDS

BACKOUT
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), or all members of the group are now missing.

When ON MISSING FILE is invoked, these consequences follow:

File or group is made unavailable to the request.
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.

PQO supports use of the CLEAR statement for clearing of an ON unit for ON MISSING FILE.

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.

The special handling for BYPASS and CONTINUE in a FOR EACH RECORD loop in group context described above for communication failures during ON MISSING MEMBER does not apply to ON MISSING FILE units, because the entire group is made unavailable.

DML statements in PQO

The SOUL statements and conditions in the following table comprise the PQO data manipulation language (DML).

Only these statements and conditions can be used in reference to a remote file or group.

Following the table are discussions of the use of these statements and conditions in PQO, maintaining the classification (retrieval or update) listed in the table.

PQO DML statements and conditions
Retrieval statements	Retrieval conditions	Update statements
CLEAR LIST	FIND$	ADD
COMMIT RELEASE	FILE$	BACKOUT
COUNT OCCURRENCES OF	LIST$	CHANGE TO
COUNT RECORDS	LOCATION$	COMMIT
FIND RECORDS	POINT$	DELETE
FIND ALL RECORDS	SFGE$	DELETE EACH
FIND ALL VALUES
FIND AND PRINT COUNT	SFL$	DELETE RECORD
FOR EACH OCCURRENCE		DELETE RECORDS
FOR EACH RECORD		FILE RECORDS
FOR EACH VALUE
FOR `k` RECORDS		INSERT
FOR `k` VALUES
FOR RECORD NUMBER		STORE RECORD
NOTE `fieldname`		UPDATE RECORD
OPEN
OPENC
PLACE RECORD ON LIST
PLACE RECORDS ON LIST
PRINT ALL INFORMATION
RELEASE ALL RECORDS
RELEASE RECORDS
REMOVE RECORD FROM LIST
REMOVE RECORDS FROM LIST
SORT RECORD KEYS
SORT RECORDS
SORT VALUES

Using IN clauses

A remote file specification (using either the AT clause or a file synonym) or a scattered group is syntactically valid in the IN FILE or IN GROUP clause of supported DML statements in remote context.

Also, you can use the following IN clause variations to refer to a remote file if you are in scattered group context:

IN GROUP groupname MEMBER IN $CURFILE IN $UPDATE

Using field names in expressions

Fields in remote context can be used in the same ways as fields in local context including the VALUE IN phrase, which refers to a label on a FOR EACH RECORD IN ORDER statement.

Handling record locking conflicts

If a client request cannot complete because of a record-locking conflict on the server system, the server automatically tries again to lock the record or set of records. The server tries again until it succeeds or until it has tried as many times as the value of the client thread ENQRETRY parameter. The value of the ENQRETRY parameter that is specified on the server thread has no effect on the number of retries.

If ENQRETRY attempts to lock a record or set of records do not succeed, the server notifies the client about the conflict. If an ON RECORD LOCKING or ON FIND CONFLICT unit is active, the unit is invoked. Otherwise, the client receives a message that the locking failed, followed by a prompt asking if the client wants to try again.

If the client enters N, the request is canceled. If the client enters Y, the server repeats the locking attempt cycle, making as many as ENQRETRY attempts before prompting again.

Using PQO retrieval statements

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 LOCATION$ for information about restricting group context FIND statements.

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 use the OPTIMIZING FNV option (OPTIMIZING can be abbreviated as OPT) to prevent FOR loop retrievals with field name variables from triggering the retrieval of all fields and all occurrences.

To use the OPTIMIZING FNV option with the FOR EACH RECORD statement, you must specify OPT FNV in one of the following places:

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

When you use OPTIMIZING FNV, only the initial value of the field name 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.

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 PQO, 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 the 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.

OPTIMIZING FNV option

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 OPTIMIZING FNV option at the end of the FOR RECORD NUMBER statement.

Using the FOR EACH VALUE statement

All forms of the FOR EACH VALUE statement are supported in remote file and scattered group context.

The FOR EACH VALUE statement initiates a loop that is executed once for each unique value of the specified field. There are several variations of the FOR EACH VALUE statement, as described in Value loops.

You can use the FOR EACH VALUE statement to:

Sort the retrieved values, using the IN ORDER clause
Specify a range of values to be retrieved, using FROM value1 TO value2 clauses
Specify a pattern to be used to retrieve values, using the LIKE pattern clause
Process a sample of values, using the k clause

Using RELEASE

The RELEASE ALL RECORDS and RELEASE RECORDS IN/ON statements are performed on the server system, releasing any remotely held found sets.

Using the SORT RECORDS statement

The SORT RECORDS statement is supported in remote file and scattered group context.

Note 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 segment of SOUL code has comments 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: PLACE RECORDS IN A ON LIST XYZ has 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. You can print the locator information stored in Table B, but not the actual data stored in Table E.

Printing preallocated fields with a PAI statement

PAI or PAI INTO normally displays preallocated fields first in its output. In PQO, however, some update operations store new preallocated field values at the end of the record. This placement at the end of the record is displayed by PAI.

Fields in a remote file update are transferred to the local node in the nonpreallocated 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 nondistributed 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 is 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
Equal sign (=) 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 (for example, 'STUDENTS AT NYC' is not valid)

Using LOCATION$

You can use the LOCATION$ condition to restrict group context FIND statements to a particular node. Used like FILE$, LOCATION$ is valid only in group context.

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 Using the DEFINE PROCESS command and AT location matches DEFINE PROCESS destination).

Valid LOCATION$ argument formats are:

Literal location names
Literal location names following dummy strings
Equal sign (=) 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 PQO update statements

In PQO, you typically execute single-node updates; you update data on only one node per Model 204 transaction. This is the default.

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.

Limitations to updating remote files

There is no support in Parallel Query Option for the date/time stamp feature. If you attempt a remote open of a data/time stamp file (FOPT=X'10), the following message is issued:
M204.1977: %F MAY NOT BE ACCESSED REMOTELY
You cannot open a file remotely and update fields defined with the BLOB or CLOB file attribute.

PQOOPT and multiple-node updates

For the SOUL DELETE RECORDS and FILE RECORDS statements only, you can enable multiple-node updates with the Model 204 parameter PQOOPT.

For more information about multiple-node updates, see Using DELETE RECORDS and Using FILE RECORD.

Updating unlocked record sets

In a typical PQO 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 can 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 might 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.

Lock a record before updating it

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

%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 example, $UPDSTAT, $UPDOVAL).

For more information about ON FCC $functions, see Using ON FIELD CONSTRAINT CONFLICT $functions.

Using ADD, CHANGE, INSERT, and DELETE statements

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

ADD CHANGE DELETE DELETE EACH DELETE RECORD INSERT

Using BACKOUT

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

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 DELETE RECORDS

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.
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 and %var is not an asterisk (*).

Using FILE RECORD

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 processing to perform multiple-node updates.

If PQOOPT is not set for multi-node updates, a FILE RECORDS statement 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 processes successfully.

Using INSERT

The INSERT statement is not supported for Large Object fields.

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 statements 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 processing stores records might not 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 field-level-operation is one of the following:

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

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

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

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

Usage

Model 204 handles errors that occur during UPDATE RECORD processing the same as those that occur during STORE RECORD processing. For more information about STORE RECORD error handling, see Data maintenance.

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 UPDATE RECORD processing 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

Except for the following functions, all file-related $functions that applied to local files or groups now 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 PQO 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.

You can use $UPDLOC to determine the location of a file that is being updated. See Using $UPDLOC.

Using $FDEF and $LSTFLD

You can use the $FDEF and $LSTFLD functions in local or remote file context. They recognize the FILE and AT keywords in the filename argument string. You also can use a file synonym.

Using $ITSOPEN

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

Syntax

The $ITSOPEN syntax 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 is open; it returns 0 if the file is closed.

Using $ITSREMOTE

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

Syntax

The $ITSREMOTE syntax 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 $UPDLOC

Use the $UPDLOC function to determine the node location where an UPDATE UNIT is in progress. If the file being updated is local, $UPDLOC returns the word LOCAL. If the file being updated is remote, $UPDLOC returns an identifier for the node location (in the form AT location). The $UPDLOC function takes no arguments.

Using file and group availability $functions

The $functions in $functions for groups and $functions for ON MISSING units provide information about file and group availability. The $functions in $functions for groups report on scattered group members. The $functions in $functions for ON MISSING units 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 in ON MISSING FILE unit example.

The index parameter in some of the $functions in $functions for groups and $functions for ON MISSING units 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 will have 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 will have 1.

Scattered group $functions

You must use the $functions in the following table in group context or Model 204 cancels the request within which you issued the $function.

You can ensure the group context by specifying a group name (groupname in syntax in the following table) 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	Result
$GRNLEFT [ (`groupname`) ]	Returns the 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 can be unavailable.)
$GRNMISS [ (`groupname`) ]	Returns the number of optional group members that are unavailable to the request.
$GRMNAME (`index` [,`groupname`] )	Returns the name of the missing (unavailable) group member represented by the `index` parameter.
$GRMLOC (`index` [,`groupname`] )	Returns the location of the missing (unavailable) group member identified by the `index` parameter.

ON MISSING unit $functions

The $functions in the following table 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.
$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).
$MISNAME (`index`)	Name of the unavailable file identified by the `index` parameter.
$MISLOC (`index`)	String containing the location of the unavailable file indicated by the `index` parameter.
$MISSTMT	String containing the type of SOUL statement that failed, for example, 'DELETE ALL RECORDS'.

ON MISSING FILE unit example

This ON MISSING FILE unit example uses the $functions in the $functions for groups table and $functions for ON MISSING units table. 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

Using the Host Language Interface

A Host Language program that issues an IFDIAL call (IFREAD or IFWRITE) can access remote data.

Any functionality that is supported for SOUL requests, as described in this topic, is supported for IFDIAL calls. There are no additional limitations or functional differences between local and remote file access for IFDIAL calls.

Use of IFSTRT calls is not supported

A Host Language program that issues an IFSTRT call (IFFIND or IFGET) cannot access remote data.

An IFOPEN call issued with a remote file specification causes Model 204 to perform the following actions:

Set the completion code to 260.
Write an error message to the client system audit trail stating that IFOPEN remote access is not allowed.

Restricted cmmands, $functions, and DML statements

This section lists the Model 204 commands and $functions that are not supported in remote context for PQO processing.

Restricted Model 204 commands

Some of the Model 204 commands that specify a file name, or that operate on a default file or on a file specified in an IN clause, are not supported in remote context for PQO processing.

The following commands cannot be used in reference to a remote file. See Commands for remote files or scattered groups for a description of the commands that can be used to reference files in remote context:

ASSIGN (specifying a procedure alias) BROADCAST FILE CREATE FILE DEASSIGN DECREASE DEFINE FIELD DELETE PROCEDURE DESECURE DESECURE PROCEDURE DISPLAY FILE DISPLAY LIST DISPLAY PROCEDURE DUMP EDIT ENQCTL FILELOAD FLOD INCLUDE INCREASE INITIALIZE PROCEDURE REDEFINE FIELD REGENERATE RENAME FIELD RENAME PROCEDURE REORGANIZE RESET (file parameters) RESTORE SECURE SECURE PROCEDURE TABLEB TABLEC TRANSFORM Z

Restricted SOUL $functions

The following SOUL $functions cannot be used in reference to a remote file:

$LSTPROC $RDPROC

If either of these $functions is used in reference to a remote file, Model 204 displays an error message.

See Using $functions for a description of the $functions whose functionality or usage is different for PQO.