Use this system macro to provide communication among processors in a TPF
loosely coupled environment and among instruction streams in a tightly coupled
environment.
This macro causes an interprocessor communication (IPC) item to be
transmitted to a specified program segment in one or more active I-streams, in
one or more active processors. The destination processors can be
targeted individually, in various combinations or in a broadcast
request. The destination I-streams can be targeted as the main I-stream
or all I-streams in the destination processors.
An IPC item contains the following information:
- An 8-byte user control area
- A 24-byte IPC control area
- 2 variable length data areas (this is optional).
Data area 1 (DA1) can be no more than 104 bytes while data area 2 (DA2) can
be any length that fits in a single 128, 381, 1055, or 4 K byte storage
block.
Required Authorizations
|
Key0
| Restricted
| System
| Common Storage
|
| X
|
|
|
Format
- label
- A symbolic name can be assigned to the macro statement.
- PGM=prog1
- This is a 4-character name identifying the program segment invoked in the
receiving processors or I-streams for which this item is intended.
- RETURN=prog2
- This is a 4-character name identifying the program segment in this
processor to be given control for each active destination processor that reads
or fails to read this processor's transmission.
- TYPE
- This parameter is used to specify the type of processing requested.
- IP
- Indicates interprocessor communication is requested and will transmit the
SIPCC request to the specified processors. The request will not be
transmitted to the originating processor. This is the default.
- IS
- Indicates inter-I-stream communication is requested and will transmit the
SIPCC request to the main I-stream or all I-streams on the specified
processors including the originating processor. The request will not be
transmitted to the originating I-stream.
- CLBL=label1
- This is a symbolic name identifying the location of an 8-byte control
area.
- CREG=R14|Rx
- This is a symbolic name identifying the register that contains the address
of an 8-byte control area.
Default: If neither CLBL nor CREG is specified, register
R14 is assumed to have a pointer to the control area.
- DLBL=label2
- This is a symbolic name identifying the location of a variable length data
area (DA1).
- DREG=R15|Ry
- This is a symbolic name identifying the register that contains the address
of a variable length data area (DA1).
Default: If neither DLBL nor DREG is specified and the
SI3LEN1 field in the control area (SI3CT) is not zero, register R15 is assumed
to have a pointer to data area 1.
- LEV=D0|...|DF
- This is a symbolic value, D0-DF, which identifies the ECB level containing
the storage block to be transmitted (DA2).
Default: If LEV is not specified and the SI3LEN2 field in
the control bytes is not zero, a level of zero is assumed.
- LIST=label3
- This is a symbolic name that identifies the name of a variable list of
destination processors.
The LIST parameter can be specified with all destination types. If
specified, the SIPCC macro service routine returns a list of all processors to
which transmission was started.
Entry Requirements
- R9 must contain the address of the entry control block (ECB) being
processed.
- You must set up an 8-byte control area. Optionally, you can set up
one or two data areas and a list of destination processors. The setup
includes initializing the destination, flag, and length fields in the control
area, as well as establishing the data areas.
- The address of the control area must be put in R14 or be specified with
the CLBL or CREG parameter.
- The address of the optional first data area, DA1, must be put in R15 or
specified with the DLBL or DREG parameter.
- The address of the optional second data area, DA2, is specified in the
storage block reference word of the ECB at the level specified by the LEV
parameter. DA2 must reside in a storage block and LEV must be specified
if the length field for DA2 is not zero. If DA2 exists, the data
transmitted will begin at byte 0 of the storage block for the specified
length.
- Processor destination information is specified in the IPC control area
(SI3CT). Destination types are specified by setting the destination
field (SI3DEST) to the following values:
- Broadcast destination (SI3DEST = X'FF')
- Destination processor list (SI3DEST = X'FE')
- Note:
- The list of destination processors is specified by the LIST parameter.
To generate a list of destination processors, use the GENLC macro. See
TPF General Macros for information about the GENLC
macro.
- Specific destination processor (SI3DEST = X'nn', where nn
is the processor ordinal number).
Return Conditions
- Control is returned to the next sequential instruction (NSI).
- The contents of R14 and R15 and the condition code are unknown. The
contents of all other registers are preserved across this macro call.
- The activity field (SI3ACT) in the control area is set to the number of
active destination processors for which the transmission was started.
The system interprocessor communications facility (SICF) uses the Processor
Status Table (PI1DT) to determine processor activity. If there are no
other active processors when SIPCC is requested, SI3ACT is set to zero.
If the destination was selective and the LIST parameter was specified, the
returned list contains the ordinal numbers of the destination processors for
which the transmission was started.
- Note:
- The original contents of the list are not preserved. The list is
overlaid by the SIPCC macro service routine on return to the user.
If the destination was broadcast (sent to all active processors) and the
LIST parameter was specified, the returned list contains the ordinal numbers
of the destination processors for which the transmission was started.
The destination field (SI3DEST) in the user control area is
unchanged.
- A flag (SI3INAC) is turned on in the control area if any destination
processor specified in SI3DEST is not active when SIPCC macro processing
begins.
- The storage block provided for data area 2 will remain attached to the ECB
upon return of control at NSI.
- SICF will invoke the program segment specified by the RETURN parameter for
each destination processor that:
- Reads this processor's transmission if the SI3CT flag SI3XMIT is set
(=1)
- Fails to read this processor's transmission if the SI3CT flag SI3XERR
is set (=1).
The control fields and data areas will be set up by SICF in the same format
as for a receiving program. The SI3RETD flag identifies the invocation
as a RETURN. The SI3RERR flag will be off (=0) if the transmission
completed successfully and the SI3XMIT flag was set (=1). SI3RERR will
be on (=1) if the transmission failed to be completed and SI3XERR was set
(=1). SI3PROC contains the ordinal number of the destination processor
that read or failed to read the transmission.
- Note:
- Special considerations exist when RETURN and TYPE=IS are specified.
I-streams on the originating processor may receive transmissions but, since
the originating processor is not considered an IPC destination, will not
invoke a program RETURN.
Programming Considerations
- This macro may be processed on any I-stream.
- The SIPCC macro can be issued only by a E-type program.
- The ECB reference register (R9) must contain the address of the ECB before
issuing the SIPCC macro.
- ECBs created by the SIPCC macro use the version of the program most
recently activated on the specified processor. If this program is
incompatible with the program that issued the SIPCC call, an interface problem
may occur.
- The CREG and DREG parameters must be coded or defaulted to different
registers.
- The user of SIPCC can be notified of successful and/or unsuccessful
transmissions, for each active destination processor, by coding the macro
RETURN parameter and setting the SI3XMIT and/or SI3XERR flags in the user
control area (SI3CT). See the previous note for TYPE=IS
considerations.
- When using the I-stream routing request the user will specify the I-stream
destination by setting the SI3ALL_IS flag in the user flag byte
(SI3FLGU). When routing to the main I-stream set SI3ALL_IS to 0.
When routing to all I-streams set SI3ALL_IS to 1. Requests will not be
routed to the originating I-stream.
- No attempt is made to transmit to an inactive processor. If the
request was a broadcast to all processors in the complex and any processor is
not active, flag SI3INACT is set (=1).
- IPC items that require expedited handling are identified by setting the
priority flag (SI3PRTY) in the control area to 1. Priority requests
cause incore staging to be halted and transmission for all available items to
be initiated. In the receiving processors, priority items are placed on
the ready list.
- The program segment named in the PGM and RETURN parameters must reside on
the data base indicated by the PBI field in the requestor's ECB.
That is, the program must have been allocated using the system allocator and
loaded to the system files. See TPF System
Installation Support Reference for more information about the system
allocator.
- The PBI and SSUID fields in the requestors ECB will be transmitted to the
destinations. There, they will be used to initialize the ECB and invoke
the specified program.
- The format of an IPC item as seen by the destination program segment and
the program segment specified in the RETURN parameter is as follows:
- The 8-byte control area will be placed in the second work area of the ECB
beginning at location EBX000.
- Data area 1 will be placed in the first work area of the ECB beginning at
location EBW000.
- Data area 2 will be placed in a storage block on level 0 of the
ECB. The size of the storage block will be the same as the sender's
block size.
- In addition to the normal macro trace information, the SIPCC macro trace
entry will contain the destination processor indicator, the origin I-stream,
the system flag field, and the user flag field.
Examples
- Broadcast data from location EBW008 to segment CDEF in all active
processors. The control area is defined at location EBW000.
SIPCC PGM=CDEF,CLBL=EBW000,DLBL=EBW008
- Note:
- Since the control area will be modified by SICF, it must reside in modifiable
storage.
- Same as previously except that the address of the control area has been
placed in register 2.
SIPCC PGM=CDEF,CREG=R2,DLBL=EBW008
- Note:
- SICF will load R15 with the address of EBW008. R15 could not,
therefore, have been used for CREG.
- Broadcast data from location EBW008 to segment CDEF in all active
I-streams in all active processors.
SIPCC PGM=CDEF,TYPE=IS,CREG=R2,DLBL=EBW008
For this example the user has set SI3ALL_IS to '1'. Also,
SI3DEST can be set to 'FF' to indicate all processors.
- The data being transmitted has now been moved to a storage block and its
address loaded in register R15. The user wishes to have this data
appear in the destination segment's ECB.
SIPCC PGM=CDEF,CREG=R2
- Note:
- Neither DREG nor DLBL had to be specified since R15, the default register,
contains the address of the data.
- In this example, the data is in the same storage block (on level 4) but
you want the destination segment to receive it in an equivalent storage
block.
SIPCC PGM=CDEF,CREG=R2,LEV=D4
- Note:
- Destination segment CDEF will receive the storage block on level 0.
- Having preloaded R14 and R15 with the control area and data area
addresses, you may want to notify the KLMN segment of successful transmissions
to each of the destination processors.
SIPCC PGM=CDEF,RETURN=KLMN
- Note:
- The SI3XMIT control area flag had to be set before issuing the SIPCC
macro.
- You may want a response from the destination segment. There are to
be no data areas transmitted.
SIPCC PGM=CDEF
- Note:
- The SI3LEN1 control area field must be zero otherwise SICF will assume R15
contains the address of a data area. You must also have preloaded R14
with the address of the control area. The SIEREQR control area flag may
be used to request a response. SICF does not make use of this
flag.
- You can specify a set of destination processors by using a data list
contructed by the GENLC macro. For this, the SI3DEST control area field
is set to X'FE' and the address of the list is passed to the SIPCC
service routine by the LIST parameter.
SIPCC PGM=CDEF,CREG=R2,LEV=D4,LIST=EVNBKLW
- Note:
- On return, the contents of the list block are modified to hold a list of the
processors to which transmission was started. The list block can be
empty (list count of 0).
- When specifying a broadcast transmission (SI3DEST=X'FF'), you can
have the SIPCC macro service routine return a list of processors to which the
transmission was started. This returned list can be used with the
Internal Event Facility (LIST type event).
SIPCC PGM=CDEF,CREG=R2,LEV=D4,LIST=EBX000