UNDERLINE
BLINK
REVERSE-VIDEO
##
Symbolic Screen Field References
When you are coding customization logic for your MMP's, you will usually be more familiar with the database field (DIT) (cont.)
datanames than with the screen field (MSK) datanames. For that reason, you may prefer to utilize MAGEC's **Symbolic (cont.)
Screen Field Referencing** feature which is described in detail in the "Database Administration" chapter of the (cont.)
"Programmer's Reference Guide.
Briefly, it enables you to use the database name to indirectly access screen fields. The mapping of database names to (cont.)
screen field names is controlled by the associations defined in the screen's Mask definition. The associations are (cont.)
defined using the "Source/Target" specifications for screen fields.
Assuming that you had a screen field named SAMOUNT with a source/target named CUS01-AMOUNT, you could code:
MOVE +10.00 TO @CUS01-AMOUNT@-N @CUS01-AMOUNT@-ED
MOVE RED TO @CUS01-AMOUNT@-COLOR
rather than having to look up the screen field name (SAMOUNT) in order to access it.
MAGEC will, as the program is being generated, translate the symbolic references into the proper Cobol datanames. You (cont.)
can append any of the appropriate suffixes to the symbolic reference, as shown above. Assuming that the screen field (cont.)
having CUS01-AMOUNT as its source/target is named SAMOUNT, the above coding would translate into:
MOVE +10.00 TO SAMOUNT-N SAMOUNT-ED
MOVE RED TO SAMOUNT-COLOR
Symbolic references are a good way to access screen fields in routines which are to be stored as copybooks to be (cont.)
included into many programs. This way you are not concerned with knowing the datanames used for screen fields in (cont.)
several places, your coding becomes more "portable".
**
NOTE:
**
You should read the topic, *Symbolic Screen Field References* in the "Database Administration" chapter before coding (cont.)
symbolic references. This feature was provided primarily for the coding of Business Rules and Referential Integrity (cont.)
Rules, however, it is also available to Application Developers.
#
Appendix Q -- SQL
##
SQLCRE Function
In order to generate MMP's which access an SQL database, such as DB2, you must provide customization coding (using SQL) (cont.)
to replace the default I/O routines. You could do this manually, or you can have MAGEC generate the necessary (cont.)
customization coding automatically. The automatic generation process is online and involves only a single online (cont.)
command:
SQLCRE nnn
where nnn is the Mask# (SHD number) of the application for which you wish SQL accesses generated.
The SQLCRE function will automatically generate customization for all of the I/O insertion points. They are:
%ADDIT
**%DELET
%LOCKY
%REDNX
%RDUKY
%REDKY
%UPDAT
%RELES
and for two other insertion points where it is necessary to define the host variables and to move them to and from the standard MAGEC data definition copybook. The two other insertion points are:
%LITERAL
%SUBRTNM
The customization will be added to the dictionary with names which include modifiers to identify them as generated (cont.)
code. The modifiers will all be "MAGECSQL". For example, for application 600 there would be customization generated (cont.)
as:
600/ADDIT/MAGECSQL
600/REDKY/MAGECSQL
et cetera
If you modify these generated routines you should be aware that re-executing the SQLCRE command will overlay your modifications with newly generated, unmodified routines.
The generated code assumes that there is a member defining the host variables for each Element accessed stored on the MAGEC library. The member must have a name of
eeeee-c/SQL
where eeeee is the element name. Such a host variable definition library member will be generated by the DITGEN (cont.)
function (see the *Data Definition* tutorial) automatically, if the Data Class has an access method of SQL or DB2 (cont.)
specified.
If you have generated an application for SQL and wish to revert it back to VSAM, or some other access method, you must (cont.)
remove all of the SQL customization. This allows the application to be re-generated using the default logic which (cont.)
accesses the MAGEC I/O module.
To remove the SQL customization, you could either manually delete it piece-by-piece; or you could use the SQLPUR (SQL Purge) function to remove all of it in one fell swoop. The format is:
SQLPUR nnn
where nnn is the applications's Mask number, as before. Any modifications you nave made to the generated SQL routines (cont.)
will be deleted along with the routines since the SQLPUR function erases all customization code for the specified (cont.)
application which has a modifier of MAGECSQL.
The generated SQL customization is for the Primary Data Class only. The Primary Data Class may be a single table or it (cont.)
may be a view, joining several tables. Restrictions of your database management system may prevent updates or deletes (cont.)
whcn accessing a joined view, rather than a simple table.
If you wish, you can do standard MAGEC joins of multiple tables, thereby circumventing the database management system's (cont.)
restrictions against updating joined views. To do that you would code SQL accesses to other tables in the standard (cont.)
%JOIN insertion point, or elsewhere in the MMP's logic. MAGEC will not automatically generate such accesses; however, (cont.)
the built-in Named Proforma facility will help you quite a lot since it contains all the SQL command formats pre-coded (cont.)
for you.
SQLPUR will not purge any customization except for that which has the MAGECSQL modifier, and is in the designated (cont.)
insertion points (listed earlier). Your manually added SQL code in other insertion points (such as %JOIN), or with any (cont.)
other modifiers, will not be purged!
#
Appendix R -- Attach / Detach
##
Purpose for this Facilty
As of release 2.6, MAGEC has added the Attach/Detach facility which provides a standardized technique for coding (cont.)
"nested" screens. Nested screens are simply a sequence of screens wherein the operator can be entering into one screen (cont.)
and can "pop-up" another screen and then return to the first screen with all data as it was left and with the ability (cont.)
to pass information from one to another.
Some people would use the nomenclature "push/pop stack", or "call/return", to describe MAGEC's Attach/Detach facility. (cont.)
The name "Attach/Detach" is intended to avoid confusion with any other existing facility of CICS or other environmental (cont.)
software.
An Attach is a call from one transaction to invoke another transaction, retaining all data necessary to enable the lower-level transaction to Detach, or to return to the calling transaction.
This facility supports multiple levels of nesting. The Attach function preserves TWA data, file positioning, and screen (cont.)
data for the transaction so that control is passed back to it in the same status as it was left. The transactions are (cont.)
also able to pass data back and forth.
The Attach/Detach facility is particularly beneficial when used in conjunction with the MODELWIN feature which (cont.)
generates pop-up windows applications. A full-screen application can easily Attach to a pop-up window application which (cont.)
can perform any number of processes, then Detach back to the full-screen application which invoked (cont.)
it.
Rather than using the FTH-FUNCT (Fetch Function) command, which would require the programmer to save and restore TWA (cont.)
data for each task, using Attach/Detach automatically saves and restores the TWA as appropriate and supports passing (cont.)
data from one task to another.
##
Design Criteria
The Attach/Detach facility retains much of the feel of existing MAGEC facilities, in fact, it is very similar to fetch (cont.)
function (FTH-FUNCT) which is a well known and established MAGEC programming technique. The facility uses existing (cont.)
MAGEC common areas, i.e. the common screen fields, SFUNCT, SKEY, SERRMSG, SCOMPL, and TWA-MSK-AID are in the same (cont.)
relative positions in every TWA, thereby making them the ideal common areas for the applictions to use. There is also (cont.)
the benefit that the use of these fields is completely environmentally neutral, creating no CICS dependencies. Having (cont.)
an unlimited number of levels introduces the problem of too much overhead, so a limit of thirteen (13) levels is (cont.)
designated as being sufficient for most needs. The facility should be usable from either of the active MAGEC windows (cont.)
(swapping windows is done using the PF9 key) at the terminal and each session is completely independent of the other. (cont.)
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.)
next: cstm21.md.txt