RELES--release the record just read-with-intent<br />ADDIT--add a record<br />**VER--set TWA-DB-RETURN-CODE (or DB-RETURN-CODE) to MAGEC version#<br />The following commands are valid only in batch programs:<br />CLSFL--close a file<br />*CLSE--close all files<br />OPENU--open file for update<br />OPENR--open file read-only<br />*READ--set default to open read-only (implicit opens)<br />*LOAD--set default to open for update (implicit opens)<br />*PURG--enable reading and purging pseudodeleted records<br />As a rule of thumb: commands ending in "KY" require that a value be filled into TWA-KEY-VALUE or DB-KEY-VALUE, Commands (cont.)<br />beginning with LOC implicitly read only the key value (as if it were a mini-Element defined). All commands require that (cont.)<br />the element list contain valid Element name(s) even if they are LOC commands. Commands starting with RDU obtain (cont.)<br />Exclusive Control of the record (rather than Control Interval), locking out other tasks from reading (or (cont.)<br />reading-with-intent) that record.<br />The Key Name that is moved to TWA-DB-KEY-NAME or DB-KEY-NAME must be defined on the KYF file, i.e.: IVCK1.<br />The DELET and UPDAT commands must be preceded by a successful read-with-intent (RDU..) command for that record. The (cont.)<br />LOCNX, REDNX and REDPR commands must be preceded by a successful LOC.. or RED.. command.<br />## <br />The Key Value -- Online Programs<br />The TWA field named TWA-KEY-VALUE is 256-bytes long and can therefore contain a file key up to that size. The generated (cont.)<br />MMP's include a Normalize Key routine (BA300-Normalize-Key) which transforms the key value entered by the operator on (cont.)<br />the top line of the screen into the correct format for use in accessing the file. It places the transformed (file (cont.)<br />format) key value into a field in the TWA filed named NORMALIZED-KEY and the MMP then moves that to TWA-KEY-VALUE for (cont.)<br />accessing the Primary Data Class. If the developer adds customization code to access other files then it is his/her (cont.)<br />responsibility to set TWA-KEY-VALUE as needed.<br />## <br />The Key Value -- Batch Programs<br />The Working Storage field named DB-KEY-VALUE is 256-bytes long and can therefore contain a file key up to that size.<br />## <br />Element List<br />The area in the TWA named TWA-ELT-LIST has room for up to 16 Element names. This means that the MMP can read up to 16 (cont.)<br />Elements from the same Data Class in one CALL. MAGECIO will return the data from the record read for the Element(s) (cont.)<br />specified and in the order they are specified in the Element list. The data will be concatenated, therefore it is (cont.)<br />necessary that the copybook definitions for the Elements be in the same order and that they be the correct length(s) (cont.)<br />and that they be immediately following one another (if there are more than one).<br />The Element Names are the 5-character names defined on the ELT file. In the Element list up to sixteen (16) Element (cont.)<br />Names may be specified, they must be separated by one space and the last Element Name must be followed by a "dummy" (cont.)<br />Element Name of blanks (unless you have filled all sixteen (16) names). An example of the Element list to access two (cont.)<br />Elements might be:<br />in online MMP's:<br />MOVE 'IVC01 IVC04 ' TO TWA-ELT-LIST.<br />in batch MBP's:<br />MOVE 'IVC01 IVC04 ' TO DB-ELT-LIST.<br />The Program would also contain, in its Data Division:<br />-MAGECINC IVC01-C<br />-MAGECINC IVC04-C<br />## <br />Read Into / Write From -- Online Programs<br />To tell MAGECIO where to read into or write from, online MMP's use the MAGECSET subroutine that is provided and (cont.)<br />included into the Link Edit for all MMP's. The MAGECSET subroutine should be CALLed immediately before every CALL to (cont.)<br />MAGECIO. To tell MAGECIO to READ INTO the area beginning with IVC01-ELEMENT (Cobol dataname in copybook) the MMP would (cont.)<br />contain:<br />CALL 'MAGECSET' USING TWA-DB-AREA-A IVC01-ELEMENT<br />The area you read into or write from is often called the "work area". If the MMP does not point MAGECIO to a work area (cont.)<br />before CALLing MAGECIO then the default area will be used. The default area is TWA-DB-DATA.<br />## <br />Read Into / Write From -- Batch Programs<br />Batch programs specify where to read into or write from via the standard Cobol parameter list passed with the CALL (cont.)<br />verb. The second parameter passed to the batch I/O module points to the area to read into or write (cont.)<br />from.<br />## <br />CALL'ing MAGECIO -- Online Programs<br />To call MAGECIO to service your request, code:<br />PERFORM AA840-CALL-MAGEC-IO THRU AA899-EXIT<br />The mechanism for actually CALLing the MAGECIO module is different for each TP monitor supported by MAGEC and can even (cont.)<br />be different depending on system options at your site. The code generated in the AA840 routine will be correct for your (cont.)<br />site. If your generated applications are ever required to operate in a different environment as a result of a (cont.)<br />conversion or for any other reason then the AA840 routine will automatically be adjusted accordingly by the MMPCREAT (cont.)<br />process. If, on the other hand, you "hard code" your own code to accomplish the CALL then your application might not (cont.)<br />work in other environments.<br />## <br />CALL'ing MAGECIO -- Batch Programs<br />Batch programs must be linked to include the MAGDBMS subroutine, that is the batch version of MAGECIO. To call it, enter the following code:<br />CALL 'MAGECIO' USING DB-REQUEST-AREA, work-area, DB-ELT-LIST.<br />If the file you are accessing has not been opened yet, MAGECIO will open it for *read-only* (unless you have set the (cont.)<br />global default to open for *update*). You can explicitly open a file using the OPENU (open for update) or OPENR (open (cont.)<br />read-only) commands. You can alter the default using the *LOAD (default open for update) or *READ (default open (cont.)<br />read-only). When your program is initially started the default is set to open read-only.<br />You can close a file using the CLSFL command, then re-open it if you need to.<br /># <br />Return Codes<br />## <br />MAGECIO Intercepts I/O Errors<br />Whenever you request database services via MAGECIO you should always check the Return Code to see that your request was (cont.)<br />successfully handled. There are a large number of things which can go wrong when you attempt to access a file (cont.)<br />including: I/O errors, invalid requests, missing Dictionary definitions, or hardware failures. Unless you have (cont.)<br />specified for MAGECIO not to handle errors (see below), MAGECIO tests for these error conditions and handles them for (cont.)<br />the MMP so that the MMP need not concern itself with them. If a catastrophic error is detected then MAGECIO issues an (cont.)<br />error message to the offending terminal and then aborts the task with an appropriate Abend Code.<br />A two-character Return Code is placed into the request area in a field named TWA-DB-RETURN-CODE (online) or (cont.)<br />DB-RETURN-CODE (in batch) by MAGECIO on every request. A value of blanks always indicates that the request was (cont.)<br />successfully handled without errors. There is a Condition-Name (88 level) defined which the programs use to test for (cont.)<br />successful completion as:<br />IF (REC-FOUND)<br />- etc.<br />A value of '14' indicates either that no record was found for the key value given or that the end of the list (file) was reached. A Condition Name is provided for this also as:<br />IF (NOT-FOUND)<br />- etc.<br />A value of '10' indicates that you have attempted to add a record with a key value that is a duplicate of one already on file. A Condition Name for this is also provided as:<br />IF (DUP-ERROR)<br />- etc.<br />The database accesses generated automatically by MMPCREAT and MBPCREAT always include checking of the Return Code. Yours should also.<br />If you do not wish for MAGECIO to abort the task when a serious error condition occurs, you should move "NH" to (cont.)<br />TWA-DB-RETURN-CODE just prior to calling MAGECIO. The "NH" stands for "No Handle" and directs MAGECIO to simply set the (cont.)<br />appropriate code into TWA-DB-RETURN-CODE and return to your program. It them becomes your responsibility to deal with (cont.)<br />any error conditions.<br /># <br />Sample Code<br />## <br />A Cobol Example -- Online Programs (MMP's)<br />An example of the complete coding to read (using the REDKY command) two Elements from the IVC Data Class for Customer# 37, Invoice# 125 would be:<br />- - - - - in TWA data definition area - -(%DATADEF) - - - -<br />| ```<br />**<br />03 INVOICE-DATA.<br />```** <br />-MAGECINC IVC01-C<br />-MAGECINC IVC04-C<br />- - - - - in PROCEDURE DIVISION - - - - - (%JOIN) - - - - -<br />MOVE REDKY TO TWA-DB-CMD.<br />MOVE 'IVCK1' TO TWA-DB-KEY-NAME.<br />MOVE '00037000125' TO TWA-KEY-VALUE.<br />MOVE 'IVC01 IVC04 ' TO TWA-ELT-LIST.<br />CALL 'MAGECSET' USING TWA-DB-AREA-A INVOICE-DATA.<br />PERFORM AA840-CALL-MAGEC-IO THRU AA899-EXIT.<br />IF (REC-FOUND)<br />| ```<br />**<br />NEXT SENTENCE<br />```** <br />ELSE<br />| ```<br />**<br />GO TO NO-INVOICE-FOUND.<br />```** <br />Other database commands (i.e. RDUKY, UPDAT, etc.) are coded in exactly the same format.<br />The %DATADEF and %JOIN markers above refer to the Custom Algorithm insertion points of the same names as used by the (cont.)<br />application developer. They are not the only places where I/O requests may be coded. They are, however, the places (cont.)<br />where such coding is most often found.<br />The %DATADEF is in the TWA-DB-DATA area of the TWA, this is where MMPCREAT will automatically read the Primary Data (cont.)<br />Class's Elements into and where the copybooks for them will automatically be included. It is sometimes desirable to (cont.)<br />place the copybooks (and read-into area) for the other Data Classes elsewhere in the TWA, possibly because of size. The (cont.)<br />other place where copybooks are often included by the developers is the %VARSTOR insertion point. This area is farther (cont.)<br />down in the TWA in the VARIABLE-STORAGE area that is not saved and restored by MAGECCP and is always cleared to (cont.)<br />LOW-VALUES on entry to the MMP.<br />Remember, if you are only reading the record to determine whether it exists or not (as in some editing routines) then (cont.)<br />you can save space and some overhead by using the LOCKX command instead of REDKY. Your "read-into" area need only be as (cont.)<br />large as the record key in that case.<br />## <br />A Cobol Example -- Batch Programs (MBP's)<br />An example of how to code the logic to accomplish exactly the same thing as was done in the above online MMP from a batch program (we call them MBP's) is as follows:<br />- - - - - in WORKING-STORAGE - - - - - - (%DATADEF) - - - -<br />| ```<br />**<br />01 INVOICE-DATA.<br />```** <br />-MAGECINC IVC01-C<br />-MAGECINC IVC04-C<br />- - - - - in PROCEDURE DIVISION - - - - - (%JOIN) - - - - -<br />MOVE REDKY TO DB-CMD.<br />MOVE 'IVCK1' TO DB-KEY-NAME.<br />MOVE 'IVC01 IVC04' TO DB-ELT-LIST.<br />MOVE '00037000125' TO DB-KEY-VALUE.<br />CALL 'MAGECIO' USING DB-REQUEST-AREA<br />INVOICE-DATA<br />DB-ELT-LIST.<br />IF (REC-FOUND)<br />| ```<br />**<br />NEXT SENTENCE<br />```** <br />ELSE<br />| ```<br />**<br />GO TO NO-INVOICE-FOUND.<br />```** <br />Other database commands (i.e. RDUKY, UPDAT, ADDIT, etc.) are coded in exactly the same format.<br />**<br />NOTE:<br />**<br />As of MAGEC release 3.0, batch programs (MBP's) include provisions to accept the same coding as is shown for MMP's on (cont.)<br />the previous page, as well as the coding shown above. This enables you to use the same Proformas and included routines (cont.)<br />in both online and batch programs. The MBP's include a redefinition of the request area so that, for example, moving a (cont.)<br />command to TWA-DB-CMD is identical to moving to DB-CMD, and so forth. The AA840-CALL-MAGEC-IO paragraph is also (cont.)<br />included in the MBP's, as is the pointer field TWA-DB-AREA-A.<br />Your MBP must be linked to include the MAGDBMS module. The sample jobstreams provided with MAGEC contain the (cont.)<br />appropriate link coding for your environment (MVS, VSE, MS-DOS, VM, etc.). The jobstream is named MBPCREAT, it is a JCL (cont.)<br />member for the mainframe and a .BAT or .CMD file for the PC.<br />## <br />Logical Sequences of Commands<br />The following sequence of commands will illustrate how you can control opening and closing files in a batch program. Assume a program accessing the ABC, DEF, and XYZ data classes.<br />**Command**<br />**MAGECIO action taken**<br />beginning of program<br />initial default open switch set to "read-only"<br />LOCKY XYZ<br />open XYZ read-only<br />REDLE XYZ<br /><br />next: db04.md.txt