Messaging system6289392Abstract A messaging system for passing messages between calling programs and called programs wherein all messages are passed within a defined message block and via a message interface. The message interface has memory for storing, for each called program, an identifier and a program interface. In use, the message interface receives a message block from a calling program containing an identifier, associates the identifier with a particular called program and a particular program interface, and sends a message block to the particular called program utilizing the particular program interface. Claims What is claimed is: Description BACKGROUND OF THE INVENTION
Capsule Table: contains one row per capsule.
COLUMN NAME TYPE NOTES
CAPSULE_NAME Char(5) Checked against Program-Id
AVAIL_FOR_USE Char(1) `N`, `W`, `Y`
CAP_SECRTY_TYPE Char(1)
OWNER_USERID Char(8) Used when routing calls in Test
Harness
UPDATED Timestamp
UPDATED_USERID Char(8)
CAPSULE_DBMS Char(8)
CAPSULE_ROUTER Char(8)
ENTITY (OENT) 15 One row for each version of each entity. (Note that an entity may refer to more thane one DB2 table. Also indexed on Entity_Abbrev, Entity_version (enforced unique), and Entity_Name, Entity_Version (enforced unique)
COLUMN NAME TYPE NOTES
ENTITY_NUMBER Smallint Never changes
ENTITY_VERSION Smallint
ENTITY_NAME Char(18) Meaningful unique name, generates
Entity Name in Entity Block within
application.
ENTITY_ABBREV Char(4) Used to distinguish columns of the
same names occurring in different
entities, and also in the construction
of Method Names. This should be
unique within ODICT.
DB_PARTITION Char(2) Valid DB partition code
CAPSULE_PREFIX Char(1) Prefix used for Internal Method calls,
currently `I`
CAP2CAP_PREFIX Char(1) Prefix used for Capsule to Capsule
calls, currently `C`
AVAIL_FOR_USE Char(1) `N` (initially), `Y`
UPDATED Time-
stamp
UPDATED_USERID Char(8)
METHOD (OMTH) 16 Generally one row per method version released, although ODICT synchronisation may introduce more. Each method belongs to one capsule. Once a method has been made available, a new version must be created for any change in the method. Also indexed on Capsule_Name, Method_Name, Method_Version for relation with Capsule table (OCAP).
COLUMN NAME TYPE NOTES
METHOD_NAME Char(30) Constructed according to
standards for naming
methods. First part (Action
Type) is `GET`, `GETM`,
`MOD` etc. Next part is the
Entity Abbreviation. See
XCALL Programmer's Guide
Appendix B for full details.
METHOD_VERSION Smallint
METHOD_TYPE Char(2) `RR`, `RU`, `UU`, `RL`
depending on the Action Type
METHOD_TYPE_STATS Char(1) `M`, `I`, `D`, `R` depending
on Method_Type
CAPSULE_NAME Char(5) OMAP Foreign Key
DEF_TUPLES_BACK Smallint Default number of items
returned. This will depend on
the Action Type, i.e. 1 for a
GET-type method, >1 for
a GETM or GETN.
MAX_TUPLES_BACK Smallint Maximum number of items
returned. This will never be
less than Def_Tuples_Back.
AVAIL_FOR_USE Char(1) `N` (initially), `Y`. Note that
`Y` inhibits method deletion
and permits a new version to
be input. `N` allows input
of Derived Fields.
METHOD_DESCRIPTION V240 Narrative outline
UPDATED Time-
stamp
UPDATED_USERID Char(8)
ENTITY COLUMN (OCOL) 17 One row for each column, whether DB2 or derived, used in current or previous entity version. Defines the attributes of each column.
COLUMN NAME TYPE NOTES
ENTITY_NUMBER Smallint
COLUMN_NUMBER Smallint Column no. within the Entity. This
will not change, even if underlying
table structures do. Deleted columns
could at a later date be reused.
COLUMN_TYPE Char(8) CHAR, DATE, DECIMAL,
INTEGER, SMALLINT, TIME,
TIMESTMP, VARCHAR
COLUMN_LENGTH Smallint Used to calculate offset sizes in
Entity Block
COLUMN_SCALE Smallint No. of Decimal pieces
COLUMN_NULLS Char(1) `N`, `Y`
DELETED Time- Nulls allowed
stamp
DELETED_USERID Char(8) Nulls allowed
DB2 TABLE (OXTB) 18 Shows Entity implementation by DB2 tables. (An Entity may be implemented by more than one DB2 table) Also indexed on Base_Capsule for relation to Capsule able (OCAP). There mey of course be no tables for a given Entity, e.g. for (TRADE MARK OF IBM) data.
COLUMN NAME TYPE NOTES
TABLE_NAME Char(18)
ENTITY_NUMBER Smallint OENT Foreign Key
ENTITY_VERSION Smallint OENT Foreign Key
BASE_CAPSULE Char(5) OCAP Foreign Key. Nulls allowed.
Will always refer to an existing
Capsule.
TABLE_PREFIX Char(4)
CREATOR_ID Char(8) System identifier, e.g. COSMOSS,
TRAINING, OMS
(ODRV) 19 One row for each derived field (a field which does not physically exist on a DB2 table, but which is either calculated or held on some other DBMS, e.g. (TRADE MARK OF IBM)). This information could have been held as an indicator column on OCOL, but it was felt that it may be necessary to hold more information later. Each row here will have an equivalent row on ENTITY COLUMN (OCOL)
COLUMN NAME TYPE NOTES
ENTITY_NUMBER Smallint OCOL Foreign Key
COLUMN_NUMBER Smallint OCOL Foreign Key
INTERFACE (OINT) 20 Defines the interface block for each method version, i.e. the columns used by that version and whether they are mandatory for input or available for output. This is the Many-to-Many relationship between Entity Column and Method Version. Also indexed on Entity_Number, Column_Number for relation with Entity Column table (OCOL). Method_Name, Method_Version is used for `Many` end of relationship with Method table (OMTH)
COLUMN NAME TYPE NOTES
METHOD_NAME Char(30) OMTH Foreign Key
METHOD_VERSION Smallint OMTH Foreign Key
TYPE_IFACE Char(1) Whether field is mandatory in this
method: `A` output (A)vailable,
`M` - input (M)andatory, `O` - input
(O)ptional
ENTITY_NUMBER Smallint OCOL Foreign Key
COLUMN_NUMBER Smallint OCOL Foreign Key
DB2 TABLE COLUMN (OSHD) 21 Lists columns in current version of DB2 tables
COLUMN NAME TYPE NOTES
TABLE_NAME Char(18) DB2 table name
COLUMN_NAME Char(16) Column name within Entity (supplied
via relationship with OXTB table)
DB2_COLUMN_NO Smallint
ENTITY COLUMN TO ENTITY MAPPING (OMAP) Lists the columns by name supported by each version of each entity and thus implements the many-to-many link between Entity and Entity Column. Holds a complete set of rows for all columns defined for use with the entity version, including columns no longer in use but required by old method version calls. ENTITY_NUMBER and COLUMN_NUMBER point to OCOL row holding details of the column. LAST_ENT_VER_USED holds ENTITY_VERSION of last entity version using this column. This table is used by the XCALL precompiler to build the Entity Block for a given Entity Version. It also provides a name for the column, which can then be used in constructing a field name for use in an application. Also indexed on Entity_Number, Column_Number for relationship with Entity Column table (OCOL). Entity_Number, Entity_Version used for `Many` end of relationship with Entity tabled (OENT).
COLUMN NAME TYPE NOTES
ENTITY_NUMBER Smallint OCOL Foreign Key, OENT Foreign
Key
ENTITY_VERSION Smallint OENT Foreign Key
COLUMN_NAME Char(20)
COLUMN_NUMBER Smallint OCOL Foreign Key. This is the
Entity column number (as opposed to
DB2 column no.) i.e. as specified
in OCOL
CAPSULE-ENTITY (OXCE) Cross-references capsules and entities. Also indexed on Entity_Number, Entity_Version
COLUMN NAME TYPE NOTES
CAPSULE_NAME Char(5) OCAP Foreign Key
ENTITY_NUMBER Smallint OENT Foreign Key
ENTITY_VERSION Smallint OENT Foreign Key
ENTITY-METHOD (OXME) Cross-references method versions and entity versions. NB Primary Index is on Entity_Number, Entity_Version, Method_Name, Method_Version. Also indexed on Method_Name, Method_Version, Entity_Number, Entity_Version. Note that Methods can process more than one Entity as well as Entities being processed by more than one Method
COLUMN NAME TYPE NOTES
METHOD_NAME Char(30) OMTH Foreign Key
METHOD_VERSION Smallint OMTH Foreign Key
ENTITY_NUMBER Smallint OENT Foreign Key
ENTITY_VERSION Smallint OENT Foreign Key
XCALL Runtime System The actions of the XCALL runtime system can be sumarised as follows: Transaction makes Method call XCALL `collects` IRB data from Transaction Entity Blocks XCALL accesses Linear Dataset to find the capsule to call IRB data `presented` to Capsule Capsule processed call XCALL `collects` IRB data from Capsule's Entity Blocks XCALL returns data to Transaction's Blocks The XCALL Runtime System will now be described in greater detail. Back End The lowest level layer of XCALL runtime, responsible for the call to the selected capsule, has the following functions:
Request to Capsule Request to XCALL
Pass XCIB and Request Establish Session on first call
Message to Capsule
On return Pass XCIB and Send XCIB and Request
IRB or Response Message then wait
Message back to On return receive XBIC and
Control and Continuity Response Message or IRB
Capsule Call A `level 2` call, also known as a Capsule to Capsule call. If a capsule calls a method which is in a different capsule it needs to set up information in a separate XCIB. To avoid name clashes this is called the XC2B, and X2-prefixes rather than the XC-prefixes in the normal XCIB identify fieldnames correctly. It is also necessary to store more trace information and to keep track of further calls. Control and Continuity(C/C) The second level layer of XCALL run time, has the following functions: Keeps track of Capsules called. Records status of current call. `Owns` DBMS threads/Run Units Identifies appropriate Back End for remote Capsules Passes request to Back End Manages explicit Commit Requests--sending commits to remote XCALLs as necessary. Front End The first level layer of XCALL run time has the following functions:
Request From Appl Request From XCALL
Locate the Capsule that Receive XCIB and Request
supports the method Message
Pass control to C/C Check this is the right
place the pass to C/C
On return present data to On return send XCIB and
caller Response Message to
calling XCALL
Entity Block Block This is the collective name for the Capsule Entity Blocks allocated at run time. An area of store is allocated to contain the largest amount of data expected back from the method call within the capsule and its size will be the total size of all capsule entity blocks managed by this capsule, multiplies by the number of rows requested. IRB The Intermediate Request/Response Block. This is the data area that is passed to and from a Capsule. It comprises the input or output data firelds concatenated to minimise space, i.e. with no account taken of Entity structure. Local Call A `traditional` call to a capsule on the local node: XCALL can call the capsule directly from back end processing Map 1, Map 2A and Map 2B Data areas which hold details of the mapping of input and output data to and from the IRB. Remote Call A call to a remote capsule. This requires more complex processing and control. (Release 3.0 on). Transaction Call A standard call, using XCIB fields as control. The precompiler puts in the call to the appropriate entry point. It also calculates the IRB size as the larger of (rows requested*output row length) or (input rows supplied*input row length). The resulting value goes into XC-IRB-SIZE. Map 1 and Map 2A data will be preset by the time the call takes place. XCCB Control and Continuity Block. XCCT XCALL Capsule Table. This is loaded from LDS tables and holds details of each Capsule, including capsule status, ownership and location. XCIB The XCALL Interface Block. This is the means of communication between the various XCALL runtime components and calling processes. It contains such information as the Capsule and Method to be called, trace information, addresses of Enrtity Blocks and details on mapping the IRB to Entity Blocks. XCMT XCALL Method Table. This is loaded from LDS tables and at run time XCALL searches it with the method name as key, determining the capsule that contains it. XCMT also retains status and rows requested/returned details for the method. XCNT XCALL Node Table. This is loaded from LDS tables and holds details of each node. The relationship between the control block structures utilized in XCALL is shown in FIG. 5. XCALL STRUCTURE Entry points There are various entry points to XCALL, based on the environment in which the call takes place. These are permutations of: Transaction call/Capsule call (i.e. Capsule to Capsule); CICS Foreground/CICS Background/Batch; Local/Remote. The three layers, Front End , Continuity & Control, and Back End In each case, the entry points are supported by three layers of processing: Front End, Control and Continuity, and Back End, before the requested capsule is actually called. Caller Processing Precompiler-generated code loads Map1 and Map 2A data for mapping Caller Entity Block data to the IRB, calculates the size of the IRB and stores this and trace information in XCIB. Before calling the entry point input data is transferred to the Caller Entity Block field(s). After each call to XCALL, the application must check the return code and behave accordingly. After control has been returned, the trace information is updated and any requested data put into the nominated output fields. Entry Point The main function of the entry point is to get addresses of the entity blocks that have been passed as parameters to the original call. Based on the number of significant parameters passed, entries in XCIB (XC-EM-ADDR) are set to these addresses. In addition, checks on things such as the environment take place. Front End. This receives requests from application programs (and from remote systems on behalf of a remote application). It captures appropriate security information and maintains a trace of the calls received. It is also responsible for mapping the IRB to the Caller Entity Block(s). When XCALL is called, the front end acquires storage from the operating system by executing a GETMAIN for the IRB, using either a CICS GETMAIN or an Assembler equivalent for Batch. The size of the space obtained is then held in XC-CURRENT-IRBSIZE. On a subsequent call, the XC-IRB-SIZE is set again by the precompiler inserted code in the caller. The front end compares this with XC-CURRENT-IRB-SIZE. If the current size is greater than or equal to the size requested no further action is necessary, otherwise the current space is released with FREEMAIN and a new IRB obtained with GETMAIN again. Various administrative and security actions now take place to: Increment the XCIB trace pointer and move the current request information into the new trace entry; Set the XCIB caller's node and task number fields; Use the XCMT to check the method name is valid, get the capsule name (taking account of possible use of the Test Harness) and that the capsule (if a local one) is available for the type of request (if not set the appropriate SWE code and return to the caller); Get the node from the XCCT and set the node id into the XCIB; Get the security information (userid from middleware) and perform a checksum to generate a security check field; Create the primary XCCB on the first call for a task. Store XCCB details: addresses of run time tables etc., and capsule to capsule call information as appropriate. Front End then stores the request data from the caller and puts it into the IRB, calling Assembler routine XC700UAS to do this (see the section below on Map 1 and Map 2 Processing for a detailed description). XCIB details are stored in XCCB. After calling Continuity and Control, Front End deals with capsule to capsule call processing, copying details back into the appropriate XCIB fields. It then calls Assembler routine XC703UAS which is essentially XC700UAS in reverse, to transfer data from the returned updated IRB into the Caller Entity Block(s). If Commit processing is required, it takes place here, otherwise control passes back to the entry point, and thence to the caller. Control and Continuity. This maintains details of the capsules that an application calls. It uses the XCCT to pass requests to the appropriate capsule. It is responsible for handling Backouts and Comrnits explicitly requested by the caller or Backouts caused by error handling requirements. Backout/Commit calls invoke checking of DBMS type against each capsule so far called by this transaction, before the requested action takes place. If the call is not a Backout or Commit, then C&C proceeds assuming a method call. If the capsule called is not in the XCCB, the XCCT is used to locate the system the capsule resides in and the type of back end (communications access method or local) that should be used to talk to the remote system. Update accesses are checked, and then call statistics updated. If call limits have not been exceeded, C&C passes control to Back End. On return from Back End, C&C checks that the XCIB has not become corrupted and updates XCCB statistics for this capsule. If the return SWE code is 8 or higher then backout occurs. Finally, control is returned to Front End. Back End Calls the appropriate capsule, which may be the Stable version or a Working Copy or a Stub (these last two are when testing). It stores the local part of the XCIB into the save area in the XCCB, and passes control to the capsule. On return, it checks that nothing has been corrupted and that the rows returned value is OK. Before restoring the local XCIB it builds the IRB with the data to be returned to the caller, using Assembler routine XC702UAS (see Map 1 and Map 2 Processing below). Control then returns to C&C. Capsule Processing The precompiler generates code to store capsule details in the XCIB and check that the method is valid and that the required message data has been passed. It then unravels the IRB data presented, using Assembler routine XC701UAS. If this is the first time this capsule has been called then XC704TCS is used to get store for the Entity Block Block. This consists of all the Capsule Entity Blocks, occurring as many time as necessary (XC-ROWS-REQUESTED). After setting the Capsule Entity Block addresses into the XCIB the capsule then performs the requested method, updates the XC-SWE-CODE and XC-ROWS-RETURNED fields in XCIB, after which control returns to the back end. MAP 1 AND MAP2 PROCESSING Data areas managed by Map 1 and Map 2 As mentioned above, data is passed around the various parts of XCALL using three areas (excluding any other source or destination data fields): The Caller Entity Block which is the tailored block comprising just those fields referenced by this caller. This is built up on a Caller basis: an entity block may well contain fields that are there as a result of several different calls referencing different fields. Additionally, if calls indicate that arrays are required then the OCCURS clause will be the maximum for that entity found by the precomplier. In these ways the entity blocks are no larger than necessary. The Capsule Entity Block which is the full entity block comprising all fields, whether database or derived, defined as being not deleted for this version of the entity. The Intermediate Request/Response Block (IRB) where data is packed and unpacked for each individual call. Control of the various moves required is by map tables which identify and locate the source and destination fields. There are three such maps MAP 1 contains entries each part of which identifies input and output data respectively: effectively there are two lists, one for input and one for output. The precompiler generates the Entity and Field Numbers for each field that is mentioned in an INPUT or an OUTPUT clause in a particular XCALL call. There is no implicit relationship between the input and output specifications: there may for example be only one significant input entry and many output entries. An entry set to zero indicates the end of each list. There is a Map 1 entry for each column referred to in a given call i.e. in the Input and Output clauses. Each list is terminated by zeroes. There is no relationship between the input and output elements in each occurrence: there may be only one significant input entry and several output entries, for example. The values in this (and Map2 format A) are loaded by precompiler generated code. MAP 2 version A links the IRB data to the caller entity block. There is a one-to-one relationship between entries on this map and those on Map 1. As in Map 1, each entry has an Input and an Output part. No particular indication of the end of each list is required: this can easily be derived from Map 1. The details are loaded by the precompiler, and XCALL saves values before passing control to the capsule, restoring them when the IRB has been rebuilt with returned data. MAP 2 version B shares the same physical data area, values being loaded in by precompiler-generated code executed within the capsule. Whereas Map 2A is concerned with thetaller entity block, Map 2B links the IRB data to the Capsule Entity Block. There is thus one entry for each field in that entity version not marked as deleted. Map 1 is still needed: data movement between the IRB and the Capsule Entity block is dependent on the existence of a significant Entity/Field number combination on Map 1 matching the equivalent entry on Map 2B. Example of MAP1/MAP2 Processing In this example the manipulation of input and output is demonstrated for a simple method call which receives supplies two input keys, and receives a row back for each. Although somewhat simplistic, careful study of the data at each stage should reveal the details of IRB/Entity Block interaction. The entity--PARROT--has the attributes shown in the table below and is described in the dictionary (ODICT). The particular method call requests only a subset of the available columns: the others are included for illustration. Entity Details (from ODICT) Entity Number 500 Version 1 Entity Name PARROT Entity Abbreviation PARR Column Details
Col no Name Type Length
1 CODE Char 4
2 NAME Char 20
3 SIZE Smallint 2
4 COLOUR Char 8
5 FEED Char 10
6 WEIGHT Smallint 2
NB Type Char=Character, Smallint=small integer (binary in the range 1-32767) XCALL statement XCALL GETN-PARR
INPUT (PARR-CODE FROM WS-PARR-CODE(*))
OUTPUT (PARR-CODE INTO WS-PARR-CODE(*);
PARR-NAME INTO WS-PARR-NAME(*);
PARR-WEIGHT INTO WS-PARR-WEIGHT(*))
ITEMS(2,2)
END-XCALL Capsule View of the Data (Entity Block) Consists of a number of Occurrences (Rows) of all of the attributes of the entity (columns)
Column Column
Column Name Type Length
I-PARR-CODE Char 4
I-PARR-NAME Char 20
I-PARR-SIZE Smallint 2
I-PARR-COLOUR Char 8
I-PARR-FEED Char 8
I-PARR-WEIGHT Smallint 2
(Total length of row: 44 bytes) Caller View of the Data (Entity Block) Consists of a number of Occurrences (Rows) of all of the attributes of the entity (columns)
Column Column
Column Name Type Length
I-PARR-CODE Char 4
I-PARR-NAME Char 20
I-PARR-WEIGHT Smallint 2
(Total length of row: 26 bytes) Processing Details Tables updated before XCALL call executed: ##STR1## Caller Entity Block (assuming ws-fields set up by program)
PARR-CODE PARR-NAME PARR-WEIGHT
##STR2## Processing Front end called: XC700UAS called to move data from Method EB to IRB: string each input field on Map1 (processing stops when a zero-filled field is met) into the IRB. For input arrays, stringing is on a row-by-row basis. The fields used in calculation are the offset and length within the caller entity block, held in Map 2A, and the address of the entity block (originally passed as a parameter to the original call to XCALL) and the length of the entity block row held in XCIB). The offset is from the beginning of the row, which is incremented by the row length for subsequent rows. IRB CONTENTS ##STR3## IRB data used to update Capsule entity block: done by XC701UAS, using Map 1 and Map 2B details Map 1 contaings the Entity and Field no of input data. From Map 2B data it is possible to determine the length of each input field, matching the Entity and Field number with that of the Map 1 entry. From the same Map 2B entry the offset within the full entity block is available. The addresses of the full entity blocks are set up following acquisition of main store. ##STR4## Capsule does its work and populates Entity block (assume all fields are marked as available for output: this method call only requires subset)
PARR- PARR- PARR- PARR- PARR-
PARR-CODE NAME SIZE COLOUR FEED WEIGHT
MC01 MACAW 10 BLUE NUTS 25
##STR5## The XCIB will be updated to indicate that 2 rows are to be returned (XC-ROWS-RETURNED set to 2). IRB filled by XC702UAS: Map 1 again tells us which output entity/field combinations are required, Map 2B where they are in the Capsule Entity block: ##STR6## Method Entity Block updated by XC703UAS, using Map 1 and Map 2A, whose values have been restored by Back End processing:
PARR-CODE PARR-NAME PARR-WEIGHT
MC01 MACAW 25
CK01 COCKATOO 20
The processing performed by the various application and XCALL layers in the execution of a single call to a capsule, are now described with reference to FIG. 6. The four processes, labelled 1, 2, 3 and 4 in FIG. 6 are described first. XC700UAS (process 1 in FIG. 6)--BUILD IRB FROM APPLICATION ENTITY BLOCK(S) Initialise the IRB Header. Start processing at the first input field entry in MAP1, continue until a column number of zero is found or entry 255 is processed. Perform the process once for each input row. Calculate the location to move from by . . . a) Retrieve the address of the beginning of the entity block from the XCIB entity details array entry pointed to by the current Map2a entry. b) Subtract 1 from the number of the current row, multiply it by the length of a row (indicated in the entity details array) and add the result to the address retrieved above. c) Add to the result the number of bytes into a row to the start of the field (held in the current Map2a entry). Move the number of bytes indicated in the field length in the current map2a entry from the start address calculated above to the next free position in the IRB. increment the next free position in the IRB by the number of bytes moved. Note that Map2a entry n corresponds to Map1 entry n. XC701UAS (process 2 in FIG. 6)--BUILD EBB DATA FROM IRB Initialise the EBB Header. Process each INPUT Map1 entry in order until an entity number of zeroes is encountered or entry 255 is processed. Repeat the process the number of input rows times. Find the entry in Map2b that matches the entity number & column number for the current Map1 INPUT entry. (Note--both are in ascending column number within entity number order.) Calculate the location to move to by . . . a) Retrieve the address of the beginning of the entity block from the XCIB entity details array entry pointed to by the current Map2b entry. b) Subtract 1 from the number of the current row, multiply it by the length of a row (indicated in the entity details array) and add the result to the address retrieved above. c) Add to the result the number of bytes into a row to the start of the field (held in the current Map2b entry). Move the number of bytes indicated in the field length in the current map2b entry from the next position to be moved from in the IRB to the start address calculated above in the capsule entity block. Increment the next position to move from in the IRB by the number of bytes moved. XC702UAS (process 3 in FIG. 6)--BUILD IRB FROM CAPSULE ENTITY BLOCK(S) This performs the same processing as XC701UAS, but in reverse. The Map1 and Map2b process produces the address to move from in the capsule's entity block(s) and data is moved into the IRB overwriting the input data. XC703UAS (process 4 in FIG. 6)--BUILD APPLICATION ENTITY BLOCK(S) FROM IRB. This performs the same processing as XC700UAS, but in reverse. The Map1 and Map2a process produces the address to move to and data is moved from the IRB overwriting the existing contents of the application's entity block(s). Application--`Normal` Code. 1. The application puts the input data to be sent to the method into the variables mentioned in the right hand side of the INPUT in the XCALL statement. Application--Precompiler Generated Code 2. Update Map1 in the XCIB with the entity and column (field) numbers of the columns mentioned in the left hand side of the XCALL statement (Input and Output). Store entity details in the XCIB. Set the number of input rows supplied and the number of response rows requested in the XCIB. 3. Update Map2a with the entity subscript, offset and length of the columns mentioned in Map1. Update the XCIB with the size of IRB required for this method call. 4. Move the variables mentioned in the right hand side of the INPUT in the XCALL statement into the entity block variables representing the fields mentioned on the left hand side of the XCALL statement. 5. Update the XCIB with details of the program making the call. 6. Call the XCALL program relevant to the environment in which this program is executing. Pass the XCIB, the entity blocks required for INPUT and OUTPUT fields. XCALL--Front End 7. Update the Local XCIB with details of the entity blocks passed. 8. Access the control storage tables that define methods, capsules, nodes and the relationship between them (as defined in ODICT). Validate the method exists and update the XCIB with the Capsule Id for the method and the Node Id for the Capsule. 9. If this is the first call in this `task`--get storage for the XCCB and update the XCIB with details of the calling task. If there is no IRB or the current one is too small--get storage for the IRB. 10. Call XC700UAS. XCALL--XC700UAS 11. Move the input data (as listed in Map1 in the Global XCIB and described in Map2a in the Local XCIB) from the callers entity block(s) into the IRB. 12. Return to Front end. XCALL--Front End 13. Call Continuity and Control Layer XCALL--Continuity & Control Layer 14. Check that the caller has access to the capsule for the required level (read only access etc). Update the call statistics in the method and capsule control tables. 15. Call Back end. XCALL--Back End 16. Save the Local XCIB. 17. Call the Capsule program Capsule--Precompiler Generated Code (XC ENTRY statement expansion) 18. Check that the method name, method version, entity number(s) and entity version(s) passed in this call are valid (as defined in ODICT and RECEIVE statements when the capsule was precompiled). 19. Call XC701UAS. XCALL--XC701UAS 20. Check that the current EBB size is sufficient for the current call. If not update the XCCB with the size of EBB required, set the return code and return to the capsule (i.e. continue at 23 below). 21. Set the addresses) of the entity block(s) within the EBB in the Local XCIB. 22. Move the input data (as listed in Map1 in the Global XCIB and described in Map2b in the Local XCIB) into the capsules entity block(s) from the IRB. 23. Return to the capsule. Capsule--Precompiler Generated Code (XC ENTRY statement expansion) 24. Check the return code. If EBB was not big enough--call XC704TCS otherwise continue at 28 below. XCALL--XC704TCS, 25. If there is an existing EBB release the storage. Acquire storage for an EBB of the size indicated in the XCCB. 26. Return to the capsule. Capsule--Precompiler Generated Code (XC ENTRY statement expansion) 27. Call XC701UAS. Continue at 20 above. Capsule--Precompiler Generated Code (XC ENTRY statement expansion) 28. Pass control to the specified Method code. Capsule--Method code 29. Process the input data in the entity block(s) and create response (output) data in the entity block(s). Update the XCIB with the number of rows returned. 30. Return to XCALL XCALL--Back End 31. If the capsule has returned data--call XC702UAS. Otherwise continue at 34 below. XCALL--XC702UAS 32. Move the output data (as listed in Map1 in the Global XCIB and described in Map2b in the Local XCIB) from the capsules entity block(s) to the IRB. 33. Return to the Back End. XCALL--Back End. 34. Restore Local XCIB from the saved copy taken at 16 above. 35. Return to Continuity & Control XCALL--Continuity & Control 36. Update the response statistics in the method and capsule control tables. 37. Return to Front End. XCALL--Front End 38. If the capsule returned data--call XC703UAS. Otherwise continue at 41 below. XCALL--XC703UAS 39. Move the output data (as listed in Map1 in the Global XCIB and described in Map2a in the Local XCIB) to the callers entity block(s) from the IRB. 40. Return to Front end. XCALL--Front End 41. Return to Application. Application--Precompiler Generate Code 42. If the capsule returned data--move the output data from the entity block(s) to the variables mentioned on the right hand side of the INPUT in the XCALL statement. Application--`Normal` Code 43. Process response--make further XCALLs etc. This example demonstrates how the use of the XCALL messaging system has allowed version independence between the transaction and the capsule. The transaction view of the data in entity 1 and 2 is of entity 1 having variables A to D and entity 2 having variables E and F. The capsule's view of the data is that entity 1 has variables A to D but entity 2 has variables E to G. This may for example arise if an additional variable G has been added to the database (which is accessed via the capsule), which the transaction is unaware of. This may for example occur if variable G is added to the database after the transaction has been written. Given these differing views of the data between the transaction and the capsule, if XCALL were not used, i.e. if a normal linkage between the transaction and the capsule was used, a problem would be encountered when entity 2 is accessed. As this entity is read, when E.sub.2 is reached the capsule would actually access F.sub.2 rather than E.sub.2, and E.sub.2 rather than G.sub.1. Thus the incorrect data would be passed back to the transaction. As described above, by utilizing XCALL and an intermediate IRB, the transaction and the capsule can each have their own view of the same entities and yet consistently and correctly access these entitities by communicating their views of the data via MAP2a and MAP2b to XCALL. REMOTE CALL PROCESSING In XCALL, if the control and continuity layer detects that the request is for a capsule on a remote machine, instead of calling the standard back end to do the capsule call, it calls a new back end. The new back end will have to pass the request to the remote system. Instead of directly calling a capsule on the remote system, the new back end will call a new XCALL server program on the remote system. This also does static links to three programs, the front end, the control and continuity layer, and the back end. In this new server, only the front end is new. If control is received from a remote system, the XCIB will be all that is received initially (at least by XCALL if not the system). Based on the capsule details held locally, it will acquire storage for the request and response blocks and update the local portion of the XCIB. The following checks are made before control is passed to the next layer. i) If this is a new local task, save the calling task number. If not check that the task is the same. ii) Check that the capsule is local and perhaps check that a routing by key agrees with the local routing table. iii) Perform local security checking against remote system and userid. Check the security check field is correct. When the request was from a remote system, it is the front end that sends the updated XCIB and the appropriate IRB and response blocks back to the requester's system. The RLEN fields in the response blocks will indicate if and how much data should be sent for each of them. When all appropriate data has been sent, it will free the storage the blocks occupied (apart from the XCIB and XCCB probably) and wait for the next request.
|
Same subclass Same class Consider this |
||||||||||