gtpc2m6w | C/C++ Language Support User's Guide |
This function provides communication among processors in a TPF loosely
coupled (LC) environment. It causes an interprocessor communication
(IPC) item to be transmitted to a specified program segment in one or all
active I-streams, and in one or more active processors. The destination
processors can be specified as a single processor, as a list of processors, or
as a broadcast to all processors. The destination I-streams can be
targeted as either the main I-stream or all I-streams in the destination
processors.
An IPC item consists of control information and, optionally, two variable
length data areas. Data area 1 (DA1) may be up to 104 bytes
maximum. Data area 2 (DA2) may be any length that will fit in a single
128-, 381-, 1055-, or 4K-byte storage block.
Format
#include <sysapi.h>
int sipcc(const struct sipcc_parm *sipcc_parm_list);
- sipcc_parm_list
- A pointer to a sipcc_parm structure as described below:
- sipcc_num_parm
- Number of parameters following this one. Values between
SIPCC_PARM_MAX and SIPCC_PARM_MIN are valid. This number defines the
range of parameters that are recognized by the sipcc handling routine.
The range always begins with the first parameter (sipcc_receiving_pgm).
The following parameters are in the exact order that will be described by the
range.
- sipcc_receiving_pgm
- Program name that is invoked in the receiving processors. It is a
required parameter.
- sipcc_da1_len
- Length of data area 1. Maximum length is 104 bytes. It is an
optional parameter.
- sipcc_da1_ptr
- Pointer to data area 1. This parameter is ignored when
sipcc_da1_length is zero. It is required when sipcc_da1_length is not
zero.
- sipcc_da2_len
- Length of data area 2. The length cannot exceed the size of the
storage block specified in the level of sipcc_da2_. It is an optional
parameter.
- sipcc_da2_lvl
- A valid data level from enumeration type t_lvl. This
field is ignored if sipcc_da2_length is zero. It is required when
sipcc_da2_length is not zero. If a data level is specified, that data
level must hold a block.
- sipcc_priority
- SIPCC_PRIORITY_YES for a high priority request or SIPCC_PRIORITY_NO for a
regular request. SIPCC_PRIORITY_NO is the default if the parameter is
omitted.
- sipcc_xmit_type
- SIPCC_XMIT_IP for inter-processor or SIPCC_XMIT_IS for
inter-processor/inter-I-stream transmission. SIPCC_XMIT_IP is the
default if the parameter is omitted.
- sipcc_receiving_proc
- The processors that are to receive this item. For a single
processor, specify the ordinal number of the processor; for all active
processors, specify SIPCC_ALL_ACTIVE_PROC; for a list of processors,
specify SIPCC_PROCESSOR_LIST. If a list is specified,
sipcc_list_ptr must contains a pointer to the list of
processors. The default is SIPCC_ALL_ACTIVE_PROC if the parameter is
omitted.
- sipcc_receiving_is
- I-streams to be receiving the item. SIPCC_IS_MAIN or SIPCC_IS_ALL
are valid. SIPCC_IS_MAIN is the default if the parameter is
omitted.
- sipcc_response
- SIPCC_RESPONSE_YES or SIPCC_REPONSE_NO. This parameter is only used
by user application programs. The SIPCC service routine will only pass
the value to user applications without any processing. The default
value is SIPCC_RESPONSE_NO if the parameter is omitted.
- sipcc_item_type
- SIPCC_REQUEST_ITEM or SIPCC_RESPONSE_ITEM. This parameter is only
used by user application programs. The SIPCC service routine will only
pass the value to user applications without any processing. The default
value is SIPCC_REQUEST_ITEM if the parameter is omitted.
- sipcc_list_ptr
- A pointer to an area of storage containing a list of destination processor
ordinal numbers. The sipcc_list_ptr parameter is required
when specifying a list of destination processors (the
sipcc_receiving_proc parameter is set to SIPCC_PROCESSOR_LIST) and
is optional for requests that broadcast to all processors or that transmit to
a single processor. If specified, on return from the request the list
area contains a list of processor ordinal numbers for all processors to which
transmission was started.
Normal Return
SIPCC_OK is returned when transmission to the destination processor has
been initiated.
Error Return
SIPCC_FAILED is returned when transmission to the destination processor was
not initiated.
Programming Considerations
- This function can be issued only by an E-type program.
- The C library function service routine will set up the control area, which
includes the destination, flags, and length fields of data area 1 and data
area 2, and issues a SIPCC SVC.
- The address of the optional second data area, DA2, is specified in the
storage block reference word of the ECB at the level specified in the
parameter list. DA2 must reside in a storage block. If DA2
exists, the data transmitted will begin at byte 0 of the storage block for the
specified length.
- The storage block provided for data area 2 will remain attached to the ECB
upon return of control at NSI.
- There will be no attempt to transmit to an inactive processor.
- IPC items that require expedited handling are identified by setting the
SIPCC_PRIORITY_YES flag in the parameter list. 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 parameter list (the program segment that
is invoked in the receiving processor) must reside on the database indicated
by the PBI field in the requestor's ECB.
- The PBI, DBI, and SSU ID fields in the requester's ECB will be
transmitted to the destination processors. 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 in
the receiving processor is as follows:
- 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.
- There is an implied Wait if storage blocks required by the System
Interprocessor Communication Facility (SICF) are not available when
needed.
- The sipcc library function routine will recognize the following
sipcc error and exit the ECB
- The length of DA1 is greater than 104 bytes.
- The length of DA2 is greater than the storage block size on the specified
level.
- The sipcc_list_ptr parameter must contain a pointer to a list
of processors, but the value is null.
- If sipcc_list_ptr is specified, the original content of the
list area is not preserved. The list area is overlaid by the
sipcc function with a list of processor ordinal numbers to which
transmission was started.
Examples
The following example calls sipcc to broadcast an IPC to program ABCD in
all active processors at regular priority, with no response required.
200 bytes of data reside in a data block on data level D4.
·
·
·
struct sipcc_parm sipcc_parm_list = {
5, /* 5 parameters follow. */
{ "ABCD" }, /* #1 - Receiving pgm name. */
0, /* #2 - Data area 1 length. */
NULL, /* #3 - Data area 1 address. */
200, /* #4 - Data area 2 length. */
D4 /* #5 - Data area 2 data lvl. */
};
·
·
·
if (sipcc(&sipcc_parm_list) != SIPCC_OK)
{
/* Handle sipcc failure. */
}
Related Information
See TPF System Macros for information about the
SIPCC macro.