PURPOSE: The RELATE statements are used to declare DS's for all data servers and file systems, SD's, DI's, report files, GS's, and DBL’s for use in the PM. They also associate DS's and DBL's with the designators names and report files with the numbers by which they will be identified throughout the PM. When the PM is invoked, all DS’s defined by RELATE statements are initialized for the kind of processing specified in the RELATE statement. Each DS, DI, GS, file, and DBL that will be used any place in the PM must be identified in a RELATE statement. The maximum number of auxiliary DS's or DI’s that can be declared in a PM is 100. The maximum number of reports is 10 and the maximum GS's is 10.
RELATE statements can only occur in the CONTROL section of the PM.
There are five forms of the RELATE statement:
For relating master DS, SD, ID, or DI and transaction DS or SD.
For relating auxiliary DS’s, DI’s SD's and ID's.
For relating reports to a file or the terminal.
For relating GS areas.
For relating DBL’s.
Forms 1 and 2 have variations with the use of Simultaneous Update.
FORM 1a: (RELATE) Master/Transaction for non Concurrent Queue Environment
RELATE {DS; SD; DI; ID} name {WITH; TO; AS} {MASTER; TRANSACTION}
[FOR {INPUT; UPDATE}]
FORM 1b: (RELATE) Master / Transaction - Concurrent Queue Environment
RELATE {DS; SD; DI; ID} name {WITH; TO; AS} {MASTER; TRANSACTION}
[FOR {INPUT; UPDATE}]
[ALLOWING /OTHERS TO/{WAIT; INPUT; UPDATE}]
[DS /WAIT/ MESSAGE /IS/ {DISABLED; ENABLED}]
[RECORD /WAIT/ MESSAGE /IS/ {DISABLED; ENABLED}]
[WAIT {n /SECONDS/; FOREVER} /FOR/ DS]
[WAIT {n /SECONDS/; FOREVER} /FOR/ RECORD]
The optional clauses of the RELATE statement control aspects of the Concurrent Queue environment. The FOR clause specifies precisely which operations the PM will perform on the DS. Similarly, the ALLOWING clause specifies precisely which operations other users will be allowed to perform on the DS while this PM controls it. The ALLOWING clause activates the Concurrent Queued environment, which causes record-level queuing so that it is possible to allow multiple-user updating. When the ALLOWING clause specifies the option OTHERS TO WAIT, it activates the Exclusive Queued environment meaning no other users can access the data set while it is being used by this PM.
The other four clauses described are all default override clauses. They are used to specify how long a PM should wait for a busy data set or record within a data set and to control what is displayed on the screen while the PM waits.
|
name |
Object name for the DS, SD, DI or ID. DS and SD are related to the current master or transaction. A DI is used to access a DS. ID is related to the current master. The current master is always the last data set specified in the USE DS command. The transaction data set is specified in one of the join commands which invokes the PM. To specify a DS, DI, ID or SD in another DBL, use the IN DBL clause. |
|
WITH, TO, AS |
are synonymous - any of the three can be used. |
|
MASTER |
specifies the master DS, SD, or DI. When this Process Module (PM) is called by one of the Data Manipulation commands, there must be a RELATE statement in the PM for the master DS. Use either the SD, DS, or DI name, but it must be that of the current DS. |
|
TRANSACTION |
specifies the transaction DS or SD. When using a Join command (one that uses both a master DS and a transaction DS), the transaction DS or its SD must also be related. A DI cannot be related for the transaction DS. |
|
FOR operation |
specifies the operations that this PM will perform on the related DS. The operations are: |
|
INPUT |
tells ACCENT R to use the set for read only (no changes or additions can be made to the DS). This is the default if no FOR option is stated. |
|
UPDATE |
tells ACCENT R that statements in the PM will update records, create new records, or delete records. This option must be used if the PM is to contain READY and CREATE statements that affect the DS being related. Notice that the operations given in the FOR clause correspond to the statements that will be used later in the PM to manipulate records in the related DS. The operations must be listed in the FOR clause in the order shown above. |
|
ALLOWING clause |
specifies what types of access other jobs may have to the DS while it is used by the PM. For example, if a DS is related with ALLOWING INPUT, only those jobs immediately following it in the queue that request INPUT can access the DS concurrently. Others must wait in the queue for their turn. When the ALLOWING clause specifies any operation, it establishes the Concurrent Queued environment, in which queuing occurs for both DS access and record access. The ALLOWING clause is optional. When there is no ALLOWING clause, the access environment uses the default environment. ALLOWING OTHERS TO WAIT specifies exclusive access to the DS. This clause sets up the Exclusive Queued environment. This PM will only get access to the DS when all previous users in the queue have released the DS. During the execution of this PM, no succeeding user may concurrently access the same DS. ALLOWING OTHERS TO INPUT or UPDATE activates the Concurrent Queued environment. It establishes record-level queuing, as well as DS level queuing. The most useful combinations of FOR and ALLOWING clauses are listed in Table 13-19. Each entry in the list also shows which environment is created by the given ALLOWING clause. |
|
[DS /WAIT/ MESSAGE /IS/ \\{DISABLED;ENABLED}] |
is used to control the printing of a message whenever ACCENT R waits for a busy DS. The message is stored in the system field @DS_MESSAGE and is printed every 30 seconds until access is granted or until @DS_WAIT seconds has elapsed. The default message is “Waiting for {N} in use by PID {H} user {S},” where N is the DS name, H is the process number currently using the DS, and S is the name of that user. (If more than one user has access, the one named is chosen at random.) The message may be changed by changing the system field @DS_MESSAGE. The default is ENABLED. There is no need for this clause if ENABLED is the state you want. |
|
[RECORD /WAIT/ MESSAGE/IS/\\ {DISABLED;ENABLED}] |
is used to control the printing of a message whenever ACCENT R waits for a busy record. The message is stored in the system field @RECORD_MESSAGE and is printed every 30 seconds until access is granted or until @RECORD_WAIT seconds elapse. The default message is “Waiting for record in {N} in use by PID {H} user {S},” where N, H, S are as described above. The message may be changed by modifying the system field @RECORD_MESSAGE. The default is ENABLED. |
|
[WAIT {n /SECONDS/; FOREVER} /FOR/ DS] |
specifies the maximum number of seconds to wait for a queued DS. This clause overrides the value stored in the system field @DS_WAIT. The default is 300 seconds. The job aborts when the wait period exceeds @DS_WAIT seconds or the value given here. You can also just store a value into @DS_WAIT. |
|
[WAIT{n/SECONDS/; FOREVER} /FOR/RECORD] |
specifies the maximum number of seconds to wait for a busy record. This clause overrides the value stored in the system field @RECORD_WAIT. The default is 300 seconds. When the waiting period exceeds @RECORD_WAIT seconds or the value specified here, the system field @AUX is set to “BUSY”, the executing statement fails, and the PM continues. You can also just store a value into @RECORD_WAIT. If the wait time is to be different for each RELATEd DS set, then use this clause. |
|
For |
Allowing |
Environment |
Record Queued |
|
INPUT |
UPDATE |
Concurrent Queued |
YES |
|
INPUT |
INPUT |
Concurrent Queued |
YES |
|
UPDATE |
INPUT |
Concurrent Queued |
YES |
|
UPDATE |
UPDATE |
Concurrent Queued |
YES |
|
INPUT |
WAIT |
Exclusive Queued |
NO |
|
UPDATE |
WAIT |
Exclusive Queued |
NO |
|
CREATE |
|
Default - no DS queue |
NO |
Table 13-19 FOR, ALLOW Clause Combinations
The command from which a PM is called determines the mode in which the master and transaction DS’s are related. Table 13-20 shows the mode for each command.
|
Command |
Data Set |
for Clause |
|
ALTER |
master |
must be UPDATE |
|
CHANGE |
master |
must be UPDATE |
|
DELETE |
master |
must be UPDATE |
|
ENTER |
master |
must be UPDATE |
|
EXTRACT |
master |
must be INPUT |
|
LOAD |
master |
must be UPDATE |
|
MERGE |
master transaction |
must be INPUT must be INPUT |
|
PURGE |
master transaction |
must be UPDATE either UPDATE or INPUT |
|
REPORT |
master |
must be INPUT |
|
SELECT |
master transaction |
must be INPUT either UPDATE or INPUT |
|
SORT |
master |
must be INPUT |
|
UPDATE |
master transaction |
must be UPDATE either UPDATE or INPUT |
Table 13-20 RELATE Mode Required by Command
NOTES: The option of naming the SD rather than the DS in the RELATE statement is useful if there are several DS’s that have the same SD. It is possible to use the same PM on any of those DS’s. The PM uses the declared DS as master and the DS named in the clause of the command as the transaction. The DS’s must of course match the related SD’s.
If a DI is related, it must be declared with the USE DI command or the DI clause of the USE DS command before the PM is executed. The domain is named with the USE DOMAIN clause of the command that calls the PM.
SEE ALSO: GET Statement, USE Command, IN DBL Clause, System Fields, Simultaneous Update
FORM 2a: (RELATE) Auxiliary DS’s or DI’s
RELATE {DS; SD; DI; ID} name {WITH; TO AS} designator [ON \\fields\\] [FOR
{INPUT; UPDATE; CREATE; CREATE APPENDING}] [DEFER OPEN]
FORM 2b: (RELATE) Auxiliary DS’s or DI’s - Concurrent Queue Environment
RELATE {DS; SD; DI; ID} name {WITH; TO AS} designator [ON \\field\\] [FOR
operation] [ALLOWING /OTHERS TO/ {WAIT; {INPUT; UPDATE}}] [DS /WAIT/
MESSAGE /IS/ {DISABLED; ENABLED} [RECORD /WAIT/ MESSAGE /IS/
{DISABLED; ENABLED} ] [WAIT {n /SECONDS/; FOREVER} /FOR/ DS] [WAIT
{n /SECONDS/; FOREVER} /FOR/ RECORD]
|
designator |
is the name by which the DS will be identified in statements in the PM. The designator must begin with an alpha character, can contain alpha characters, numbers, underscores, and periods, and can be up to 40 characters long. |
|
[ON\\field\\] |
is specified if the records are to be accessed using the MATCH ON option of any GET statement. If this option is used, the auxiliary DS must already be sorted on the named fields in the same order. This clause cannot be used if a DI is related or for a DS having multiple record types. |
|
INPUT |
declares the auxiliary DS for reading only. This is the default option if no FOR clause is specified. |
|
CREATE |
declares the auxiliary DS available for accepting newly created records. Any existing records will be cleared before new records are written. |
|
CREATE APPENDING |
declares the auxiliary DS for accepting new records. They will be added to any records currently in the DS. |
|
UPDATE |
declares the auxiliary DS for reading, deleting, changing records, and appending new records. |
|
DEFER OPEN |
defers opening the auxiliary DS until the DS is be opened with an OPEN statement. In some applications the name of the DS or DI is not known when the PM begins execution. If the DEFER OPEN option is specified in the RELATE statement, the name of the DS or DI can be specified later in the OPEN statement. Also, you can process multiple DS's with one “related” DS by CLOSEing one and the OPENing another. For example, you can create a PM where the user enters the DS name or DI name during PM execution. Before, the user of the PM had to specify an EQUATE clause in the command that started execution of the PM. Now the PM can ask the user the name at any time prior to the OPEN statement. You can also CLOSE the current DS or DI and OPEN another, thus allowing you to process many DS's or DI's. |
This example illustrates data accessing with users specifying different combinations of FOR clause and ALLOWING clause in the RELATE statement. All jobs below have requested access to the same DS. The STATUS columns are time sequenced from left to right.
| Job | Relate For | Allowing Others To |
Job Sequence: Time Sequence | ||||
| Status (1) | Status (2) | Status (3) | Status (4) | Status (5) | |||
| 1 | UPDATE | UPDATE | running | done | |||
| 2 | INPUT | UPDATE | running | done | |||
| 3 | UPDATE | UPDATE | running | done | |||
| 4 | INPUT | WAIT | queued | running | done | ||
| 5 | UPDATE | UPDATE | queued | queued | running | done | |
| 6 | UPDATE | UPDATE | queued | queued | running | done | |
| 7 | UPDATE | UPDATE | queued | queued | queued | running | done |
| 8 | UPDATE | INPUT | queued | queued | queued | queued | running |
| 9 | UPDATE | UPDATE | queued | queued | queued | queued | queued |
Jobs 1, 2, and 3 run concurrently since their FOR clauses and ALLOWING clauses permit each other to concurrently access the DS.
Job 4 runs by itself, since an ALLOWING OTHERS TO WAIT clause specifies exclusive access to the DS. It establishes the Exclusive Queued environment.
Jobs 5 and 6 both create the Concurrent Queued environment, and both allow others to update, so they can run together.
Jobs 7 and 9 are compatible, but because 8 is not compatible and cannot run with 7, 9 must wait. No job is ever allowed to move up in front of an earlier job in the queue. This is to avoid indefinite postponement as job after job would jump in front of an incompatible one.
NOTES: The \\field\\ option cannot be used when an ALLOWING clause establishes the Concurrent Queued environment for the DS.
Up to 100 auxiliary DS’s can be related in one PM if sufficient hardware input-output (IO) channels are assigned to the user.
It is advisable to FORM CHECK all DI’s to be used for auxiliary DS’s before the PM is used. ACCENT R does form any obsolete or unformed DI’s at run time, but the process is less efficient.
Processes may time out unless all PM’s open shared tables in the same order. ACCENT R will sort the data set names and open them in alphabetical order to help avoid dead locking PM's. It has no control over those with DEFER OPEN specified.
FORM 3: (RELATE) Report Files
RELATE {SF {name; FROM COMMAND}; TERMINAL} {AS; TO; WITH} REPORT
n [APPEND/ING/]
|
SF name |
is the name of the SF on which the report will be written. The default extension is .REP. |
|
SF FROM COMMAND |
is used if the SF name is specified in the VIA clause of the command. The command that calls the PM can then include a parallel sub-clause. REPORT n TO sf_name If no such clause is included, the report displays on the terminal screen. Using the command instead of the PM to name an SF that is to receive a report is valuable if: a) creating a report repeatedly, but do not want to have the previous version of that report written over by the current version; b) deciding at the time the PM is run whether the report should go to the terminal or a file. |
|
TERMINAL |
can be specified as the destination for the report. |
|
AS, TO, WITH |
are synonymous - any of the three can be used. |
|
REPORT n |
specifies the number that will be used to reference the report in later section’s of the PM. |
|
APPENDING |
must appear at the end of the statement following the report number. Causes the new report data to be added to the end of the file if one already exists. |
NOTES: It is possible to create up to ten reports within each PM, and there must be a RELATE statement for each report.
It is important that only one report be directed to the terminal. If two or more reports display on the terminal screen, the report lines interweave as the reports are displayed.
PURPOSE: This statement declares GS for use in a PM and associates the GS’s with the designators by which they will be identified throughout the PM. A maximum of ten GS’s can be declared. All GS's that is used within the PM must be identified in a RELATE statement.
The RELATE statement can only occur in the CONTROL section of a PM.
The GS’s that are related in a PM must be declared with a USE GS command before the PM is executed.
FORM 4: (RELATE) Global Storage Areas
RELATE GS gs_name1 AS designator
|
gs_name |
specifies an existing GS to be used. Up to ten GS names can be specified. |
|
designator |
specifies the name by which the GS is addressed in the PM. The designator may be the same as the GS name, but it still must be specified after the “AS”. The designator must begin with an alphabetic character and can contain alphabetic characters, numbers, underscores, and periods. The designator can be up to 40 characters long. |
RELATE GS BOOK_LIB AS BK
RELATE GS COVERS AS COV
These statements relate the GS’s named BOOK_LIB and COVERS for use in the PM. In the rest of the PM, these two GS’s are referred to by their designators (BK and COV). For example, assume that GS BOOK_LIB and GS COVERS both contain a field called %ID and that the value from a declared field named ID is to be moved to %ID in both GS BOOK_LIB and GS COVERS.
ID:D TO %ID: %ID:BK
ID:D TO %ID: %ID:COV
Global storage can be used to pass information from one PM to another since the area for the GS is allocated when the use command is given. For example:
Global storage areas can also be declared shareable outside of ACCENT R with C, FORTRAN or COBOL programs. See USE GS for details on how this is accomplished.
NOTES: Once a GS has been related in a PM, any of the fields in that GS can be accessed in any section in the PM.
FORM 5: (RELATE) Data Base Library
RELATE DBL {name; FROM COMMAND} {AS; TO; WITH} designator /FOR INPUT/
|
name |
is the name of a DBL. It can be any DBL name, including the current one. |
|
FROM COMMAND |
indicates that the DBL will be specified in the EQUATE clause or subclause of the command that calls the PM. If the command does not specify a DBL, the current DBL is used. |
|
AS, TO, WITH |
are synonymous--any of the three can be used. |
|
designator |
is the name by which the DBL will be identified in later GET statements in the PM. |
|
FOR INPUT |
are clarity words. The DBL can only be accessed for input. See the GET statement for DBL access for information on how to access the DBL entries and what information is available. |
The example below relates a master DS, a transaction DS, and three SF's for report output. The master DS is to be updated, but the transaction DS will be used only for input to the PM. The three report files will all have the default extension .REP.
DEFINE PM BOOK_REPORTS
CONTROL SECTION RELATE DS BOOKS AS MASTER FOR UPDATE RELATE DS SALES AS TRANSACTION FOR INPUT RELATE SF SALES_YTD_REP AS REPORT 1 RELATE SF ORDER_REP AS REPORT 2 RELATE SF FROM COMMAND AS REPORT 3
USE DS BOOKS
ALTER VIA BOOK_REPORTS EQUATE REPORT 3 TO PUB_REP
The following example relates a GS area named BOOK_LIB and one auxiliary DS named BOOKS. Since no master DS is related, the PM that contains this CONTROL section must be executed by a USE PM command. No designator is assigned in the relate GS statement since it is the only GS and there is no possibility of two GS fields having the same name in the DBL.
CONTROL SECTION
RELATE GS BOOK_LIB
RELATE DS BOOKS WITH AUX1 ON INIT FOR INPUT
The next CONTROL section relates a variety of objects. By relating a SD as the master, this PM can be used on any DS associated with that SD. The particular DS used is named in the USE DS command at execution time. The second RELATE statement relates a DI as an auxiliary. The third RELATE statement, which relates an auxiliary DS, includes an ON clause. The DS must be sorted on the named fields before the PM is executed, as GET statements later in the PM will retrieve records in order on those fields. The fourth RELATE statement names the SF that is to receive the single report produced.
CONTROL SECTION RELATE SD BOOKS AS MASTER FOR UPDATE RELATE DI PUB AS AUX1 FOR INPUT RELATE DS BOOKS AS AUX2 ON TITLE_CODE, PUB_CODE FOR INPUT RELATE SF BOOK_LIST AS REPORT 1
The next example shows the relationship of the RELATE statement to the command that declares the DS and the command that calls the PM. The two commands could be contained in a CM.
USE DS BOOKS DI BOOKS UPDATE WITH SALES MATCH ON TITLE_CODE VIA KEEPUP
Since the UPDATE command above does not include a USE DOMAIN clause, the first domain of DI BOOKS is used by default. The RELATE statement in the PM must match these two commands in two ways: 1) The schema (SD) in the relate statement must be the schema associated with the data set books and 2) it must specify FOR UPDATE (since the UPDATE command requires that mode).