For simplicity, protocol requirements of individual applications are the application's responsibility. The system also (cont.) supports user-initiated cancellation of the dialog, clearing the "stack". This is basically consistent with the concept (cont.) that any transaction dialog under CICS can be interrupted at any time due to the nature of pseudo-conversational (cont.) programming, VTAM, or hardware errors. ## Implementation and Use The Attach/Detach facility operates much in the same manner as the MAGEC "Fetch Function" facility. Unlike a fetch (cont.) function, when an application attaches another application, the requesting application's usable TWA is saved before (cont.) entering the other application program. Upon returning from the attached application, the original TWA is restored to (cont.) its state as it was when saved immediately before the attach was done except as noted below. In order to invoke an (cont.) Attach, the application program uses a sequence of code as follows:  *== This is often done in %PFKEYM or %PFKEYL    *== passing data via SERRMSG (optional)           IF ( you wish to attach to another function )              MOVE requested function TO SFUNCT              MOVE requested key TO SKEY              MOVE passed-information TO SERRMSG              GO TO AA760-ATTACH.   As you can see from the above, invocation of this facility is much like using the FTH-FUNCT logic. The desired function (cont.) code and key value are placed into the standard screen fields as if they had been typed into those fields by the (cont.) operator. The return from the attached function to the (next higher) invoking function is also quite similar to the FTH-FUNCT (cont.) coding, except that the returning function need not know the identity of the attaching function. An example of the (cont.) required code is as follows:  *== This is often done in %PFKEYM or %PFKEYL    *== passing data back via SERRMSG (optional)             IF ( you wish to detach )                MOVE return-information TO SERRMSG                GO TO AA770-DETACH.   This sequence instructs the Attach/Detach service module to return to the next highest level, i.e.: restore the TWA of (cont.) the invoking function and give control back to that function (at the top of the Procedure Division, not the (cont.) "next-sequential instruction"). In order to pass information from task to task, the system requires the ability to pass parameter information and (cont.) retrieve the returned information. To accomplish this, the Attach/Detach facility uses the standard MAGEC screen fields (cont.) as communication areas. We have already discussed the use of SFUNCT and SKEY in the examples above. In addition, SCOMPL (cont.) is used by the attach/detach facility to provide information about the function being performed. This field has a (cont.) structure as follows:          05  TWA-SCOMPL-DATA.                07 TWA-SCOMPL-ATTDET PIC X(03)                07 TWA-SCOMPL-FUNCT PIC X(06)                07 TWA-SCOMPL-KEY PIC X(31)   The value of these fields depends on the last type of request made; i.e.: if an Attach was done then the first field (cont.) contains the literal "ATT". After a Detach it contains the value "DET". The remaining fields contain the last function (cont.) and the last key processed by the program requesting the Attach/Detach service. This information may be used by your (cont.) program to determine the validity of a particular dialog, i.e.: perhaps only certain programs should attach certain (cont.) other programs. The SERRMSG field is used as a communications area between functions. Note that communications is optional, not (cont.) mandatory. This 240-byte field may be structured in any manner required by the participating applications. To do so, (cont.) the applications should contain an area with the desired breakdown or definition and should MOVE SERRMSG to (and from) (cont.) that area. It is up to the application designer to specify the desired definition for this area. There are two (cont.) recommendations that are made with respect to this area: 1. Place into the beginning of the area something that can be used as a recognition code to indicate the structure of (cont.) the area. A good code might be the function code of the program providing the service. This should be validated upon (cont.) entry by the attached or detached program to insure the expected structure is received. 2. Refrain from using any binary or packed decimal fields in this area. There may be a possibility that an (cont.) Attached/Detached program will merely send a screen without reformatting the SERRMG area. Packed or binary fields will (cont.) result in invalid characters in the data stream sent to the terminal, and the screen will not transmit (cont.) correctly. The value of SERRMSG is passed "down" and "up" the dialog by the Attach/Detach facility. Please note that if you wish (cont.) to retain the original value of this area, or SCOMPL for that matter, before attaching another function you should move (cont.) this field to an area defined in the %DATADEF customization point or, alternatively, you could merely rebuild it from (cont.) the original information (usually values in the %LITERAL customization). Although this area is somewhat limited in its (cont.) size (240 bytes), it can be used quite effectively. If the attached dialog was doing a codification look-up, the only (cont.) information required to be sent back to the attaching function is the key of the record selected, not the entire (cont.) record. The receiving transaction can always reread the record in question to obtain additional information. (cont.) Conceptually, information passed in this manner is far more atomic than one might suspect initially. Conventional CICS (cont.) DFHCOMMAREA processes generally tend to pass far more data. The original attaching program's TWA area will be (cont.) preserved; therefore there is never any need to pass along any of that information to the attached module. In fact, (cont.) upon entry to the attached module, the TWA will contain the contents of the attaching programs area. This area will (cont.) always be completely restored upon detachment. Of course the values of TWA-MSK-AID, SCOMPL, and SERRMSG area will be (cont.) altered as cited above. Applications which require massive cross communication of TWA information can be developed but (cont.) need to be rigorously architected to insure that the TWA areas conform. One technique for passing very large amounts of (cont.) data is to write it to a record on a file, passing the key to the target transaction. We have discussed the basic method of invocation of the attach/detach facility and the communications areas used in the (cont.) process. We should now discuss the additional information available to the application designer/programmer to control (cont.) this facility. There are a series of COBOL 88-Levels in the TWA which may be interrogated to determine the current (cont.) status of a dialog. The below series of code examples illustrate the use of these conditionals: 1.  *== This is often done in %PFKEYM or %PFKEYL    *== Determine if attached and, if so, detach    *== passing data back via SERRMSG (optional)          IF ( you wish to detach )             IF (TWA-SWAP-ATTACHED)                 MOVE  return-information TO SERRMSG                 GO TO AA770-DETACH.         2.  *== This is often done in %PFKEYM or %PFKEYL    *== Check to be sure that we can attach another level lower         IF ( something needs to be attached )            IF (NOT TWA-SWAP-LOWLEVEL)         do the attach logic .                             3.  *== Cancel the current Dialog programatically if required         IF (TWA-SWAP-DIALOG-A)            MOVE A   TO TWA-SWAP-ID         ELSE                         MOVE X   TO TWA-SWAP-ID                             4.  *== This must be done in %PREINIT    *== Check for attach and utilize data passed in SERRMSG         IF (TWA-MSK-ATT-REQ)             IF (TWA-SCOMPL-ATTDET = 'ATT' ) AND                (TWA-SCOMPL-FUNCT is a valid function )                MOVE SERRMSG TO your-SERRMSG-work-area                 continue as appropiate for attach             ELSE                          take action for invalid attach .                             5. *== This must be done in %PREINIT   *== Check for detach and utilize data passed in SERRMSG         IF (TWA-MSK-DET-REQ)            IF ( TWA-SCOMPL-ATTDET = 'DET' ) AND               ( TWA-SCOMPL-FUNCT is a valid function )               MOVE SERRMSG TO your-SERRMSG-work-area               move various SERRMSG data to screen fields               GO TO AA800-SEND-SCREEN            ELSE                          take action for invalid detach .   The above examples show the various things that can be done by interrogating the current status of the session. The (cont.) third example shows how a program can push itself to the top of the attach list. Note that this also occurs (cont.) automatically any time the terminal user causes the MAGEC clear screen to be invoked, or when a MAGEC menu function is (cont.) used. The application users can escape a dialog at any time they desire. Logging on (via the SYSLOG function) also (cont.) results in the session being established at the "top" of the attach dialog (clearing the stack). Additionally, if the (cont.) application does not make the check to see if it has been attached, and then subsequently issues an invalid Detach (cont.) request, an error code is displayed. Attempting to attach another function when you are already at the lowest level (cont.) results in a pop-up window offering the operator four options for handling the situation. 1) push the oldest screen off (cont.) the stack, 2) clear the stack, 3) transfer the screen without adding the current screen to the stack (using a (cont.) FTH-FUNCT, instead of an Attach), 4) return to the original screen. # Appendix S -- Multi-Screen Applications ## Screen Sequences A common (false) impression that many developers get when first introduced to MAGEC is that it does a great job of (cont.) developing single-screen transactions; but doesn't seem to handle applications which involve multiple screens. An (cont.) example of such a multi-screen application would occur when the data to be added/updated is more than can be placed on (cont.) one screen. In this example it is necessary to create multiple screens to capture or present all the data before any (cont.) I/O request to update the file(s) or table(s) is issued. Actually, multi-screen processing is quite simple with MAGEC. In fact, the entire application development process which (cont.) was used throughout these turorials is merely a collection of MAGEC-generated applications which link to one another. (cont.) Next: https://magec.com/DOC/markdown/cstm18.md.txt