SIPCC–System interprocessor/inter-I-stream communication

Use this system macro to provide communication among processors in a z/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    

Last updated

  • Changed for PUT06.
  • Changed for PUT00.

Format

Read syntax diagramSkip visual syntax diagramlabelSIPCC PGM= prog1,RETURN= prog2,TYPE=IP,TYPE=IS,CREG=R14,CREG= reg1,CLBL= label1,DREG=R15,DREG= reg2,DLBL= label2,LEV=D0,LEV=Dn,LIST=label3
label
is a symbolic name that can be assigned to the macro statement.
PGM=prog1
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
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
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
is a symbolic name identifying the location of an 8-byte control area.
CREG=R14|reg1
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
is a symbolic name identifying the location of a variable length data area (DA1).
DREG=R15|reg2
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
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
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 (SI3DSTN) to the following values:
    • Broadcast destination (SI3DSTN = X'FF')
    • Destination processor list (SI3DSTN = 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 z/TPF General Services for information about the GENLC macro.
    • Specific destination processor (SI3DSTN = 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 (SI3DSTN) in the user control area is unchanged.

  • A flag (SI3INAC) is turned on in the control area if any destination processor specified in SI3DSTN 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

  • For information about macro register conventions, see Register conventions.
  • 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 in-core staging to be halted and transmission for all available items to be started. 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 be allocated and listed in the control file. See z/TPF Program Management for more information about control files.
  • 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, SI3DSTN can be set to X'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 SI3DSTN 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 (SI3DSTN=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