This general macro has two distinct functions:
- In the online environment, it permits the initiation of a request to
synchronize a global field or record among all active tightly coupled
processors, loosely coupled processors, or both.
- In the offline environment, it is used in SIP Stage 2 to build the system
interprocessor global table (SIGT).
See also the global area program material in the TPF
System Installation Support Reference.
Format
- label
- A symbolic name can be assigned to the macro statement.
- LOCK
- Obtains exclusive use of the specified global. When the LOCK option
is used, this macro will obtain the requested global with Hold and will
refresh the core copy of the global with the current file copy.
- UNLOCK
- Releases exclusive use of the specified global. The UNLOCK option
will unhold the file copy of the global. The requested global must have
been locked first.
- SYNC
- Requests synchronization of the specified global. When the SYNC
option is requested, the designated global is filed, and an entry is created
to activate the synchronization of the global among the active
I-streams. In addition, in a loosely coupled (LC) environment, the
interprocessor communication facility (IPC) is activated. The IPC is
used to inform the other processors in the LC complex that the requested
global value should be refreshed in core. After filing the record and
activating the IPC, processing is the same as for the UNLOCK option.
Again, the requested global must be locked prior to executing this
request.
- symbol2
- A global field or record name must be specified as symbol2.
- INDEX=NO|Rx
- When Rx is specified, the index value in Rx is added to
the value generated by symbol2 to calculate the index number for the
global record to be synchronized. If this option is not used, the index
value generated by symbol2 is used.
This option is valid only for synchronizable global records (not global
fields). Valid registers are R0-R7, R14, and R15.
- Note:
- The purpose of providing the INDEX feature is to facilitate stepping through
a consecutive list of global records in the SIGT. Normal care must be
exercised in setting up and using such a list.
- ERRTN=label
- When present, this parameter will generate a branch to the specified label
when an error occurs during execution of the SYNCC macro.
If not present and an error occurs during execution of the SYNCC macro, a
system error with dump will occur and the ECB will be exited.
This parameter generates an additional four bytes of object code.
- TBL=NO|GEN|END
- This parameter is specified as GEN or END only when a new system
interprocessor global table (SIGT) is to be generated. Since a SIGT is
not usually being generated, NO is the default.
- When used, it should be the only parameter coded.
- Application programs should never use this parameter.
Normal usage is as follows:
SYNCC TBL=GEN
SYNCC GLOBAL=...etc.
SYNCC GLOBAL=...etc.
.
.
.
SYNCC TBL=END
Only the following parameters can be used in the SIGT generation (when
TBL=GEN).
BASE=
COMMON=
GLOBAL=
IS=
LOAD=
PROTECT=
- BASE=GLOBA|GLOBY
- Global base for this data.
- COMMON=YES|NO
- This indicates whether the global is common to other SSUs or not.
YES and NO are the only valid values. If YES is specified, and GLOBAL
refers to a Global field, then BASE must be GLOBY.
- GLOBAL=name
- Name of the synchronizable global data.
- IS=UNIQUE|SHARED
- This indicates whether the global is shared by all I-streams in each
central processing complex (CPC). UNIQUE and SHARED are the only valid
values.
- LOAD=YES|NO
- This is valid for global fields only. If YES, indicates
that on the load of a new SIGT, the DASD-resident copy of the Synchronizable
Global Field Record (SGFR) for the item referenced by GLOBAL is to be
initialized from the core copy of the global field. If NO, the SGFR
record will not be initialized during IPL. YES and NO are the only
valid values.
The default is YES.
- PROTECT=GLOBAL1|GLOBAL2|GLOBAL3
- This indicates which protection key should be stored in the SIGT table
entry for this item.
Entry Requirements
- The following are entry requirements for the online function:
- R9 must contain the address of the ECB being processed.
- The entry must not be holding a lock on any global field or global record
at the time of a LOCK request.
- The entry must not be holding a record at the time a LOCK request is
made.
- There should not be any outstanding I/O at the time this macro is
issued.
- The entry must be holding a lock on the global field or global record
requested to be unlocked or synchronized.
- If the parameter INDEX=rx is coded, the general register
specified by rx must contain the increment that will be added to the
index generated from symbol2 to calculate the total global
index.
- If the user wants control returned on an error condition, the ERRTN
parameter must be coded.
- The user should issue the LOCK and associated UNLOCK in the same segment,
to ensure the protect key. The LOCK should not be carried across Enter
macros.
- The following are entry requirements for the offline function:
- The macro SYNLST, generated as part of the system generation procedure,
must be available to the assembler that processes the SYNCC table generation
run.
- The macro SYNLST contains a list of valid synchronizable global fields and
records as defined at system generation time by means of GLSYNC
statements. The sequence of SYNCC table generation statements must
exactly follow the order of the SYNLST sequence, with no omissions or
additions.
Return Conditions
- The following are return conditions for the online function:
- The contents of R14 and R15 are unknown. The contents of all other
registers are preserved across this macro call.
- LOCK option:
- After the lock operation has successfully completed, control is returned
to the next sequential instruction (NSI). If the ERRTN parameter is
coded, return is NSI+4.
- The protect key corresponding to the requested global is set in the
current PSW.
- If an error has occurred and the ERRTN parameter is not coded, the entry
is exited after a system dump is taken. If the ERRTN parameter is
coded, control is returned at the NSI, except for errors stemming from
possible destruction of core. In this case, the entry is exited after a
system error.
- If an error is returned from the internally-generated FIWHC macro while
trying to retrieve the global sync records, one of the following occurs:
- If the error is the result of a hold lockout or processing of the ZECBL
command (CE1SUD=X'81'), it is a user error. The 0000DB system
error is issued and the ECB is exited.
- If the error occurred because of record retrieval problems (for example, a
record ID failure occurred), it is related to database corruption. The
0006A3 system error is issued and the affected subsystem is cycled to 1052
state so that you can take immediate corrective action.
- The contents of the general registers, except for R14 and R15, and the
condition code are saved while processing this macro.
- The core copy of the requested global has been refreshed by the lock
operation.
- The ECB global sync indicator (CE1SYN) indicates a LOCK condition and the
entry's hold counter is incremented.
- UNLOCK option
- Control is returned to the next sequential instruction. NSI+4 if
ERRTN i
- The current PSW protect key is reset to that of working storage.
- The contents of the general registers, except for R14 and R15, and the
condition code are saved during execution of this macro.
- The ECB global sync indicator (CE1SYN) is cleared and the entry's hold
counter is decremented.
- SYNC option
- Control is returned to the next sequential instruction. NSI+4 if
ERRTN is coded.
- The current PSW protect key is reset to that of working storage.
- The contents of the general registers, except for R14 and R15, and the
condition code are saved during execution of this macro.
- For the offline function, assuming no errors, assembling a valid set of
SYNCC statements will produce a SIGT table in the form of a loadable object
deck plus a table listing. Since no executable code is generated, there
are no return conditions.
Programming Considerations
For the online function, this macro can be executed on any I-stream.
Examples
- This example shows a global symbol @SYNCD being locked, some processing
taking place, and then being unlocked.
SYNCC LOCK,@SYNCD
.
<processing>
.
SYNCC UNLOCK,@SYNCD
- The global referred to by @SYNCREC plus the additional index value in R4
is filed and synchronized among the active i-streams. If an error
should occur, control transfers to LABEL99 for recovery.
SYNCC SYNC,@SYNCREC,INDEX=R4,ERRTN=LABEL99
- This is an example of generating a system interprocessor global
table. First, the TBL parameter is used to initiate table
generation. Next, a number of globals and their characteristics are
defined. Finally, table generation is ended with the TBL parameter
again. The global shown below is being defined in global area A with
the protection key of global1. The global is unique to the SSU defining
it, is I-stream unique, and when the SIGT is loaded the global value in main
memory is synchronized with its DASD copy.
SYNCC TBL=GEN
SYNCC GLOBAL=@SYBCD,BASE=@GLOBA,PROTECT=GLOBAL1,COMMON=NO,LOAD=YES, X
IS=UNIQUE
SYNCC etc. .
. . .
. . .
SYNCC TBL=END