UCLA/IPC-370 Programming (IPCPROG) V1.410 (Preliminary) University of California Office of Academic Computing 5628 Math Sciences Addition Los Angeles, California 90024 Michael Stein OAC Systems CSYSMAS@OAC.UCLA.EDU Copyright Regents University of California, 1984, 1985, 1986. DISCLAIMER __________ The University of California requires the following disclaimer concerning all distributed programs: Although this program has been tested by its contributor, no warranty, expressed or implied, is made by the contributor or the University of California, as to the accuracy and functioning of the program and related program material, nor shall the fact of the distribution constitute any such warranty, and no responsibility is assumed by the contributor or the University of California, in connection therewith. 06/21/91 17:40 UCLA/IPC-370 Programming (IPCPROG) Page i CONTENTS ________ Introduction . . . . . . . . . . . . . . . . . . . . . . 2 Note definitions . . . . . . . . . . . . . . . . . . . 2 IPC Services . . . . . . . . . . . . . . . . . . . . . . 3 IPC operation . . . . . . . . . . . . . . . . . . . . 3 IPC SVC interface . . . . . . . . . . . . . . . . . . 4 IPC restrictions . . . . . . . . . . . . . . . . . . . 4 IPC validity checking . . . . . . . . . . . . . . . . 5 IPC tag string . . . . . . . . . . . . . . . . . . . . 5 tag string format . . . . . . . . . . . . . . . . . 5 parsed tag string format . . . . . . . . . . . . . 6 tag string matching . . . . . . . . . . . . . . . . 6 CID (connection id) . . . . . . . . . . . . . . . . . 7 IPC request completion codes . . . . . . . . . . . . . 7 IPC Abend codes . . . . . . . . . . . . . . . . . . . 8 IPCSTAT service routine - IPC reason codes . . . . . . 9 IPCREQ macro . . . . . . . . . . . . . . . . . . . . . . 9 IPCREQ Dsect generation . . . . . . . . . . . . . . 10 IPCREQ request common operands . . . . . . . . . . . 10 IPC notification(s) - NOTIFY= . . . . . . . . . . . 10 IPC Connection Ids - CID= . . . . . . . . . . . . . 12 IPC options - OPTIONS= . . . . . . . . . . . . . . . 12 IPCREQ OPEN . . . . . . . . . . . . . . . . . . . . 12 IPCREQ SEND . . . . . . . . . . . . . . . . . . . . 13 IPCREQ RECEIVE . . . . . . . . . . . . . . . . . . . 13 IPCREQ CLOSE . . . . . . . . . . . . . . . . . . . . 13 IPCREQ ABCLS . . . . . . . . . . . . . . . . . . . . 14 IPCREQ QTAG . . . . . . . . . . . . . . . . . . . . 14 IPCREQ QUSER . . . . . . . . . . . . . . . . . . . . 14 INDEX . . . . . . . . . . . . . . . . . . . . . . . 15 UCLA/IPC-370 Programming (IPCPROG) Page 2 INTRODUCTION Inter-Process-Communication (IPC) is a product developed by UCLA/OAC to provide communication services between processes for MVS and future systems. Since MVS differs from previous systems in many ways most of the approaches previously used were not considered viable for MVS and future systems. IPC has the ability to evolve with the operating system. IPC's relatively simple, fixed external interface hides the changes to the internals required by system changes. This simple interface assumes that future communication (hardware/software) capabilities will eventually eliminate hardware forced protocols. Communication link speed is also assumed to be fast enough to avoid requiring special transmission options to maintain efficiency. This is certainly true now as all IPC data transfer is storage to storage in a single MVS system. Note definitions ________________ The notes scattered throughout this document are intended as suggestions, they are NOT part of the IPC defined interface. Any use of these is at your own risk. Note: This is a general IPC programming note. It generally consists of hints to the programmer on intended use or debugging techniques for programs using IPC. As an aid in debugging programs using IPC, some simplified versions of IPC internal processing logic is included. Temp: This is the current state of affairs and it WILL change (when I get time). No attempt will be made to make these changes upward compatible with the current IPC. Future: This describes possible future changes. These might be implemented, but not necessarily this way. An attempt will be made to keep these changes upward compatible with the current version of IPC. OAC: These notes are specific to UCLA/OAC. UCLA/IPC-370 Programming (IPCPROG) Page 3 IPC SERVICES IPC operation _____________ IPC provides "connections" between "processes". connection -- half-connection -- process -- IPC currently assumes each end of a connection is controlled by a separate process, connections are independent. A connection consists of a full duplex data path for records. The path in each direction is independent, there is no requirement that a path be used. Connections are created by IPC OPEN requests dynamically as requested. There is no requirement that connections be predefined to IPC, all connection matching is done on "Tag Strings". Definition is done at IPC OPEN time by matching tag strings. Half-connections with matching strings are connected. IPC data path characteristics: IPC may buffer an arbitrary amount of data internally. The requirements on IPC are: All data sent eventually is received in the order sent. Internal IPC delays are not permanent if no more data is sent. Send complete when IPC has moved the data from the buffer Receive complete when buffer has 1 record or is full. Zero length records are valid (?) (continue flag etc) All IPC requests will eventually be notified unless the task is gone... If a task using IPC terminates (normally or abnormally) all IPC connections are abnormally closed. If a link fails all connections which require that link and have no alternative are abnormally closed. There is no "retry" visible externally, a closed connection indicates that all possible retries failed. IPC externally handles data as if each request were a record. At most one record can be sent with one send request or received with one receive request. If the incoming record is too long for a receiver's buffer, the buffer is filled, RQ#OPTC is set (continued), and the remaining data will be received next. The reverse also is possible, a send can specify OPTION=(CONT) -- if more data after this send is also part of the same record. Close indicates to IPC that no more data is to be sent by this side of the connection. IPC does not close the UCLA/IPC-370 Programming (IPCPROG) Page 4 connection until both sides have issued CLOSE and all data has been delivered. Temp: all data gets delivered on close? Note: A byte pipe mode of operation can be used by specifying CONT on all sends. Note that the receiver's request is only marked complete if either a ending record segment is contained in the buffer, or the buffer is full. If attempting byte pipe mode, omitting CONT on the last send will prevent the receiver from hanging waiting for the end of the (last) record. If data is sent but never received close will hang. This will not stop ABCLS or a cancel/ABEND of either task involved. IPC SVC interface _________________ The IPC SVC is the gateway to IPC. All IPC requests are made by issuing this SVC. The IPCREQ macro will generate the parameter list required by the SVC and optionally invoke it. If necessary the IPCREQ macro can be used to generate a DSECT of the parameter list (RQ#) and the list can be built or modified directly. The IPC SVC requires register 1 contain the address of the RQ#. IPC always uses 32 bit addresses and lengths, thus all parameters passed to IPC MUST provide 32 bit values. Under MVS/370 this means that all high bytes of addresses and lengths must contain zero. This includes the address of the IPCREQ list passed to the IPC SVC in R1. MVS/XA: The IPC SVC can be issued from 31 bit mode as long as all the parameters fit in 24 bits (and the high bits are zero -- IPC still checks). IPC is still internally running in 24 bit mode. The IPC SVC may destroy the contents of R0, R1, and R15. R14 is sometimes used by the IPCREQ macro. On return from the IPC SVC R15 does NOT contain a return code. All IPC requests are asynchronous, a completion code is placed into RQ#CC when the request is complete. The field RQ#TS is X'00' when a request is complete and X'FF' when incomplete. Once a request has been issued, no changes may be made to the RQ# until it is complete. If any changes are made the results are unpredictable. This may include lost notifies, ABENDs, and other problems. Note: The IPC SVC is currently a type 1 SVC. IPC restrictions ________________ - Checkpoint-restart is not supported by IPC. If any process using IPC is restarted the results are unpredictable. UCLA/IPC-370 Programming (IPCPROG) Page 5 Note: In the future IPC may prevent use of checkpoint-restart in the same memory. OAC: OAC does not support use of checkpoint-restart. - IPC only supports one job-step per address space using IPC. Any requests issued by other job-step's in the same memory are failed. IPC validity checking _____________________ IPC associates with each half-connection (one end of connection) an OS task and a protect key. Only that task may make requests for that connection, and only when running with that key. IPC always uses the key from the PSW, never the task key (TCBKEY) in validity checking. Note: interrupt routines run in TCBKEY if the requesting key is >= 8 (non-system key). All IPC references to user storage are validity checked. Most are made in the users key allowing the hardware to perform the validity checking, all the rest are made by one routine which preforms it's own validity checking also using the users key. IPC tag string ______________ tag string format _________________ The TAG string supplied in an IPC OPEN request names the half-connections for the requested connection. This section describes the current IPC OPEN processing. This is subject to change, both by changes to IPC, initialization options, and IPC installation exits. The IPC tag string consists of two groups of sub-strings separated by periods. The first group names the other half-connection process, the second group names the current half-connection process. Each sub-string may only contain the upper case letters A-Z, blank, question mark '?', and the national characters '$#@' and is limited to 8 characters in length. The sub-strings in each group progress from local to global in the IPC network. ../.. Sub-strings which are not supplied are defaulted by IPC using the initialization options and the installation exits. The and sub-strings are currently forced to context dependent values. is set from the TIOT jobname value at OPEN time, is set to an installation dependent value. UCLA/IPC-370 Programming (IPCPROG) Page 6 IPC will accept at least 56 bytes of tag string. Specification of anything past is optional, with "your" fields defaulting to wild characters (installation option), and "my" fields defaulting to the current context. Note: IPC will fail any OPEN request with an invalid tag string. This could be due to invalid characters in the sub-strings, sub-strings too long, or other invalid syntax. parsed tag string format ________________________ The tag string is parsed by IPC and it is this "parsed" format which is returned when an IPCREQ QTAG request is made. The tag string parsed format consists of the following: length description 1 length of rest of "parsed" format string 1 length of "your" part n * AL1(sub-str len),C'sub-str' 1 length of "my" part n * AL1(sub-str len),C'sub-str' For example the string 'YTAG.YJOB/MT.MJ' could be parsed into: AL1(26,11,4),C'YTAG',AL1(4),C'YJOB',AL1(0) AL1(13,2),C'MT',AL1(2),C'MJ',AL1(6),C'DEFNET' This format is only encountered in the results of IPCREQ QTAG. tag string matching ___________________ IPC compares the substrings with the corresponding substrings of all other half-connections not yet matched. If a match is found a connection is established between the matching half-connections. No further searching is done. It is undefined which order the unmatched half-connections are searched, and if more than one match is possible IPC only guarantees that a match will occur. The character '?' will match any character except itself. Note: This tag definition anticipates support for loosely coupled systems. At this time the best strategy is to omit the network level tag information and use the installation defaults. Future: The length of a sub-string may be extented beyond 8 characters and the length of the total TAG string may be extented beyond 64 bytes. Lower case characters may be allowed (or translated?). More than 3 sub-strings may be required in the future for large or complicated networks. UCLA/IPC-370 Programming (IPCPROG) Page 7 IPC may make use of other characters as delimiters or other special functions. Some might be reserved for use by installation exits. CID (connection id) ___________________ The connection id is the handle which identifies a specific half-connection (one end of a connection) to IPC. The CID must be specified in RQ#CID for any IPC request which refers to an existing connection. IPC will set RQ#CID before control is returned when a request creates a new connection. The CID is a 16 bit number. IPC guarantees that zero will never be a valid CID, all other values are possible CID values. There is no relation between CID's -- both ends of a connection may have the same or different CID's. IPC insures that each CID is unique within it's context and refers to only one end of one connection. Note: Currently the CID assignment is local to an address space, however attempting to use a CID which does not belong to your task/key will fail. Programs must not depend upon CID's being unique in an address space, as this may change. A connection may be closed before the open completes since the CID is available once IPC returns from the open request. Future: There may exist IPC requests which operate over groups of connections, these will set RQ#CID to the specific connection operated upon. IPC request completion codes ____________________________ When an IPC request completes, IPC sets RQ#CC with a completion code, and RQ#RSN with an internal IPC reason code. In comparison with some other systems, IPC has very few possible completion codes. The completion codes in RQ#CC are: CC error level results 0 no error successful request 1 temporary (currently never used) 2 request request failed 3 connection connection failed (or closed) 4 IPC IPC failure (or IPC down) 5 user user logic error Each of the IPC completion codes (above) has one or more reason codes. These reason codes are for debugging only, they are subject to change and must not be coded into programs. The IPCSTAT subroutine may be used to generate a human readable message describing any IPC return/reason UCLA/IPC-370 Programming (IPCPROG) Page 8 codes, only IPCSTAT will be updated when the reason codes change. IPCSTAT's messages are also subject to change, they are for human use only, programs are not to try matching the message text. Note: Here are some sample types of completions which would produce each type of completion code from IPC. These are samples, not specific cases, to give an idea of the intent of the completion codes. These are not specific codes. 0 - successful send, receive, open, close 1 - internal IPC storage shortage (note that this is unlikely unless some program in the memory is in a loop making IPC requests). (this is currently treated as cc 5 - user logic error). 2 - invalid request code, not-authorized for auth request 3 - connection closed (by either side), other side terminated (without close complete), ABCLS completion. 4 - IPC emergency shutdown or not up. IPC program/logic error in memory. (will show as connection error's to other side, and will take IPC SDUMP's + logrec records) 5 - request not complete, invalid connection id, (for now - IPC storage shortage) IPC Abend codes _______________ IPC SVC number in hex. Fnn - IPC SVC not installed (normal MVS abend code) Enn - all IPC issued abend codes On any Enn abend code: R6 - address of user IPCREQ causing problem R7 - abend reason code 001 - @ RQ# > 16 meg 002 - RQ# length invalid 003 - previous request using this RQ# not complete 004 - RQ# inaccessible to IPC (request) 005 - RQ# inaccessible to IPC (notify) 006 - ECB or CS area inaccessible to IPC (notify) 007 - invalid notify code in RQ# or CS area (notify) 008 - RQ# inaccessible to IPC (open) (request) - error occurs when request is made. (notify) - error occurs when IPC attempts to notify request. Note: When IPC is passed invalid parameters it may abend the requester or complete the request with error (RQ#CC = UCLA/IPC-370 Programming (IPCPROG) Page 9 5 user logic error). The current choice is to notify if possible, this might change. OAC: The IPC SVC number is X'E6' = 230. IPCSTAT service routine - IPC reason codes __________________________________________ IPCSTAT is a collection of subroutines which provide assistance in debugging programs using IPC. IPCSTAT can: * Generate human readable messages explaining IPC completion and reason codes. * Format RQ# (IPC parameter lists) Question: should this service be part of the IPC SVC, or be a execution time loaded module? IPCSTAT parameter list (and macro to generate it)???? Temp note: IPCSTAT for now is an external routine. This module must not be link edited into programs as it is updated with IPC changes. Future note: IPCSTAT also can generate a list of all IPC completion and reason codes with message text. // EXEC PGM=IPCSTATL //STEPLIB DD DISP=SHR,DSN= //SYSPRINT DD SYSOUT=* //SYSUDUMP DD SYSOUT=* IPCREQ MACRO The IPCREQ macro is the only IPC external macro. It is modified at installation time to generate the correct SVC number for the installation. All IPC requests are made with the IPCREQ macro. This macro can also be used to generate DSECTs for the IPC parameter list or the IPC CS notify area.