Who Should Read This Guide

This guide is written primarily for use by those persons who will be utilizing the batch utilities included with MAGEC. These utilities include the jobstreams for generating and compiling programs, producing where-used reports, producing hardcopy documentation, and more.

Copies of this guide should be distributed to:

• Application developers
• Database administrators
• System programmers

Related Chapters

This chapter is to be used for reference. It includes complete discussions of jobstreams and control cards which go with them. You will usually use this chapter in conjunction with one of the other chapters, such as:

• "Librarian"
• "Documentation"
• "Data Administration"
• "Tutorials"

Overview

Mainframe Environment

In this chapter you will find explanations for the batch utility programs and their associated jobstreams. Sample JCL is shown for mainframe environments(z/OS and VSE) and for PC environments (Windows).

PC Environment

The JCL or jobstream equivalent in PC MAGEC is the .BAT file for MS-DOS and Windows environments, and the .CMD file for OS/2 environments. The MAGEC system and repository are installed into a directory named \MAGEC for a Realia Cobol system, or \MAGMF for a MicroFocus Cobol system. In the following discussions we will indicate a directory name of \MAGxx, which represents either \MAGEC or \MAGMF, depending on your compiler choice.

The .BAT files are stored in the directory \MAGxx\JCL. You are asked to include that directory in your PATH (or MAP) when you install MAGEC and to keep it permanently in your PATH or MAP. That enables you to execute the .BAT files by simply typing their names at the DOS or OS/2 prompt. When executing these .BAT files from a Windows environment, a .PIF file is used which specifies the \MAGxx\JCL directory as the path to the .BAT file, or as its Working Directory. Similarly, the OS/2 folders to execute the .CMD files each specify that directory.

Since it is illegal to contain data within a .BAT or .CMD file, the control cards and other input data are contained in separate files. These data files are ordinary text files. For easy identification we usually name them with an extension of .RDR and they are usually in the \MAGxx directory.

You can alter the .BAT files to direct them to different input and output files, as needed. In order to make PC MAGEC as similar as possible to the mainframe environment, we utilize the SET command of MS-DOS or OS/2 to associate an internal file designator (i.e. SYS006) to an external file name (i.e. \MAGxx\MAGECLBR.RDR). You can alter the SET statements, if you like. They are functionally equivalent to the DD statement (in z/OS) or the DLBL statement (in VSE).

In this book you will notice that we inform you of the file names referenced by the .BAT or .CMD files' SET statements at the time MAGEC was installed on your PC. If you alter them they will, of course, be different. It is a common practice to alter the SET statements to direct the input or output to a floppy drive (especially when transferring data to another machine).

For obvious reasons, some of the jobstreams depicted in this book have no equivalent on the PC. This is especially true of those which are used to assemble BAL programs. See the PC Batch Files section later in this chapter for filenames found exclusively in PC MAGEC.

Several environment variables are used to direct MAGEC to the proper drives to locate executable modules, data files, and temporary work files used within a given jobstream:

SET LANDRV=x (for data files)
SET LCLDRV=y (for work files)
SET EXEDRV=z (for executables)

Link MAGECCP for Production

ALACPLKP Jobstream

The ALACPLKP jobstream is used to linkedit the MAGEC Control Program for the Production User-Views (PR01 thru PR08) in a mainframe environment. It is used only if you are executing the old Assembler version of the Control Program.

VSE

// JOB ALACPLKP
// EXEC PROC=MAGECLIB    
-pvt. libs.

// OPTION CATAL
 PHASE MMP699,*
 INCLUDE MAGECCP         
(CATALR'd previously)

 INCLUDE ALAEDIT
 INCLUDE ALATEDT
 INCLUDE MOVEMSG
 INCLUDE OUTMSG
 INCLUDE SBACONV
 INCLUDE MAGVSAM
// EXEC LNKEDT,SIZE=128K
/*
/&

z/OS

//ALACPLKP JOB CLASS= ,MSGCLASS=
//LKED     EXEC PGM=IEWL,PARM=(NCAL),COND=(8,LT)
//SYSLIB   DD DSN=SYS1.MACLIB,DISP=SHR
//         DD DSN=MAGEC.LOADLIB,DISP=SHR
//SYSUT1   DD UNIT=SYSDA,SPACE=(1024,(50,20))
//SYSPRINT DD  SYSOUT=*
//SYSLMOD  DD DSN=MAGEC.LOADLIB,DISP=SHR
//SYSLIN   DD *
 INCLUDE SYSLMOD(MAGECCP)
 INCLUDE SYSLMOD(MAGVSAM)
 INCLUDE SYSLMOD(SBACONV)
 INCLUDE SYSLMOD(MOVEMSG)
 INCLUDE SYSLMOD(ALAEDIT)
 INCLUDE SYSLMOD(ALATEDT)
 INCLUDE SYSLMOD(OUTMSG)
 NAME MMP699(R)
/*
//

Link MAGECCP for Test

ALACPLKT Jobstream

The ALACPLKT jobstream is used to linkedit the MAGEC Control Program for the Test User-Views (TS01 thru TS08) in a mainframe environment. It is used only if you are executing the old Assembler version of the Control Program.

VSE

// JOB ALACPLKT
// EXEC PROC=MAGECLIB    
pvt. libs.

// OPTION CATAL
 PHASE MMP670,*
 INCLUDE MAGECCP    
    (CATALR'd previously)

 INCLUDE ALAEDIT
 INCLUDE ALATEDT
 INCLUDE MOVEMSG
 INCLUDE OUTMSG
 INCLUDE SBACONV
 INCLUDE MAGVSAM
// EXEC LNKEDT,SIZE=128K
/*
/&

z/OS

//ALACPLKT JOB CLASS= ,MSGCLASS=
//LKED     EXEC PGM=IEWL,PARM=(NCAL),COND=(8,LT)
//SYSLIB   DD DSN=SYS1.MACLIB,DISP=SHR
//         DD DSN=MAGEC.LOADLIB,DISP=SHR
//SYSUT1   DD UNIT=SYSDA,SPACE=(1024,(50,20))
//SYSPRINT DD  SYSOUT=*
//SYSLMOD  DD DSN=MAGEC.LOADLIB,DISP=SHR
//SYSLIN   DD *
 INCLUDE SYSLMOD(MAGECCP)
 INCLUDE SYSLMOD(MAGVSAM)
 INCLUDE SYSLMOD(SBACONV)
 INCLUDE SYSLMOD(MOVEMSG)
 INCLUDE SYSLMOD(ALAEDIT)
 INCLUDE SYSLMOD(ALATEDT)
 INCLUDE SYSLMOD(OUTMSG)
 NAME MMP670(R)
/*
//

Link MAGECIO for Production

ALAIOLKP Jobstream

The ALAIOLKP jobstream is used to linkedit the MAGEC I/O module for Production User-Views (PR01 thru PR08) in a mainframe environment. It is used only if you are executing the old Assembler version of the I/O module.

VSE

// JOB ALAIOLKP
// EXEC PROC=MAGECLIB    
pvt. libs.

// OPTION CATAL
 PHASE MMP698,*
 INCLUDE MAGECIO        
(CATALR'd previously)

 INCLUDE DBCSVPR        
(if Datacom/DB)

 INCLUDE MAGVSAM    
// EXEC LNKEDT,SIZE=128K
/*
/&

z/OS

//ALAIOLKP JOB CLASS= ,MSGCLASS=
//LKED     EXEC PGM=IEWL,PARM=(NCAL),COND=(8,LT)
//SYSLIB   DD DSN=SYS1.MACLIB,DISP=SHR
//         DD DSN=MAGEC.LOADLIB,DISP=SHR
//SYSUT1   DD UNIT=SYSDA,SPACE=(1024,(50,20))
//SYSPRINT DD  SYSOUT=*
//SYSLMOD  DD DSN=MAGEC.LOADLIB,DISP=SHR
//SYSLIN   DD *
 INCLUDE SYSLMOD(MAGECIO)
 INCLUDE SYSLMOD(MAGVSAM)
 INCLUDE SYSLMOD(DBCSVPR)    
(if Datacom DB)

 NAME MMP698(R)
/*
//

Note: If both VSAM and Datacom DB are to be supported by your MAGEC system, then you must include both DBCSVPR and MAGVSAM. The MAGEC Dictionary files are VSAM.

Link MAGECIO for Test

ALAIOLKT Jobstream

The ALAIOLKT jobstream is used to linkedit the MAGEC I/O module for Test User-Views (TS01 thru TS08) in a mainframe environment. It is used only if you are executing the old Assembler version of the I/O Module.

VSE

// JOB ALAIOLKT
// EXEC PROC=MAGECLIB    
-pvt. libs.

// OPTION CATAL
 PHASE MMP653,*
 INCLUDE MAGECIO        
(CATALR'd previously)

 INCLUDE DBCSVPR        
(if Datacom/DB)

 INCLUDE MAGVSAM
// EXEC LNKEDT,SIZE=128K
/*
/&

z/OS

//ALAIOLKT JOB CLASS= ,MSGCLASS=
//LKED     EXEC PGM=IEWL,PARM=(NCAL),COND=(8,LT)
//SYSLIB   DD DSN=SYS1.MACLIB,DISP=SHR
//         DD DSN=MAGEC.LOADLIB,DISP=SHR
//SYSUT1   DD UNIT=SYSDA,SPACE=(1024,(50,20))
//SYSPRINT DD  SYSOUT=*
//SYSLMOD  DD DSN=MAGEC.LOADLIB,DISP=SHR
//SYSLIN   DD *
 INCLUDE SYSLMOD(MAGECIO)
 INCLUDE SYSLMOD(MAGVSAM)    
 INCLUDE SYSLMOD(DBCSVPR)    
(if Datacom DB)

 NAME MMP653(R)
/*
//

Note: If both VSAM and Datacom DB are to be supported by your MAGEC system, then you must include both DBCSVPR and MAGVSAM. The MAGEC Dictionary files are VSAM.

List Error Messages

ERRLIST Utility Program

The ERRLIST batch utility may be used to print hardcopy lists of the Error Messages from the MAGEC ERR file. The Error Number, Text, and Narrative Description for each Error Message will be shown.

ERRLIST Control Cards

The program accepts a control card to specify the range of Error Numbers desired to be listed. Multiple control cards may be input into any one run. The format is:

Columns

Description

Card Format:

1 - 8

Constant "ERRLIST".

9 - 11

Starting Error Number. (may be alphanumeric)

12

Constant "-".

13 - 15

Ending Error Number. (may be alphanumeric)

Control card example:

ERRLIST 001-999

VSE

* $$ JOB JNM=ERRLIST,CLASS=
* $$ PRT CLASS=V
// JOB ERRLIST
// EXEC PROC=MAGECLIB    
-pvt. libs. and DLBL's for dictionary
// ASSGN SYS006,SYSIPT
// ASSGN SYS007,SYSLST
// EXEC ERRLIST,SIZE=(AUTO,20K)
ERRLIST xxx-yyy
/*
/&
* $$ EOJ

z/OS

//ERRLIST   JOB  CLASS=_,MSGCLASS=_
//STEP1    EXEC PGM=ERRLIST
//STEPLIB  DD  DSN=MAGEC.LOADLIB,DISP=SHR

* * * * * * * *   DD's for dictionary files

//SYSOUT   DD  SYSOUT=W
//SYS007   DD  SYSOUT=W
//SYS006   DD  *
ERRLIST xxx-yyy
/*
//

PC

Edit, as necessary, the control cards found in the file named:

\MAGxx\ERRLIST.RDR

At the prompt enter:

ERRLISTX

MAGECLBR

Library Utility

MAGECLBR is used for offline updating and listing against the MAGEC ALG, DOC, and DIT files.

The batch utility, MAGECLBR, may be used to:

• Punch and print a member from the ALG or DOC file.
• Print a member from the DOC file.
• Print one or all custom algorithms from the ALG file for an application
• Add a member to the ALG, DOC, or DIT file.
• Replace a member on the ALG or DOC file.
• Delete a member on the ALG, DOC, or DIT file.
• Print an index report of the ALG or DOC files.
• Print a Where-Used report for an Element, copybook, Domain, Data Item, or character string.
• Apply global changes to all Data Items belonging to a Domain

The ALG file contains five types of members (six, if you separate the two types of custom algorithms for batch and online) identifiable by their "key prefixes". They are:

Key Prefix    Member Type

LIB General purpose library member which may be referenced as a "copybook" using the -MAGECINC command. Also may be printed or punched using MAGECLBR for various purposes. Also may be entire source programs.

DEF Default customization algorithms which are inserted into generated MMP's at insertion points when the developer does not provide a custom algorithm for that insertion point.

nnn Where nnn = a valid SHD (mask) number. Custom algorithm for mask # nnn.

nnnB Where nnn = a valid Batch Report Number. Custom algorithm for Batch Report # nnnB.

PRO Named Proforma Members which are frequently used code or routines that MAGEC can place on your screen to reduce coding effort.

RUL Business Rule coding associated with an element.

The DOC file contains documentation for any purposes desired by the user, but primarily for the MAGEC Online Documentation feature.

The DIT file contains the Dictionary definitions for the Data Items (fields) in the Elements, and it also contains the Domain definitions.

Members may be seen and updated online using system function codes. The standard set of MAGEC functions and online documentation is available for each Member type. Additional functions are also provided in some cases.

To access each Member Type online use any valid function suffix ( ADD, CHG, DEL, etc.) in place of ... as follows:

DOC... ttt---tt

For Documentation on DOC file.
ttt---tt = 30-character Topic Name

LBR... nnnnnnnn/mmmmmmmm/ppp

For General Purpose Library Members.
nnnnnnnn = Member Name
mmmmmmmm = Modifier
ppp = Page number

DEF... nnnnnnnn/DEFAULT/ppp

For Default Algorithms.
nnnnnnnn = insertion %Parm Name
DEFAULT = literal value (optional)
ppp = Page number

ALG... xxx/nnnnnnnn/mmmmmmmm/ppp

For MMP Custom Algorithms.
xxx = Screen Header (mask) no.
nnnnnnnn = insertion %Parm Name
mmmmmmmm = Modifier (optional)
ppp = Page number

ALG... xxxB/nnnnnnnn/mmmmmmmm/ppp

For Batch Program Custom Algorithms.
xxxB = the Batch Report Number
nnnnnnnn = insertion %Parm Name
mmmmmmmm = modifier (optional)
ppp = Page number

PRO... nnnnnnnn/mmmmmmmm

For Named Proforma Members.
nnnnnnnn = Member Name
mmmmmmmm = Modifier (optional)

RUL... eeeee/mmmmmmmm

For Business Rules.
eeeee = 5-character Element name
mmmmmmmm = Modifier (RULWORK or RULPROC)

MAGECLBR Control Cards

The MAGECLBR control card specifies which operation is to be performed and provides the parameters necessary for the desired operation. The control card format is:

Col 1-10:

Operation (required)

-MAGECADD Add a member

-MAGECREP Replace a member

-MAGECPCH Punch and print a member

-MAGECPUN Punch and print a member

-MAGECPRT Print a member or custom algorithms

-MAGECLST Print a member or custom algorithms

-MAGECDEL Delete a member

-MAGECIDX Print an index list

-MAGECUSE Print a Where-Used report

-MAGECGBL Apply global changes (Domains only)

-MAGECI/O READONLY (col 1-18) Set file access mode for read-only for this entire execution. This must be first control card in input stream.

Col 11-14:

Key prefix (required)

LIB Ordinary library member

DEF Default algorithm

nnn 001 999 for MMP custom algorithm

nnnB 001B 999B for MBP custom algorithm

DOC Documentation on DOC file

DIT Data items in dictionary

PRO Named proforma member

RUL Business Rule

DOM Domain

Col 15-22:

Member name (ALG file only)

xxxxxxxx ALG member name

MM/DD/YY for -MAGECIDX, list members updated since this date

Col 23-23:

Separator (ALG file only)

/

,

blank

Col 24-31:

Name modifier (ALG file only) xxxxxxxx Optional suffix for member name, 1-8 characters Col 15-44: Topic name (DOC file only -- required)

xxxxxxxx Topic name of the documentation member on the DOC file

Col 15-19:

Element name (DIT file only -- required)

xxxxx Name of element on DIT file

Col 24-25:

Mode (DIT file only)

T Default -- test mode

P Production mode

Col 45-45:

Suppress heading and page number reset. For MAGECPRT and MAGECLST of multiple members when resetting to page 01 at the start of each member is not desired.

C" Continue (do not reset)

blank Default -- reset to page 01

Col 46-46:

Uppercase flag (for MAGECPRT and MAGECLST only)

U Mixed text (upper- and lowercase) wll be converted to all uppercase for output

L Default -- Text remains in upper- and lowercase on output

Col 47-48:

Page increment (only for MAGECADD and MAGECREP)

nn This controls the increment value MAGECLBR will use in generating "page" numbers as the member is being added to the file. Page number is the low-order portion of the key. The increment value will also be the page number of the first record added. If this value is 02 then the first page will be page 002, the next will be 004, etc. Default is 01 for DOC file, else 02.

Col 47-48:

Sequence column (only for MAGECPUN and MAGECPCH on ALG members)

nn Starting card column into which MAGECLBR will insert sequence numbers. The sequence numbers are actually the page number and line number within the page on the ALG file. Default is NO for -MAGECPUN and -MAGECPCH.

NO Suppresses sequence numbers

Col 49-50:

Lines per page (only for MAGECLST and MAGECPRT)

nn 01 thru 90 -- The maximum number of lines per page to print before forcing a "top of form". Default is 59.

NO Suppresses forced breaks

Col 51-54:

Entity type (DOC file only)

tttt Entity type to be used to add "prime reference" to REF file. Required only for MAGECADD DOC operations, ignored otherwise.

Col 15-24:

Domain name (for DOM key prefix only)

xxxxxxxx 20-character Domain name--valid only with the -MAGECUSE DOM and -MAGECGBL DOM operations

Note: 1. Only the MAGECADD, MAGECUSE, and MAGECDEL operations are allowed to the DIT file. The input for the MAGECADD DIT is a Cobol data definition, the dictionary definitions will be generated and added to the DIT file. The Element (ELT) definition must exist on the MAGEC dictionary prior to adding DIT definitions for that Element. 2. When new documentation is added via the MAGECADD DOC operation, MAGECLBR also adds the "prime reference" entry to the REF file for the new topic. A prime reference is one in which the key word (or key phrase) is the same as the topic name and is generated to ensure that there is at least one reference to every topic since the usual path to documentation on the DOC file is via the references from the REF file. When a topic is deleted from the DOC file all references to it are deleted from the REF file.

Printing Members

EJECT - Top-of-Page Control

When printing a member using the -MAGECPRT or -MAGECLST operations, MAGECLBR will sense EJECT lines and will skip to Top of Page. The EJECT line is not printed. An EJECT line is formatted as follows:

' EJECT'

where: — columns 1 - 11 contain blanks

columns 12 - 16 contain the literal 'EJECT' in uppercase

the remainder of the line will be ignored

SKIP and SPACE - Blank Line Insertion

During -MAGECPRT and -MAGECLST operation MAGECLBR will sense SKIP and SPACE control lines and will generate the specified number of blank lines. The line containing the SKIP or SPACE command will not be printed. These control cards are formatted as follows:

' SKIP 99'

' SPACE99'

where: — columns 1 - 11 must be blank columns 12 - 16 must contain the literal "SKIP " or "SPACE"

column 17 - 18 must contain a 2-digit number from 01 thru 99, indicating how many blank lines are to be inserted.

Note: Blank lines within the member(s) being printed are not printed, they are bypassed.

SKIP and SPACE - Overprinting/Underlining

In the SKIP and SPACE lines described above, zero (00) may be specified as the number of lines to skip, to indicate that the NEXT data line is to be printed without skipping any lines. This enables overprinting to effect special characters, such as " " or underlining.

Note: Since MAGEC does not permit entering the underscore character ( _ ) online (it is transformed to a space) special provision is made for it. In the data line immediately following the "SKIP 00" line, any occurrence of the "pseudo underscore" will be transformed into an underscore. The pseudo underscore is the uppercase letter "U".

Headings and Titles

During -MAGECPRT and -MAGECLST operations, the PAGE HEADING which MAGECLBR prints at every Top of Page, whether triggered by an EJECT line in the member being listed, or by reaching the maximum number of lines per page, will consist of a default heading with the page number displayed at the far right. The default heading is blanks if from the ALG file, or Topic Name if from the DOC file A user-defined page heading may be specified instead of this default. Up to 65 characters of heading literal may be given via the special "heading" line record(s) which may be embedded within the member being listed. The format is:

**HDG**This is the new heading (where: **HDG** = Constant in columns 1-7)

Upon encountering such a heading line, MAGECLBR will alter the heading literal. The new heading will appear as of the next Top of Page and on all subsequent Top of Page's until either the end of the member is reached or another heading line is encountered. The page number will continue to be displayed on the user-defined heading just as it did on the default heading. The page number is not reset on these heading changes; only the literal is changed.

MAGECLBR also recognizes special "title lines" within the member being printed. A title line is as:

**TTL**This is a title (where: **TTL = Constant in columns 1-7)

The title which is in columns 8 thru 67 (maximum of 60 characters) will appear in the printout with a blank line preceeding and following it and indented 5 spaces and it will automatically be underscored. The headings and titles will appear in the automatic Table of Contents which is produced on printing operations and will also appear in the Page Index which is also produced.

Suppress Reset

When multiple members are being printed in one run, the heading is reset to its default value at the end of each member, unless the "suppress reset" option is specified on the -MAGECPRT (or LST) card for that member. Specifying "suppress reset" (value = "C") is used to concatenate members so that they will be treated as one, resulting in one Table of Contents and one Page Index for a set of members. The "C" must be specified on the first -MAGECPRT or (LST) card in the set and on all subsequent ones except for the last. If the last card specifies "C", but it is not followed by any other -MAGECPRT (or LST) cards, being the last card in the run, then the "C" is ignored.

A Table of Contents will be printed at the end of each member of set of members (if continuation specified in the suppress reset option on the -MAGECPRT or LST control cards, which will include each heading and title. This Table of Contents may be placed in front of the report to produce "suitable for binding" documentation manuals. A "Page Index" will also be printed which will include all headings and titles plus other Key Word or Key Phrase entries as specified by the author using the **IDX** lines discussed below.

Page Control

During -MAGECPRT and -MAGECLST operations MAGECLBR will sense page control lines in the member being printed. Any number of page control lines may be embedded in the member. The format is:

**PAGE**xxx (where: **PAGE** = constant in columns 1-7)

xxx = a valid control value in columns 8-10

The valid control values are:

OFF Cease printing heading and page numbers.

ON Resume printing heading and page numbers.

001 - 999 Set page number to indicated value at next Top of Page.

blanks Set page number to 001 at next Top of Page.

Any other value will cause MAGECLBR to ignore the page control line and treat it as data, that is to print it. Setting the page number to any value, either explicitly or implicitly, sets heading and page number printing to "ON ".

Automatic Index of Manual

MAGECLBR will produce an index at the end of each printed member when the -MAGECPRT or -MAGECLST operations are used, and if any index control lines were encountered in the member. An index control line is coded starting in column 1 as follows:

**IDX**xxx

where: xxx = a keyword or phrase

The keyword or phrase may be up-to 65 characters in length, it will appear in the index.

Upon encountering each such index control line, an entry is generated for the Key Word or Phrase, and referring to the page number in which the index control line is found. Any given Key Word or Phrase may appear any number of times on any number of pages.

Care should be taken when using index control lines and also resetting the page number (**PAGE**nnn) in the same member since there might well be more than one page having a given number and the generated index will not differentiate between them.

Note that the Key Words or Phrases used need not actually appear in the text so that the author may enter them however they are to be presented in the index.

The **HDG** (Heading) and **TTL** (title) lines will implicitly generate an index entry as if a **IDX** line had also been coded with a Key Word equal to the new heading or title.

The maximum number of index entries is 500. The sum of all **TTL** plus **HDG** plus **IDX** lines should not exceed 500. Any beyond the 500 limit will be ignored in the page index and in the table of contents.

Splitting Large Modules

When it is necessary to add or replace a module to the files (especially the DOC file) which is larger than the maximum number of "pages" supported, then it may be divided into smaller members. When using the -MAGECPRT or -MAGECLST operations, members may be concatenated and treated as one large module using the "suppress reset" option on the control card.

Updating the Files

JCL in Member - Special Transformations

In order to permit ADDing and REPing members which contain JCL a form of "pseudo JCL" is used. MAGECLBR will make special conversions of input data characters when in "JCL mode". To set MAGECLBR into JCL mode a special control card may be included anywhere in the input data:

**JCL**START (or BEGIN, or ON, or blanks)

To remove MAGECLBR from JCL mode:

**JCL**END (or STOP, or OFF)

In the above examples the **JCL** appears in columns 1 through 7. Any number of **JCL**START and **JCL**END cards may be embedded in the input stream. They will remain in the member as added to the file. If left in the member they will direct -MAGECPCH or -MAGECPUN operations to convert the real JCL back into pseudo JCL when the member is punched. MAGECLBR will alter the following characters in "columns" 1 - 5 if in JCL mode.

It will alter the following character strings if found starting in column 1 whether in JCL mode or not:

Multiple Control Cards

When used to update the files MAGECLBR will display update statistics showing number of pages (records) deleted and added as appropriate.

Multiple control cards and operations may be included in any one execution of MAGECLBR. Any valid MAGECLBR control card (as determined by the contents of columns 1 - 10) will terminate the prior operation and initiate a new one, update statistics for each will be displayed as appropriate.

Line Lengths=

When ADDing or REPing to the files the respective line lengths must be considered or data truncation might occur. The ALG file records each contain up to 15 lines of 80 characters. The DOC file records each contain up to 15 lines of 72 characters. Any data beyond "column 72" in the member being ADDed or REPed to the DOC file will be truncated.

Maximum Number of Pages

When ADDing or REPing members consideration must be given to the size of the member and the limits for the ALG file and DOC file as to member size. On either file one record equals 15 lines (cards) of data. The record keys consist of the member name (as appropriate) with a suffix of "page number". One "page" equals 15 lines of data.

The ALG file's page number is three-digits and therefore may go as high as 999, the DOC file's page number is two-digits and may only go as high as 99. These limits restrict the maximum size of a member on either file. Specifying a page Increment (refer to control card format) can further limit the maximum size. When adding large members it may be wise to use a smaller Page Increment (01 is smallest possible) in order to accommodate the potentially large number of records needed. Incrementing the page numbers by other than 01 is done primarily to gain efficiency for online updating involving insertion of lines.

Punching Members

When punching members using -MAGECPCH or -MAGECPUN the MAGECLBR utility may be set into JCL mode via the same **JCL** control statements as for ADDing and REPing members. In the punching operations the control statements must be embedded in the member being punched. Any number of such control statements may be present to set JCL mode ON and OFF as needed. In JCL mode MAGECLBR converts real JCL into pseudo JCL as:

This pseudo JCL is compatible with that accepted into the MMPCREAT input stream as well as into the MAGECLBR utility. If JCL mode is not set ON then MAGECLBR will punch the member as is without any conversions.

The -MAGECPUN and -MAGECPCH operations will produce identical results except that -MAGECPUN will prefix each punched Member with a card to replace that Member back onto the Library (-MAGECREP card) whereas the -MAGECPCH operation will just punch the Member as is.

Punching Customization Algorithms

Online MMP's=

To punch only one specific algorithm, code your control card:

-MAGECPUN nnn pppppppp/mmmmmmmm

To punch ALL the Customization algorithms, code it:

-MAGECPUN nnn

A -MAGECREP card will be inserted in front of each algorithm punched so that they may be "turned around" as input to MAGECLBR if desired.

Batch MBP's =

To punch only one specific algorithm, code your control card:

-MAGECPUN nnnBpppppppp/mmmmmmmm

To punch ALL the Customization algorithms, code it:

-MAGECPUN nnnB

A -MAGECREP card will be inserted in front of each algorithm punched.

Printing Customization Algorithms

Online MMP's=

To print only one specific algorithm, code your control card:

-MAGECPRT nnn pppppppp/mmmmmmmm

To print ALL the Customization algorithms, code it:

-MAGECPRT nnn

Batch MBP's =

To print only one specific algorithm, code your control card:

-MAGECPRT nnnBpppppppp/mmmmmmmm

To print ALL the Customization algorithms, code it:

-MAGECPRT nnnB

Data Item Definitions

Only the -MAGECADD and -MAGECDEL operations may be used for the DIT file. A -MAGECDEL operation will delete all the DIT file definitions for an Element. The -MAGECADD operation will generate DIT file definitions from an input Cobol data definition or "copybook". If a Cobol definition already exists then you can save much time using this feature to automatically define the Data Items for the Element (record). You should always use the online DITLST and DITSEE functions to verify what was generated and to modify the default editing criteria where it is appropriate.

The input Cobol definition should immediately follow the control card(s). The Element Name specified in columns 15-19 must be the name of an Element defined on the MAGEC ELT file. There must not be any Data Item definitions already on the DIT file.

The MAGEC standard is for Cobol data names to be prefixed with the Element Name. If the input Cobol definition already has a prefix on the data names then you can trim it off using the **TRM** control card.

-MAGECADD DIT eeeee

**TRM**xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx (where: eeeee = the Element name)

x...x = the prefix (up to 32 characters long) to be trimmed from the data names

Only one **TRM** card can be in effect at a time, if another one is encountered it will replace the prior one. They may be embedded anywhere in the input Cobol data definition. The Mode which is specified in columns 24 - 31 of the -MAGECADD card will default to T if left blank.

Index Listing

To print a hardcopy Index Listing you can use the MAGECLBR control cards:

-MAGECIDX LIB (Library Index)

-MAGECIDX DOC (Documentation Index)

-MAGECIDX FCD (Online Function Codes Index)

-MAGECIDX SIF (List of Operators from SIF-file)

The Index Report for the LIB and DOC will show how many pages (records) can be recovered by "squeezing" each member. Squeezing a member is done by punching (-MAGECPUN) it and then replacing it to the file ( -MAGECREP ). To assist you in doing this, the Index Report will generate the -MAGECPUN cards for each member which shows that pages could be recovered.

Where-Used Reports

You can produce a variety of very useful Where-Used reports from the MAGEC dictionary. To do that you execute MAGECLBR using control cards as:

-MAGECUSE LIB nnnnnnnn/mmmmmmmm
-MAGECUSE ELT eeeee
-MAGECUSE DIT dddddddddddddddddddddddddddddd
-MAGECUSE DOM zzzzzzzzzzzzzzzzzzzz

where: nnnnnnnn = member name

mmmmmmmm = modifier

eeeee = element name

ddd...ddd = up to 30 character dataname

zzz...zzz = up to 20 character domain name

The first example above (LIB) will find all references to a member (copybook). The second example (ELT) will find all references to an Element, whether it is in the primary Data Class for an application or just a joined Data Class. The third example (DIT) will find all references to a Data Item (field).

When searching for references to a DIT, you have the option of giving an exact argument (dataname) or a generic argument. Generic arguments can be given using the dot ( . ) as a "wild card", for example:

-MAGECUSE DIT CUS01-Z.P (would find references to CUS01-ZIP and to CUS01-ZAP, etc.)

-MAGECUSE DIT ......ZIP-CODE (would find references to CUS01-ZIP-CODE and IVC01-ZIP-CODE, etc.)

You can also use a leading or trailing (or both) asterisk ( * ) to make your search even more generic, for example:

-MAGECUSE DIT CUS01-ZIP* (would find references to CUS01-ZIP, CUS01-ZIP-CODE, CUS01-ZIPPER, etc.)

Global Changes for Domains

In addition to listing the where-used report for a Domain, you can globally change all Data Items belonging to a Domain. The global change function will make the necessary changes to ensure that all the Data Items belonging to a Domain have compatible definitions [with the Domain's]. To do a global change, execute MAGECLBR using a control cards as:

-MAGECGBL DOM zzzzzzzzzzzzzzzzzzzz

where: zzz...zzz = up to 20 character domain name

For example, to change all zip codes from five digits to nine digits [assuming that they are all defined as belonging to the Domain named ZIP-CODE, which you have defined].

1) alter the definition of the Domain, ZIP-CODE using the online DOMCHG function

2) execute MAGECLBR using the -MAGECGBL DOM ZIP-CODE control card

You should note that while the global change facility will alter the DIT definitions for all ZIP-CODE items, it will not alter the ELT, DCL, KYF, or copybook definitions. You may well need to change record or element lengths to accommodate a longer zip code field within the records. Also, you might need to change screen fields to accommodate the longer fields.

MAGECLBR Jobstream

VSE

* $$ JOB JNM=MAGECLBR,CLASS=F
* $$ PRT CLASS=V
// JOB MAGECLBR
// EXEC PROC=MAGECLIB   -pvt. libs & DLBL's for dictionary
// ASSGN SYS006,READER
// ASSGN SYS005,PUNCH
// ASSGN SYS007,SYSLST
// EXEC MAGECLBR,SIZE=(AUTO,10K)
-MAGEC...                       ------Control Card--------
--------Data Cards--------(if appropriate)
/*
/&
* $$ EOJ

z/OS

//MAGECLBR JOB CLASS=0,MSGCLASS=0
//STEP1    EXEC PGM=MAGECLBR
    -or- PGM=MAGECLBR,PARM='READONLY'  (opens files read only)
//STEPLIB DD DSN=MAGEC.LOADLIB,DISP=SHR
* * * * * * * *  DD'S for dictionary files
//SYSOUT   DD  SYSOUT=W
//SYS005    DD  DSN=.....,DCB=(BLKSIZE=....) -- "punch" output
//SYS007   DD  SYSOUT=W
//SYS006   DD  *
-MAGEC...                        --------Control Card-------
--------Data Cards--------(if appropriate)
/*
//

PC

Edit, as necessary, the control cards found in the file named:

\MAGxx\MAGECLBR.RDR

At the prompt, enter:

MAGLBREX

MAGINIT

Initialize a VSAM File

The MAGINIT batch program is used to initialize a VSAM file after the file has been defined in the VSAM catalog (master or user) for the first time. MAGINIT can be used for any VSAM file that is defined to the VSAM catalog, but will not be initially loaded using the IDCAMS utility.

If you are using PC MAGEC you do not need to execute IDCAMS to define your new file, MAGINIT actually does the jobs of both creating and initializing your file. It extracts the file specifications fom the MAGEC dictionary DCL, KYF, and ELT definitions; therefore, you must first enter them.

MAGINIT Jobstream

VSE

* $$ JOB JNM=MAGINIT,CLASS=F
* $$ PRT CLASS=V
// JOB MAGINIT          INITIALIZE A VSAM FILE
// ASSGN SYS020,DISK,VOL=......
// DLBL  NEWFILE,'....................',,VSAM
// EXEC MAGINIT,SIZE=(AUTO,10K)
/*
/&
* $$ EOJ

z/OS

//MAGINIT  JOB CLASS=0,MSGCLASS=0
//STEPLIB  DD DSN=MAGEC.LOADLIB,DISP=SHR
//STEP1    EXEC PGM=MAGINIT
//NEWFILE  DD  DSN=....................,DISP=OLD
//

PC

At the prompt enter:

MAGINIT xxx

where: xxx = the Data Class to be initialized

MALUTIL/MALRPT

MAGEC Activity Logging Utility

The MALUTIL batch program is used to extract statistics from the MAGEC Activity Logging file (MAL) and to add them to the tape file which holds cumulative statistics records. For complete documentation on this utility and on MALRPT refer to the MAGEC Security System documentation. The MAGEC Activity Logging must be turned on in order for there to be any statistics on the file. To turn logging on or off, set the MAG-ACT-LOG parameter in MAGEC Table #243 to YES or NO, as appropriate. Use the online command

243CHG MAG-ACT-LOG

MAGEC Activity Log Report Utility

The MALRPT batch utility produces a variety of reports from the cumulative Logging statistics data on the tape file produced by the MALUTIL program. For complete documentation on it refer to the MAGEC "Security" chapter.

Note: Refer to the topic Activity Logging in the "Security" chapter of this Programmer's Reference Guide for details regarding MALRPT control card formats.

MALUTIL Jobstream

VSE

* $$ JOB JNM=MALUTIL,CLASS=F
* $$ PRT CLASS=V
// JOB MALUTIL       EXTRACT MAL- APPEND TO HISTORY TAPE
// EXEC PROC=MAGECLIB   -pvt libs & DLBL's for dictionary
// TLBL SYS010,'MAGEC.ACTIVITY.LOG',99/365
// ASSGN SYS010,IGN           (input tape IGN'd first run)
// TLBL SYS011,'MAGEC.ACTIVITY.LOG',99/365
// ASSGN SYS011,181
// DLBL SYS020,'WORK.FILE',0,SD
// EXTENT SYS020,xxxxxx,1,0,548000,4000
// ASSGN SYS020,DISK,VOL=xxxxxx,SHR
// EXEC MALUTIL
/*
/& EOJ
* $$ EOJ

z/OS

//MALUTIL  JOB  CLASS=_,MSGCLASS=_
//STEP1    EXEC PGM=MALUTIL
//STEPLIB  DD  DSN=MAGEC.LOADLIB,DISP=SHR
* * * * * * * *   DD'S for dictionary files
//SYSOUT   DD  SYSOUT=W
//SYS020   DD DSN=&&WORKFIL,SPACE=(100,(100,100)),
//         UNIT=SYSDA,DISP=(NEW,DELETE),
//         DCB=(LRECL=60,BLKSIZE=6000,RECFM=FB)
//SYS010   DD  DSN=MAGEC.ACTIVITY.LOG(0),DISP=OLD,UNIT=TAPE,
//         LABEL=(1,SL,EXPDT=99000),
//         DCB=(PTR,GDG,LRECL=60,BLKSIZE=6000,RECFM=FB)
//SYS011   DD  DSN=MAGEC.ACTIVITY.LOG(+1),DISP=(NEW,CATLG),
//         UNIT=TAPE,
//         DCB=(PTR,GDG,LRECL=60,BLKSIZE=6000,RECFM=FB),
//         LABEL=(1,SL,EXPDT=99000)
//

Note: 'SYS010 DD DUMMY' used the first time this is run.

MALRPT Jobstream

VSE

* $$ JOB JNM=MALRPT,CLASS=F
* $$ PRT CLASS=V
// JOB MALRPT        PRINT REPORT FROM MAL HISTORY TAPE
// EXEC PROC=MAGECLIB   -pvt libs & DLBL's for files
// ASSGN SYS007,SYSLST
// ASSGN SYS010,181
// TLBL SYS010,'MAGEC.ACTIVITY.LOG'
// ASSGN SYS001,DISK,VOL=xxxxxx,SHR
// DLBL SORTWK1,'SORT.WORK.FILE',0,SD
// EXTENT SYS001,xxxxxx,1,0,548000,4000
// EXEC MALRPT
MALRPT 000000 999999
/*
/& EOJ
* $$ EOJ

z/OS

//MALRPT   JOB  CLASS=_,MSGCLASS=_
//STEP1    EXEC PGM=MALRPT
//STEPLIB  DD  DSN=MAGEC.LOADLIB,DISP=SHR
* * * * * * * *   DD'S for dictionary files
//SORTWK1 DD DSN=&&WORKFIL,SPACE=(100,(100,100)),UNIT=..
etc.
//SYS010   DD  DSN=MAGEC.ACTIVITY.LOG(0),DISP=OLD,UNIT=TAPE,
//         LABEL=(1,SL,EXPDT=99000),
//         DCB=(PTR,GDG,LRECL=60,BLKSIZE=6000,RECFM=FB)
//SYSOUT   DD  SYSOUT=W
//SYS007   DD  SYSOUT=W
//SYSIN    DD  *
MALRPT 000000 999999
/*
//

MMPCREAT

Generate MMP

The MMPCREAT jobstream is used to generate, compile, and link an MMP from the specifications and Customization Algorithms coded by the developer. This process may be done at any time. It is analogous to a simple compile and link which would be used when developing programs using Cobol. The non-procedural specification (from MSKDEF, etc.) and the Customization Algorithms may be changed and the application regenerated as often as desired. If the mask definition (MSKDEF) has been changed in such a manner as to require regenerating the mask (MSKCREAT) then that should be accomplished before regenerating the MMP since the mask "copybook" needs to be the latest version in order for the MMP to operate properly. The generated MMP verifies that the copybook is the current one at execution time.

The MMPCREAT jobstream consists of:

MMPCRE     Generate MMP

DFHECP1$     Translator (if CICS)

ASSEMBLY    SIGNON macro (if Westi)

Cobol Compiler    (standard compile)

Linkedit    (standard link)

In the DOS environment the output of MMPCRE is a complete compile and link jobstream which is placed into the punch queue with disposition "I"; it becomes an input "reader" queue when MMPCRE reaches end of job. This is because the DOS pre-compiler does not accept its input from a disk file. In z/OS the output from MMPCRE is a disk file of Command-Level source code which is passed to the pre-compiler, etc.

The load module or phase naming conventions for MAGEC must be observed for all online MMP's. They are:

MMPmmm

where: mmm = MMP number* (alphanumeric) in all cases

*The format for MMP numbers is:
9XX
where: 9 = a digit (0 thru 9)

x = an alphanumeric character

In the PC MAGEC environment the executable programs are named:

\MAGxx\MMPmmm.EXE

Control Cards

There are four possible control cards accepted into the MMPCRE utility program. They are:

Card 1
Specifies overall processing parameters and also which application is to be generated. Only one of these cards may appear in any one run.

Card 2
Specifies that a General Purpose library member is to be "included" into the input stream. There may be any number of these in any one run. An included member may in turn contain more of these Cards (nesting) without limitations except that the maximum "nesting level" must not be exceeded. The maximum is usually set to 10 levels.

Card 3
Specifies that the -MAGECINC (Card 3) which follows this card is "conditional", that means that the member is to be included only if it is not already being included elsewhere in this program.

Model & MMP Type prior to MAGEC 2.0

Control Card 1 and 2 must be the first two cards into MMPCRE, if used at all. If Card 2 is omitted then MMPCRE uses the default options (i.e. type of MMP specified in the SHD record--MODELMMP, MODELWIN, etc). The only three entries for this Control Card are:

&ELMMP    Standard 9-function MMP (default)

&LOCAT    Browse functions only (LOC, SCN, and FND)

&MAINT    Maintenance functions only (obsolete)

The last option (MAINT) is obsolete and only supported for compatibility with older applications systems generated in earlier releases of MAGEC. The type specified in Card 2 must agree with the "model" which is used. There are three possible models:

MODELMMP    Standard nine functions

MODLOCAT    Browse only model

MODMAINT    Maintenance only (obsolete)

Since the "model" MMP to be used must agree with the type which is specified on Card 2 there is provision made for MMPCREAT to fill in the appropriate member name on the -MAGECINC card. By coding it as:

...+....1....+....2....+....3....+....4....+.... -MAGECINC MOD&TYP

MMPCRE will replace the "&TYP" with the type from Card 2, resulting in a Card 3 such as one of the following:

...+....1....+....2....+....3....+....4....+.... -MAGECINC MODELMMP

-MAGECINC MODLOCAT

-MAGECINC MODMAINT

Since the default Card 2 (if Card 2 is omitted) specifies a type of ELMMP, by omitting Card 2 and using the "&TYP" on Card 3 the MMPCRE program uses the model as specified in the SHD record for the application in Control Card 1.

Pseudo JCL

MMPCRE will accept pseudo JCL in its input stream and will convert it into real JCL as it passes it to the output stream. The transformations are:

VERIFY Option

MAGEC Applications may be generated to access any file(s) available to the online environment (CICS, WESTI, Realia, VM/CMS, etc.). Since MAGEC has no way of ensuring that the data on those files will always be valid and since bad data (non-numeric data in numeric fields) could cause Data Exceptions (Program Checks) or other undesirable results, an option is included for MAGEC to generate the MMP's with automatic verification of the numeric fields. If the verification option is "on" then the generated MMP(s) will detect invalid numeric data in the record(s) read and will not attempt to process the bad fields, instead an error message will be presented to the Operator and the offending fields will be displayed as highlighted asterisks ( * ) in the screen mask, valid fields will be displayed as usual. The Operator may overkey the asterisks to correct the bad data. To set the Verify option on, code "VERIFY" in the Verify Option field in the Screen Header panel (online). To set it off code NO. Leaving column 45 - 50 blank tells MAGEC to get the Verify Option from the SHD record. We suggest that you leave it blank in the control card.

MMPCRE Control Cards

Columns

Description

Card 1 Format:

1 - 9

Constant 'MMPCRE '.

10 - 12

Mask (SHD) number Format: 9xx, where 9 = digit (0 9) and x = alphanum. char.

13 - 14

Blank.

15 - 24

TP Monitor Valid values: CICS or MICR or WESTI or REALIA.

25 - 34

Source Library Valid values: MAGEC, ADRLIB, or CAMLIB.

35 - 37

Operating System Valid values: DOS or OS or WIN or WNT or OS2.

38 - 44

Database System Valid values: VSAM.

45 - 50

Verify option Valid values: VERIFY, NO or blanks.

51

Blank.

52 - 56

Cobol level Valid values: COB74 or COB85 (default is COB74).

58 - 60

Display mode Valid values: TXT or GUI

61

GUI Trace Valid values: Y or N or blank

62

MAGEC Version (of program to be generated) Valid values: 2 or 3

Card 2 Format:

1 - 10

Constant '-MAGECINC'.

11 - 28

Member name (and Modifier) of the member to be included. Separate Name/Modifier with a Slash (/).

29 - 80

Comments - ignored.

Card 3 Format:

1 - 9

Constant: -IFUNIQUE.

10 - 80

Blank.

Control card examples:

....+....1....+....2....+....3....+....4....+....5....+....6....
MMPCRE  999  CICS       MAGEC  DOSVSAM         COB85 TXT N 3
-MAGECINC &MDL
-IFUNIQUE
-MAGECINC CUS01-C/COPY

Note: Refer to the MAGEC "Librarian" chapter for more information on the -MAGECINC and -IFUNIQUE statements (see "Conditional MAGECINC's").

MMPCREAT Jobstream

VSE -- CICS

* $$ JOB JNM=MMPCREAT,CLASS=0
* $$ PRT CLASS=Q
* $$ PUN CLASS=0,DISP=I,PRI=9
// JOB MMPCREAT          generate, compile, link MAGEC MMP
// EXEC PROC=MAGECLIB    -pvt. libs. & DLBL's
// ASSGN SYS006,SYSIPT
// ASSGN SYS007,SYSLST
// ASSGN SYS005,SYSPCH
// EXEC MMPCRE,SIZE=(AUTO,20K)
MMPCRE  mmm  CICS      MAGEC     DOSVSAM
¢¢ JOB  MMP&MMP Command Level Compile
¢¢ DLBL IJSYSPH,'MAGEC.SYSPCH',0,SD
¢¢ EXTENT SYSPCH,......,1,0,.....,.....
 ASSGN SYSPCH,DISK,VOL=......,SHR
¢¢

EXEC DFHECP1$,SIZE=256K
 CBL NOOPT,APOST,LIB,LANGLVL(1)
-MAGECINC &MDL
¢F
 CLOSE SYSPCH,PUNCH
¢¢ JOB MMP&MMP
¢¢ EXEC PROC=MAGECLIB
¢¢ OPTION CATAL
 ACTION CLEAR
 PHASE MMP&MMP,*
 INCLUDE DFHECI
¢¢ DLBL IJSYSIN,'MAGEC.SYSPCH',0,SD
¢¢ EXTENT SYSIPT,......,1,0,.....,.....
 ASSGN SYSIPT,DISK,VOL=......,SHR
¢¢ EXEC FCOBOL,SIZE=180K
¢F
 CLOSE SYSIPT,READER
¢¢ EXEC BOMIFBAD
¢¢ EXEC LNKEDT
¢F
¢J
¢ $$ EOJ
/*
/&
* $$ EOJ

Note: mmm = Mask (SHD) number

DOS/VSE/SP -- CICS

* $$ JOB JNM=MMPCREAT,CLASS=0,USER=MAGEC
* $$ PRT CLASS=Q
* $$ PUN CLASS=0,DISP=I,PRI=9
// JOB MMPCREAT
// EXEC PROC=MAGECLIB    -pvt. libs. & DLBL's for dictionary
// OPTION NODUMP
// ASSGN SYS006,SYSIPT
// ASSGN SYS007,SYSLST
// ASSGN SYS005,SYSPCH
// EXEC MMPCRE,SIZE=(AUTO,20K)
MMPCRE   mmm    CICS      MAGEC     DOSVSAM
¢ $$ JOB JNM=MMP&MMP,DISP=D,CLASS=A,NTFY=YES
¢/ JOB MMPCREAT
¢ $$ PUN DISP=I,PRI=9,CLASS=A
¢/ ASSGN SYS005,SYSRDR
¢/ EXEC IESINSRT
¢ $$ LST DISP=D,CLASS=Q,PRI=3
¢/ JOB MMP&MMP   COMPILE PROGRAM MMP&MMP
¢/ SETPARM CATALOG=1
¢/ LIBDEF PHASE,CATALOG=DPLIB.LIBRARY
¢/ OPTION ERRS,SXREF,SYM,CATAL,NODECK
 PHASE MMP&MMP,*
 INCLUDE DFHECI
¢/ EXEC FCOBOL,SIZE=256K
 CBL LIB,LANGLVL(1),APOST,NOADV,BUF=2048,SXREF
¢ $$ END
¢/ ON $CANCEL OR $ABEND GOTO ENDJ2
¢/ OPTION NOLIST,NODUMP,DECK
¢/ EXEC DFHECP1$,SIZE=256K
 CBL XOPTS(CICS DEBUG LANGLVL(1))
-MAGECINC &MDL
¢F
¢. ENDJ2
¢/ EXEC IESINSRT
¢F
¢/ EXEC LNKEDT,SIZE=256K
$ $$ EOJ
¢ $$ END
¢J
¢ $$ EOJ
/*
/&
* $$ EOJ

Note: mmm. = Mask (SHD) number

VSE -- WESTI

* $$ JOB JNM=MMPCREAT,CLASS=0,USER=MAGEC
* $$ PRT CLASS=Q
* $$ PUN CLASS=0,DISP=I,PRI=9
// JOB MMPCREAT         generate, compile, link MAGEC MMP
// EXEC PROC=MAGECLIB   -pvt libs & DLBL'S for dictionary
// ASSGN SYS006,SYSIPT
// ASSGN SYS007,SYSLST
// ASSGN SYS005,SYSPCH
// EXEC MMPCRE,SIZE=(AUTO,20K)
MMPCRE   mmm  WESTI     MAGEC     DOSVSAM
¢ $$ JOB JNM=MMP&MMP,CLASS=0
¢ $$ PRT CLASS=Q
¢¢ JOB MMP&MMP          Signon Assembly and Catalr
¢¢ EXEC PROC=MAGECLIB   -pvt. libs.and DLBLs for dictionary)
-MAGECINC WESTI/SIGNON
¢¢ OPTION NODECK
¢¢ EXEC FCOBOL,SIZE=128K
CBL LIB,CLIST,SXREF,OPT,NOTRUNC,BUF=4096
-MAGECINC &MDL
¢F
¢¢ EXEC BOMIFBAD
¢¢ EXEC LNKEDT
¢F
¢J
¢ $$ EOJ
/*
/&
* $$ EOJ

Note: mmm. = Mask (SHD) number

DOS/MVT/VSE -- WESTI

// JOB MMPCREAT,CL=x,RO=L
// PROC MAGECLIB
// RPT SYSPCH,D=R,DSN=JNUM.DECK1
// ASSGN SYS006,SYSIPT
// ASSGN SYS007,SYSLST
// ASSGN SYS005,SYSPCH
// EXEC MMPCRE,R=A,GET=500K
MMPCRE   mmm  WESTI     MAGEC     DOSVSAM
¢¢ JOB MMP&MMP,CL=x,RO=L
¢¢ PROC MAGECLIB
-MAGECINC WESTI/SIGNON
¢¢ OPTION NODECK,TEST
¢¢ EXEC FCOBOL,SIZE=512K
 CBL LIB,SUPMAP,OPT,BUF=256K
-MAGECINC &MDL
¢F
¢¢ EXEC BOMIFBAD
¢¢ EXEC LNKEDT
¢F
¢J
/*
/&

Note: mmm is the Mask (SHD) number

z/OS -- C I C S

//MMPCREAT JOB CLASS=x,MSGCLASS=x       gen/compile/link MMP
//MMPCRE EXEC  PGM=MMPCRE,REGION=1024K
//STEPLIB  DD  DSN=MAGEC.LOADLIB,DISP=SHR
 * * * * * * * *   DD's for VSAM dictionary files
//SYS005   DD  DSN=&&OSJOB,DISP=(NEW,PASS),UNIT=SYSDA,
//         DCB=(RECFM=FB,LRECL=80,BLKSIZE=4000),
//         SPACE=(CYL,5)
//SYS007   DD SYSOUT=*
//SYSOUT   DD SYSOUT=*
//SYSUDUMP DD SYSOUT=*
//SYSPRINT DD SYSOUT=*
//SYS006   DD *
MMPCRE   mmm  CICS      MAGEC     OS VSAM
-MAGECINC &MDL
/*
//STEP2    EXEC PGM=DFHECP1$,PARM='LANGLVL(2)'
//STEPLIB  DD DSN=CICS.LOADLIB,DISP=SHR
//            DCB=(RECFM=FB,LRECL=80,BLKSIZE=4000),
//            SPACE=(CYL,5)
//SYSPRINT DD SYSOUT=*
//SYSPUNCH DD DSN=&&SYSCIN,DISP=(NEW,PASS,DELET),
//            UNIT=SYSDA,SPACE=(4560,(10,10),RLSE),
//            DCB=(RECFM=FBS,LRECL=80,BLKSIZE=4560)
/*
//COMPILE  EXEC PGM=IKFCBL00,REGION=512k,COND=(4,LT),
// PARM='BUF=256K,APOST,LIB,NODYNAM,OPT,RESIDENT,NOTRUNC'
* LANGLVL must agree with LANGLVL for DFHECP1$
//STEPLIB  DD DSN=MAGEC.LOADLIB,DISP=SHR
//         DD DSN=CICS.COBLIB,DISP=SHR
//SYSLIB   DD DSN=MAGEC.LOADLIB,DISP=SHR
//SYSUT1   DD UNIT=SYSDA,SPACE=(460,(700,100))
//SYSUT2   DD UNIT=SYSDA,SPACE=(460,(700,100))
//SYSUT3   DD UNIT=SYSDA,SPACE=(460,(700,100))
//SYSUT4   DD UNIT=SYSDA,SPACE=(460,(700,100))
//SYSUT5   DD UNIT=SYSDA,SPACE=(460,(700,100))
//SYSUT6   DD UNIT=SYSDA,SPACE=(460,(700,100))
//SYSIN1   DD UNIT=SYSDA,SPACE=(460,(700,100))
//SYSIN2   DD UNIT=SYSDA,SAPCE=(460,(700,100))
//SYSIN    DD DSN=&&SYSCIN,DISP=(OLD,DELETE),UNIT=SYSDA
//SYSLIN   DD DSN=&&LOADSET,DISP=(MOD,PASS),UNIT=SYSDA,
//            SPACE=(80,(500,100))
//SYSPRINT DD SYSOUT=*
//SYSTERM  DD SYSOUT=*
//SYSPUNCH DD DUMMY
//LKED     EXEC PGM=IEWL,PARM='XREF,NCAL,LIST',COND=(8,LT)
//          ,REGION=192K
//SYSLIB   DD DSN=MAGEC.LOADLIB,DISP=SHR
//         DD DSN=CICS.LOADLIB,DISP=SHR
//SYSLMOD  DD DSN=MAGEC.LOADLIB,DISP=SHR
//SYSUT1   DD UNIT=SYSDA,
//            SPACE=(1024,(200,20)),DCB=BLKSIZE=1024
//SYSUT2   DD UNIT=SYSDA,
//            SPACE=(1024,(200,20)),DCB=BLKSIZE=1024
//SYSUT3   DD UNIT=SYSDA,
//            SPACE=(1024,(200,20)),DCB=BLKSIZE=1024
//SYSUT4   DD UNIT=SYSDA,
//            SPACE=(1024,(200,20)),DCB=BLKSIZE=1024
//SYSPRINT DD SYSOUT=*
//SYSLIN   DD DSN=CICS.COBLIB(DFHEILIC),DISP=SHR
//         DD DSN=&&LOADSET,DISP=(OLD,DELETE)
//         DD *
 INCLUDE SYSLIB(MAGECSET)
 NAME MMPxxx(R)
//

Note: xxx is the MMP number. mmm is the Mask (SHD) number.

z/OS -- COBOLII

//U2MSI1GN  JOB (SYST,MSI),MMPCREAT,CLASS=M,MSGCLASS=X,
//         MSGLEVEL=(1,1),NOTIFY=U2MSI1,REGION=1M
//MMPCRE    EXEC PGM=MMPCRE
//STEPLIB   DD   DSN=MAGEC.LOADLIB,DISP=SHR
********* DD's for MAGEC Dictionary files
//SYS005    DD  DSN=&&OSJOB,DISP=(NEW,PASS),UNIT=WORK,
//          DCB=(RECFM=FB,LRECL=80,BLKSIZE=4000),
//          SPACE=(CYL,20)
//SYS007    DD  SYSOUT=*
//SYSOUT    DD  SYSOUT=*
//SYSPRINT  DD  SYSOUT=*
//SYS006    DD  *
MMPCRE   mmm  CICS      MAGEC     OS VSAM   NO     COB85
-MAGECINC &MDL
//TRN2     EXEC PGM=DFHECP1$,
//            PARM=(DEBUG,EDF,COBOL2,NUM,NOSEQ,OPT,NOSOURCE,
//           VBREF),REGION=2M
//STEPLIB  DD  DSN=CICS170.LOADLIB,DISP=SHR
//SYSLIB   DD  DSN=CICS170A.MACLIB,DISP=SHR
//SYSPRINT DD  SYSOUT=*
//SYSPUNCH DD  DSN=&&SYSCIN,DISP=(,PASS),UNIT=WORK,
//             DCB=(LRECL=80,BLKSIZE=3120,RECFM=FB),
//             SPACE=(3120,(100,10),RLSE)
//SYSIN   DD  DSN=&&OSJOB,DISP=(OLD,DELETE)
//COB2 EXEC  PGM=IGYCRCTL,REGION=2M,
//       PARM=(NODYNAM,RENT,ADV,NONAME,NOFDUMP,'TRUNC(OPT)',
//             NOSSRANGE,'BUFSIZE(23440)')
//STEPLIB  DD  DSN=SYS1.COB2COMP,DISP=SHR
//         DD  DSN=SYS1.COB2CICS,DISP=SHR
//SYSPRINT DD  SYSOUT=*
//SYSLIB   DD  DSN=CICS170A.COBLIB,DISP=SHR
//SYSUT1   DD  UNIT=WORK,SPACE=(CYL,(5,5))
//SYSUT2   DD  UNIT=WORK,SPACE=(CYL,(5,5))
//SYSUT3   DD  UNIT=WORK,SPACE=(CYL,(5,5))
//SYSUT4   DD  UNIT=WORK,SPACE=(CYL,(5,5))
//SYSUT5   DD  UNIT=WORK,SPACE=(CYL,(5,5))
//SYSUT6   DD  UNIT=WORK,SPACE=(CYL,(5,5))
//SYSUT7   DD  UNIT=WORK,SPACE=(CYL,(5,5))
//SYSLIN   DD  DSN=&LOADSET,UNIT=HSMDA,DISP=(NEW,PASS),
//             SPACE=(CYL,(5,1))
//SYSIN    DD  DSN=&&SYSCIN,DISP=(OLD,DELETE)
//LKED2  EXEC  PGM=IEWL,PARM='LIST,MAP,NCAL',REGION=2M,
//       COND=(8,LE,COB2)
//SYSLMOD  DD  DSN=MAGEC.LOADLIB2,DISP=SHR
//SYSLIB   DD  DSN=SYS1.COB2LIB,DISP=SHR
//         DD  DSN=SYS1.COB2CLIB,DISP=SHR
//         DD  DSN=CICS170.LOADLIB,DISP=SHR
//SYSUT1   DD  UNIT=WORK,SPACE=(CYL,(1,1))
//SYSPRINT DD  SYSOUT=*
//SYSLIN   DD  DSN=CICS170A.COBLIB(DFHEILIC),DISP=SHR
//         DD  DSN=*.COB2.SYSLIN,DISP=(OLD,DELETE)
//         DD  *
   INCLUDE SYSLMOD(MAGECSET)
   INCLUDE SYSLIB(IGZEBST)
   NAME MMPxxx(R)
//

Note: xxx is the MMP number. mmm is the Mask (SHD) number.

PC

From within Windows or OS/2 you can execute MMPCREAT by selecting the icon from the MAGEC group or folder, a dialog box will prompt you for the MMP# plus debugger options (if desired).

From within GUI MAGEC you can execute MMPCREAT from the Developer's menu panel for Online MMP development. A window will pop up asking you for options such as GUI Trace or Animator, both of which are debugging aids.

At the prompt, enter:

MMPCREAT mmm ANIMATE g

where: mmm= Mask (SHD) number

ANIMATE= the optional parameter telling MMPCREAT to generate and compile for Micro Focus Animation

g= the optional parameter telling MMPCREAT to generate and compile for graphical debugging using MAGEC's GUI Trace facility Valid values are Y or N (or blank)

MBPCREAT

Generate MBP - MAGEC Batch Program

The MBPCREAT jobstream is used to generate, compile, and link an MBP from the specifications and Customization Algorithms coded by the developer. This process may be done at any time. It is analogous to a simple compile and link which would be used when developing programs using Cobol. The non-procedural specification (from RPTDEF, etc.) and the Customization Algorithms may be changed and the batch program regenerated as often as desired.

The MBPCREAT jobstream consists of:

MBPCRE     Generate MBP

Cobol Compiler    (standard compile)

Linkedit     (standard link, naming convention)

In the DOS environment the output of MBPCRE is a complete compile and link jobstream which is placed into the punch queue with disposition "I", it becomes an input "reader" queue when MBPCRE reaches end of job. In z/OS the output from MBPCRE is a disk file of Cobol source code which is passed to the compiler.

The load library member or phase naming conventions for MAGEC must be observed for all MBP's. They are:

MBPmmmB

where: mmm = MBP number* in all cases

*MBP numbers must follow the format:

9XX

where: 9 = a digit (0 thru 9)

XX = two alphanumeric characters

Control Cards

There are three possible control cards accepted into the MBPCRE utility program. They are:

Card 1

Specifies overall processing parameters and also which batch program is to be generated. Only one of these cards may appear in any one run.

Card 2

Specifies that a general purpose library member is to be "included" into the input stream. There may be any number of these in any one run. An included member may in turn contain more of these cards (nesting) without limitations except that the maximum "nesting level" must not be exceeded. The maximum is usually set to 10 levels.

Card 3

Specifies that the member to be included (see Card 2) is to be included only if it has not been included elsewhere in this program.

Pseudo JCL

MBPCRE will accept pseudo JCL in its input stream and will convert it into real JCL as it passes it to the output stream. The transformations are:

VERIFY Option

MAGEC Applications may be generated to access any file(s) available to the operating system environment. Since MAGEC has no way of ensuring that the data on those files will always be valid and since bad data (non-numeric data in numeric fields) could cause Data Exceptions (Program Check Abends) or other undesirable results, an option is included for MAGEC to generate the MBP's with automatic verification of the numeric fields. If the verification option is "on" then the generated MBP(s) will detect invalid numeric data in the record(s) read and will handle the bad fields in accordance with the VERIFY option used at compile time. The following list shows the processing action for each of the valid values for the VERIFY Option:

Verify Option    MBP Processing

NO

Permit numeric operation to cause Data Exception abend.

ACCEPT

Change value in field with non-numeric data to Zero and continue normal processing.

VERIFY

Change value in field with non-numeric data to Zero, generate an error message in report about the VERIFIED field, and continue processing.

The VERIFY option can be selected through a control card parameter only if the "NO" option was selected for the batch program with the BCHPGM function. If a value other than "NO" was specified for the VERIFY option in the program's Header record, the control card options will be ignored. The options on the card are:

VERIFY

Code "VERIFY" in columns 45 thru 50.

ACCEPT

Code "ACCEPT" in columns 45 thru 50.

OFF or NO

Code "NO " in columns 45 thru 50.

A minor saving of overhead can be acheived by setting the VERIFY option OFF.

MBPCRE Control Cards

Columns

Description

Card 1 Format:

1 - 9

Constant "MBPCRE ".

10 - 12

Report Number.

13

Constant "B".

14

Blank.

15 - 24

Filler.

25 - 34

Source Library Valid values: MAGEC, ADRLIB, or CAMLIB.

35 - 37

Operating System Valid values: DOS or OS.

38 - 44

Database system VSAM is the only valid value.

45 - 50

Verify option Valid values: VERIFY or NO or ACCEPT or blanks.

52 - 56

Cobol level: COB85 or COB74

57 - 80

Blank.

Card 2 Format:

1 - 10

Constant '-MAGECINC'.

11 - 28

Member name and Modifier (if appropriate) of the member to be included. Separate Name/Modifier with a Slash (/).

29 - 80

Comments - ignored.

Card 3 Format:

1 - 10

Constant '-IFUNIQUE'.

Control card examples:

....+....1....+....2....+....3....+....4....+....5....+....6 MBPCRE 999B MAGEC DOSVSAM -IFUNIQUE -MAGECINC MOD&TYP

Note: Refer to the "Librarian" chapter for more detailed information on the -MAGECINC and -IFUNIQUE (see "Conditional MAGECINC") statements.

MBPCREAT Jobstream

VSE

* $$ JOB JNM=MBPCREAT,CLASS=0
* $$ PRT CLASS=Q
* $$ PUN CLASS=0,DISP=I,PRI=9
// JOB MBPCREAT             gen, compile, link MAGEC MBP
// EXEC PROC=MAGECLIB    -pvt. libs.& DLBL's for dictionary
// ASSGN SYS006,SYSIPT
// ASSGN SYS007,SYSLST
// ASSGN SYS005,SYSPCH
// EXEC MBPCRE,SIZE=(AUTO,20K)
MBPCRE  rrrB    MAGEC     DOSVSAM
¢ $$ JNM=MBP&MBPB,CLASS=0
¢ $$ LST,CLASS=Q
¢¢ JOB  MBP&MBP      MAGEC Batch Program Compile
¢¢ EXEC PROC=MAGECLIB
¢¢ OPTION CATAL
 ACTION CLEAR
PHASE MBP&MBPB,*
INCLUDE MAGDBMS
INCLUDE DATACOBT
¢¢ EXEC FCOBOL,SIZE=180K
 CBL OPT,APOST,ADV,LANGLVL(1),SXREF,CLIST,SUPMAP,BUF=3520
-MAGECINC MOD&TYP
¢F
  ENTRY BEGINS            (use ENTRY BEGIN for Datacom/DB)
¢¢ EXEC BOMIFBAD          (remove this for VSE/SP)
¢¢ EXEC LNKEDT
¢F
¢J
¢ $$ EOJ
/*
/&
¢ $$ EOJ

Note: rrr = Report Number

z/OS

//MBPCREAT JOB CLASS=x,MSGCLASS=x     gen. compile, link MBP
//MMPCRE EXEC  PGM=MBPCRE,REGION=1024K
//STEPLIB  DD  DSN=MAGEC.LOADLIB,DISP=SHR
 * * * * * * * *   DD's for dictionary files
//SYS005   DD  DSN=&&OSJOB,DISP=(NEW,PASS),UNIT=SYSDA,
//         DCB=(RECFM=FB,LRECL=80,BLKSIZE=4000),SPACE=(CYL,5)
//SYS007   DD SYSOUT=*
//SYSOUT   DD SYSOUT=*
//SYSUDUMP DD SYSOUT=*
//SYSPRINT DD SYSOUT=*
//SYS006   DD *
MBPCRE   rrrB MAGEC     OS VSAM
-MAGECINC MOD&TYP
/*
//STEP2    EXEC PGM=IKFCBL00,REGION=512K
// PARM='BUF=256K,APOST,LIB,NODYNAM,OPT,RESIDENT,NOTRUNC'
//STEP
LIB  DD DSN=VS.COBOL.LINKLIB,DISP=SHR
//         DD DSN=VS.COBOL.COBLIB,DISP=SHR
//SYSLIB   DD DSN=SYS1.MACLIB,DISP=SHR
//         DD DSN=MAGEC.LOADLIB,DISP=SHR
//SYSUDUMP DD SYSOUT=*
//SYSPRINT DD SYSOUT=*
//SYSUT1   DD UNIT=SYSDA,SPACE=(460,(700,100))
//SYSUT2   DD UNIT=SYSDA,SPACE=(460,(700,100))
//SYSUT3   DD UNIT=SYSDA,SPACE=(460,(700,100))
//SYSUT4   DD UNIT=SYSDA,SPACE=(460,(700,100))
//SYSUT5   DD UNIT=SYSDA,SPACE=(460,(700,100))
//SYSUT6   DD UNIT=SYSDA,SPACE=(460,(700,100))
//SYSIN    DD DSN=&&OSJOB,DISP=(OLD,DELETE),UNIT=SYSDA,
//         DCB=(RECFM=FB,LRECL=80,BLKSIZE=4000,SPACE=(CYL,5)
//SYSLIN   DD DSN=&&LOADSET,DISP=(MOD,PASS),UNIT=SYSDA,
//            SPACE=(80,(500,100))
//LKED     PGM=IEWL,
// PARM='XREF,NCAL,LIST',COND=(8,LT),REGION=192K
/
/SYSLIB   DD DSN=VS.COBLIB,DISP=SHR
//         DD DSN=MAGEC.LOADLIB,DISP=SHR
//SYSLMOD  DD DSN=MAGEC.LOADLIB,DISP=SHR
//SYSUT1   DD UNIT=SYSDA,SPACE=(CYL,(2,1)
//SYSPRINT DD SYSOUT=*
//SYSLIN   DD DSN=*.COBOL.SYSLIN,DISP=(OLD,KEEP)
//         DD *
 INCLUDE SYSLMOD(MAGDBMS)
 INCLUDE SYSLMOD(DATACOBT)
ENTRY BEGIN
NAME MBPrrrB(R)

z/OS -- COBOLII

//U2MSI1CB JOB (SYST,MSI),MBPCREAT,CLASS=M,MSGCLASS=X,
//         MSGLEVEL=(1,1),NOTIFY=U2MSI2,REGION=4M
//MBPCREAT EXEC PGM=MBPCRE,REGION=4096K
//STEPLIB  DD   DSN=MAGEC.LOADLIB2,DISP=SHR
********** DD's for MAGEC Dictionary files
//SYS005    DD  DSN=&&OSJOB,DISP=(NEW,PASS),UNIT=WORK,
//          DCB=(RECFM=FB,LRECL=80,BLKSIZE=17600),
//          SPACE=(CYL,20)
//SYS007    DD  SYSOUT=*
//SYSOUT    DD  SYSOUT=*
//SYSUDUMP  DD  SYSOUT=*
//SYSPRINT  DD  SYSOUT=*
//SYS006    DD  *
MBPCRE   rrrB MAGEC     OS VSAM
-MAGECINC MOD&TYP
//COB2   EXEC  PGM=IGYCRCTL,REGION=2M,
//       PARM=(NONAME,'BUFSIZE(23440)',
//            NOFDUMP,NODYNAM,DMAP,NOSTATE,
//            SXREF,NODUMP,OPT,NOSUPPRESS,ADV,NOSSRANGE)
//STEPLIB  DD  DSN=SYS1.COB2COMP,DISP=SHR
//SYSPUNCH DD  DSN=&&DECK,DISP=(MOD,PASS),UNIT=HSMDA,
//         SPACE=(80,(500,100)),DCB=BLKSIZE=3200
//SYSLIB   DD  DSN=CICS.PROD.COPYLIB,DISP=SHR
//SYSUT1   DD  UNIT=WORK,SPACE=(CYL,(5,5))
//SYSUT2   DD  UNIT=WORK,SPACE=(CYL,(5,5))
//SYSUT3   DD  UNIT=WORK,SPACE=(CYL,(5,5))
//SYSUT4   DD  UNIT=WORK,SPACE=(CYL,(5,5))
//SYSUT5   DD  UNIT=WORK,SPACE=(CYL,(5,5))
//SYSUT6   DD  UNIT=WORK,SPACE=(CYL,(5,5))
//SYSUT7   DD  UNIT=WORK,SPACE=(CYL,(5,5))
//SYSLIN   DD  DSN=&&SYSLIN,DISP=(MOD,PASS),SPACE=(CYL,(5,1)),
//             UNIT=HSMDA
//SYSPRINT  DD  SYSOUT=*
//SYSIN    DD  DSN=&&OSJOB,DISP=(OLD,DELETE)
//LKED2  EXEC  PGM=IEWL,PARM='LIST,XREF,LET',REGION=512K //SYSLMOD  DD  DSN=MAGEC.LOADLIB2,DISP=SHR
//SYSLIB   DD  DSN=SYS1.COB2LIB,DISP=SHR,DCB=BLKSIZE=23476 //         DD  DSN=MAGEC.LOADLIB2,DISP=SHR
//         DD  DSN=SYS1.VENDOR.LINKLIB,DISP=SHR
//SYSUT1   DD  UNIT=WORK,SPACE=(CYL,(1,1))
//SYSPRINT DD  SYSOUT=*
//SYSLIN   DD  DSN=*.COB2.SYSLIN,DISP=(OLD,DELETE)
//         DD  *
   INCLUDE SYSLMOD(MAGECSET)
   INCLUDE SYSLMOD(DATACOBT)
   INCLUDE SYSLIB(IGZEBST)
   ENTRY BEGINS
   NAME MBPrrrB(R)
//*

PC

From within Windows or OS/2 you can execute MBPCREAT by selecting the icon from the MAGEC group or folder, a dialog box will prompt you for the MBP# plus debugger options (if desired).

At the prompt, enter:

MBPCREAT rrrB ANIMATE

where:
rrr = MBP number

ANIMATE = = optional literal parameter indicating that MBPCREAT is to generate and compile program for Micro Focus Animator

MAGECCOB & MAGECASM

Compile Program from Library

The MAGEC Library may be used for any type of program, online or batch. If you wish to store and maintain your batch COBOL or ASSEMBLER programs using the MAGEC Library and online maintenance facilities then you will want to be able to submit compiles and assemblies from the Library.

Using the MAGEC Library for all your programs lets you use the "copybook" include feature (-MAGECINC) to use the same data definitions and library routines for all your programs. This means the Dictionary-generated copybooks also can be included into non-MAGEC programs, if you wish (refer to the "Database Administration" chapter).

The MAGECCOB and MAGECASM jobstreams execute the MMPCRE program to extract the source code from the MAGEC library (ALG file) and to expand copybooks (-MAGECINC's). The "dummy" screen header (SHD) number of "681" is used in the control cards since MMPCRE requires a valid SHD number in order to execute.

To compile a COBOL program from the Library use the MAGECCOB jobstream.

Assemble Program from Library

To assemble your Assembler language programs from the Library use the MAGECASM jobstream.

The first step in each of these two jobstreams is MMPCRE which will extract your program from the Library and expand any -MAGECINC statements. If you would like more detail regarding the control cards into MMPCRE refer to MMPCREAT earlier in this chapter. MMPCRE is used also to generate MMP's.

Adding Program to Library

Remember, the MAGECLBR utility discussed earlier may be used to add your programs to the MAGEC Library.

MAGECCOB Jobstream

Compile and link batch program from MAGEC Library (ALG file).

VSE

* $$ JOB JNM=MAGECCOB,CLASS=F
* $$ PRT CLASS=V
* $$ PUN CLASS=F,DISP=I,PRI=9
// JOB MAGECCOB
// EXEC PROC=MAGECLIB   -pvt. libs & DLBL'S for dictionary
// ASSGN SYS006,SYSIPT
// ASSGN SYS007,SYSLST
// ASSGN SYS005,SYSPCH
// EXEC MMPCRE,SIZE=(AUTO,20K)
MMPCRE   681  CICS      MAGEC     DOSVSAM
¢ $$ JOB JNM=BATCH,CLASS=0
¢ $$ LST CLASS=Q
¢¢ JOB MAGECCOB
¢¢ EXEC PROC=MAGECLIB   -pvt. libs. (and DLBL'S if VSAM)
¢¢ OPTION CATAL
 PHASE --------,*
 INCLUDE DATACOB
¢¢ EXEC FCOBOL,SIZE=128K
 CBL BUF=3520,SUPMAP,CLIST,SXREF,OPT,LIB,APOST,LANGLVL(1),ADV
-MAGECINC --------            member name
¢F
¢¢ EXEC LNKEDT
¢J
¢ $$ EOJ
/*
/&
* $$ EOJ

Note: Refer to MMPCREAT in this chapter for control card layout.

z/OS

//COMPILE JOB CLASS=A,MSGCLASS=A
//STEP1  EXEC  PGM=MMPCRE,REGION=1024K
//STEPLIB  DD  DSN=MAGEC.LOADLIB.DISP=SHR
 * * * * * * * *   DD'S for dictionary files
//SYS005   DD  DSN=&&OSJOB,DISP=(NEW,PASS),UNIT=SYSDA
//        DCB=(RECFM=FB,LRECL=80,BLKSIZE=4000),SPACE=(CYL,5)
//SYS007   DD SYSOUT=*
//SYSOUT   DD SYSOUT=*
//SYSUDUMP DD SYSOUT=*
//SYSPRINT DD SYSOUT=*
//SYS006   DD *
MMPCRE   681 CICS     MAGEC    OS  VSAM
-MAGECINC XXXXXXXX                (XXXXXXX = member name)
/*
//COB    EXEC PGM=IKFCBL00,REGION=256K,
//    PARM='NODECK,LINKMAP,DCLIST,LOAD,RESIDENT,NODYNAM'
//STEPLIB  DD DSN=VS.COBOL.LINKLIB,DISP=SHR
//         DD DSN=VS.COBOL.COBLIB,DISP=SHR
//SYSLIB   DD DSN=SYS1.MACLIB,DISP=SHR
//         DD DSN=MAGEC.LOADLIB,DISP=SHR
//SYSUDUMP DD SYSOUT=*
//SYSPRINT DD  SYSOUT=*
//SYSUT1   DD  UNIT=SYSDA,SPACE=(CYL,(2,1))
//SYSUT2   DD  UNIT=SYSDA,SPACE=(CYL,(2,1))
//SYSUT3   DD  UNIT=SYSDA,SPACE=(CYL,(2,1))
//SYSUT4   DD  UNIT=SYSDA,SPACE=(CYL,(2,1))
//SYSLIB   DD  DSN=SYS1.MACLIB,DISP=SHR
//         DD  DSN=MAGEC.LOADLIB,DISP=SHR
//SYSLIN   DD  UNIT=SYSDA,SPACE=(TRK,(30,10)),DISP=(,PASS)
//SYSIN    DD  DSN=&&OSJOB,DISP=(OLD,DELET),UNIT=SYSDA,
//             DCB=(RECFM=FB,LRECL=80,BLKSIZE=4000,
//             SPACE=(CYL,5)
//LKED     EXEC PGM=IEWL,PARM=(XREF,LET,LIST),COND=(8,LE)
//SYSLIB   DD  DSN=VS.COBLIB,DISP=SHR
//         DD  DSN=MAGEC.LOADLIB,DISP=SHR
//SYSLMOD  DD  DSN=MAGEC.LOADLIB,DISP=SHR
//SYSPRINT DD  SYSOUT=*
//SYSUT1  DD  UNIT=SYSDA,SPACE=(CYL,(2,1))
//SYSLIN  DD  DSN=*.COBOL.SYSLIN,DISP=(OLD,DELETE)
//        DD  *
 INCLUDE SYSLMOD(DATACOB)
 NAME XXXXXXXX(R)
/*
//

z/OS -- COBOLII

//U2MSI1CB JOB (SYST,MSI),MAGCOB85,CLASS=M,MSGCLASS=X,
//         MSGLEVEL=(1,1),NOTIFY=U2MSI2,REGION=4M
//MAGECCOB EXEC PGM=MMPCRE,REGION=4096K
//STEPLIB  DD   DSN=MAGEC.LOADLIB2,DISP=SHR
************ DD's for MAGEC Dictionary files
//SYS005    DD  DSN=&&OSJOB,DISP=(NEW,PASS),UNIT=WORK,
//          DCB=(RECFM=FB,LRECL=80,BLKSIZE=17600),
//          SPACE=(CYL,20)
//SYS007    DD  SYSOUT=*
//SYSOUT    DD  SYSOUT=*
//SYSUDUMP  DD  SYSOUT=*
//SYSPRINT  DD  SYSOUT=*
//SYS006    DD  *
MMPCRE   681  CICS       MAGEC    OS VSAM
-MAGECINC XXXXXXXX
//COB2   EXEC  PGM=IGYCRCTL,REGION=2M,
//       PARM=(NONAME,'BUFSIZE(23440)',
//          NOFDUMP,NODYNAM,DMAP,NOSTATE,
//          SXREF,CLIST,OPT,NOSUPPRESS,ADV,NOSSRANGE)
//STEPLIB  DD  DSN=SYS1.COB2COMP,DISP=SHR
//SYSPUNCH DD  DSN=&&DECK,DISP=(MOD,PASS),UNIT=HSMDA,
//         SPACE=(80,(500,100)),DCB=BLKSIZE=3200
//SYSLIB   DD  DSN=CICS.PROD.COPYLIB,DISP=SHR
//SYSUT1   DD  UNIT=WORK,SPACE=(CYL,(5,5))
//SYSUT2   DD  UNIT=WORK,SPACE=(CYL,(5,5))
//SYSUT3   DD  UNIT=WORK,SPACE=(CYL,(5,5))
//SYSUT4   DD  UNIT=WORK,SPACE=(CYL,(5,5))
//SYSUT5   DD  UNIT=WORK,SPACE=(CYL,(5,5))
//SYSUT6   DD  UNIT=WORK,SPACE=(CYL,(5,5))
//SYSUT7   DD  UNIT=WORK,SPACE=(CYL,(5,5))
//SYSLIN   DD  DSN=&&SYSLIN,DISP=(MOD,PASS),SPACE=(CYL,(5,1)),
//             UNIT=HSMDA
//SYSPRINT  DD  SYSOUT=*
//SYSIN    DD  DSN=&&OSJOB,DISP=(OLD,DELETE)
//LKED2  EXEC  PGM=IEWL,PARM='LIST,XREF,LET,TERM',REGION=512K
//SYSLMOD  DD  DSN=MAGEC.LOADLIB2,DISP=SHR
//SYSLIB   DD  DSN=SYS1.COB2LIB,DISP=SHR,DCB=BLKSIZE=23476
//         DD  DSN=MAGEC.LOADLIB2,DISP=SHR
//         DD  DSN=SYS1.VENDOR.LINKLIB,DISP=SHR
//SYSUT1   DD  UNIT=WORK,SPACE=(CYL,(1,1))
//SYSPRINT DD  SYSOUT=*
//SYSLIN   DD  DSN=*.COB2.SYSLIN,DISP=(OLD,DELETE)
//         DD  *

   INCLUDE SYSLMOD(MAGECSET)
   INCLUDE SYSLMOD(DATACOB)
   INCLUDE SYSLIB(IGZEBST)
   NAME XXXXXXXX(R)
//*

PC

At the prompt, enter:

MAGECCOB xxxxxxxx

where: xxxxxxxx = the member name to be compiled

MAGECASM Jobstream

Assemble and CATALR. See MMPCREAT in this chapter for control card layout.

VSE

* $$ JOB JNM=MAGECASM,CLASS=F
* $$ PRT CLASS=V
* $$ PUN CLASS=F,DISP=I,PRI=9
// JOB MAGECASM
// EXEC PROC=MAGECLIB   -pvt. libs & dictionary file DLBL's
// ASSGN SYS006,SYSIPT
// ASSGN SYS007,SYSLST
// ASSGN SYS005,SYSPCH
// EXEC MMPCRE,SIZE=(AUTO,20K)
MMPCRE   681  CICS      MAGEC     DOSVSAM
¢ $$ JOB JNM=MAGECASM,CLASS=F
¢ $$ PRT CLASS=V
¢¢ JOB MAGECASM
¢¢ EXEC PROC=MAGECLIB   -pvt. libs & DLBL's for dictionary
 ASSGN SYSPCH,....       i.e:  ,DISK,VOL=SYSRES,SHR
¢¢ OPTION DECK
¢¢ EXEC ASSEMBLY,SIZE=128K
-MAGECINC xxxxxxxx         member name
¢F
 CLOSE SYSPCH,PUNCH
ASSGN SYSIPT,.......      example:  ASSGN SYSIPT,SYSRES
¢¢ EXEC MAINT
¢F
¢J
¢¢ JOB CLOSE
CLOSE SYSIPT,READER
¢F
¢J
¢ $$ EOJ
/*
/&
* $$ EOJ

z/OS

//MAGECASM JOB CLASS=A,MSGCLASS=W
//STEP1  EXEC  PGM=MMPCRE,REGION=1024K
//STEPLIB  DD DSN=MAGEC.LOADLIB,DISP=SHR
* * * * * * * *   DD'a for VSAM files (if VSAM)
//SYS005   DD DSN=&&OSJOB,DISP=(NEW,PASS),UNIT=SYSDA
//        DCB=(RECFM=FB,LRECL=80,BLKSIZE=4000),SPACE=(CYL,5)
//SYS007   DD SYSOUT=*
//SYSOUT   DD SYSOUT=*
//SYSUDUMP DD SYSOUT=*
//SYSPRINT DD SYSOUT=*
//SYS006   DD *
MMPCRE   681 CICS      MAGEC     OS VSAM
-MAGECINC XXXXXXXX                   member name
/*
//STEP2  EXEC PGM=IFOX00
//STEPLIB DD DSN=MAGEC.LOADLIB,DISP=SHR
//SYSLIB  DD DSN=CICS.MACLIB,DISP=SHR
//         DD DSN=CICS.SOURCE,DISP=SHR
//         DD DSN=MAGEC.LOADLIB,DISP=SHR
//SYSUT1   DD UNIT=SYSDA,SPACE=(1700,(400,50))
//SYSUT2   DD UNIT=SYSDA,SPACE=(1700,(400,50))
//SYSUT3   DD UNIT=SYSDA,SPACE=(1700,(400,50))
//SYSPRINT DD SYSOUT=*
//SYSGO    DD DUMMY
//SYSPUNCH DD DSN=&SYSGO,DISP=(MOD,PASS),UNIT=SYSDA,
//            SPACE=(80,(200,100))
//SYSIN    DD DSN=&&OSJOB,DISP=(OLD,DELETE),UNIT=SYSDA,
//        DCB=(RECFM=FB,LRECL=80,BLKSIZE=4000),SPACE=(CYL,5)
/*
//LKED     EXEC PGM=IEWL,PARM=(NCAL),COND=(8,LT)
//SYSLIB   DD DSN=MAGEC.LOADLIB,DISP=SHR
//SYSLIN   DD DSN=&SYSGO,DISP=(OLD,DELETE)
//SYSUT1   DD UNIT=SYSDA,SPACE=(1024,(50,20))
//SYSPRINT DD SYSOUT=*
//SYSLMOD  DD DSN=MAGEC.LOADLIB(XXXXXXXX),DISP=SHR
/*
//

MSKCREAT

Generate a Mask

The MSKCREAT jobstream is used to generate a mask so that it may be used by an MMP. The specifications and screen format are obtained from the MAGEC Dictionary where they are stored as the developer "draws" the mask (online function code MSKDEF) and enters editing criteria for the screen fields.

Note: The online function MSKCRE accomplishes the same thing as the offline MSKCREAT jobstream. The offline jobstream is provided for administrative purposes to enable scheduling MSKCREAT's to be executed at night for lists of mask numbers.

The output from the MSKCREAT jobstream is:

MSK file record

A mask initialization record used at execution time to format a screen.

Cobol definition

A "copybook" catalogued to the MAGEC ALG file to be -MAGECINC'd by an MMP.

Listing

A listing showing screen field specs and errors (if any).

SHD file record

The SHD record is updated to show the date and time the mask was generated.

The jobstream consists of one step:

MSKCRE

Extract data and sort it, generate the mask and "copybook".

MSKCRE Control Cards

A control card is accepted into the first step to indicate which mask is to be generated and what kind of Library. The format of the control card is:

Columns Description

1 - 9

Constant 'MSKCREAT'.

10 - 12

Mask (SHD) Number.

Control card example:

MSKCREAT nnn

MSKCREAT Jobstream

VSE

* $$ JOB JNM=MSKCREAT,CLASS=F
* $$ PRT CLASS=V
// JOB MSKCREAT  Generate MAGEC Mask
// EXEC PROC=MAGECLIB   -pvt. libs & DLBL's for dictionary
// ASSGN SYS007,SYSLST
// ASSGN SYS006,SYSIPT
// DLBL SORTWK01,'SORTED.WORK.FILE',0,SD
// EXTENT SYS001,volid,1,0,548000,4000
// ASSGN SYS001,DISK,VOL=xxxxxx,SHR
// EXEC MSKCRE,SIZE=(AUTO,20K)
MSKCREAT ...
/*
/&
* $$ EOJ

z/OS

//MSKCREAT JOB CLASS=A,MSGCLASS=...
//STEP1  EXEC  PGM=MSKCRE,REGION=1M
//STEPLIB  DD  DSN=MAGEC.LOADLIB.DISP=SHR
* * * * * * * *   DD's for dictionary files
//SORTWK01 DD  UNIT=SYSDA,SPACE=(CYL,(1,1))
//SORTWK02 DD  UNIT=SYSDA,SPACE=(CYL,(1,1))
//SORTWK03 DD  UNIT=SYSDA,SPACE=(CYL,(1,1))
//SYSOUT   DD  SYSOUT=*
//SYS007   DD  SYSOUT=*
//SYS006   DD  *
MSKCREAT ...
/*
//

PC

At the prompt, enter: (xxx = Mask number)

MSKCREAT xxx

MSKDOC

Print Mask & Documentation

The MSKDOC batch utility program may be used to print a hardcopy image of the mask from the MAGEC Dictionary files and associated technical documentation. The mask need not have been created yet (via the MSKCREAT process) since the Screen format and all specifications are taken from the Dictionary entries produced as the developer enters the specifications and "draws" the mask (via MSKDEF).

The program accepts a control card which specifies which mask is to be printed. Multiple control cards may be input to any one run. MSKDOC produces complete documentation for your online application, including screen format, attribute controls, customization, business rules, and security requirements. The report is neatly formatted. If you prefer some other report format for your hardcopy documentation MAGEC Software will make the source code (Cobol) for MSKDOC available to you so that you can create your own documentation printing program.

MSKDOC Control Cards

Columns

Description

1 - 7

Constant 'MSKDOC '.

8 - 10

Mask (SHD) Number.

12 - 80

Blank.

Control card example:

MSKDOC 001

MSKDOC Jobstream

VSE

* $$ JOB JNM=MSKDOC,CLASS=_
* $$ PRT CLASS=V
// JOB MSKDOC
// EXEC PROC=MAGECLIB   -pvt. libs. and dictionary DLBL's
// ASSGN SYS006,SYSIPT
// ASSGN SYS007,SYSLST
// EXEC MSKDOC,SIZE=(AUTO,20K)
MSKDOC mmm
/*
/&
* $$ EOJ

z/OS

//MSKDOC   JOB  CLASS=_,MSGCLASS=_
//STEP1   EXEC PGM=MSKDOC
//STEPLIB  DD  DSN=MAGEC.LOADLIB,DISP=SHR
* * * * * * * *   DD's for dictionary files
//SYSOUT   DD  SYSOUT=W
//SYS007   DD  SYSOUT=W
//SYS006   DD  *
MSKDOC mmm
/*
//

PC

Edit, as necessary, the control cards found in the local disk drive (LCLDRV) in the file named:

\MAGMF\MSKDOC.RDR

At the prompt enter:

MSKDOCEX

MSKPRT

Print a Mask Image

The batch utility program MSKPRT may be used to print an image of any mask on the MAGEC MSK file. The mask must have been created (via MSKCREAT) in order for it to have a record on the MSK file. To print an image of a mask (plus technical documentation for it) whether or not it has been created via MSKCREAT, the utility program MSKDOC may be used.

Whereas MSKDOC produces an image as it appears to the developer on the online MSKDEF screen, MSKPRT produces an image as it appears to the application user.

MSKPRT accepts a control card to specify which mask it is to print. Multiple control cards may be input to one run. The control card format is as shown below:

MSKPRT Control Cards

Columns

Description

Card Format:

1 - 7

Constant 'MSKPRT '.

8 - 10

Mask (SHD) Number.

12 - 80

Blank.

Control card example:

MSKPRT 001

MSKPRT Jobstream

VSE

* $$ JOB JNM=MSKPRT,CLASS=F
* $$ PRT CLASS=V
// JOB MSKPRT
// EXEC PROC=MAGECLIB   -pvt. libs & DLBL's for dictionary
// ASSGN SYS006,SYSIPT
// ASSGN SYS007,SYSLST
// EXEC MSKPRT,SIZE=(AUTO,20K)
MSKPRT mmm
/*
/&
* $$ EOJ

z/OS

//MSKPRT   JOB  CLASS=_,MSGCLASS=_
//STEP1    EXEC PGM=MSKPRT
//STEPLIB  DD  DSN=MAGEC.LOADLIB,DISP=SHR
* * * * * * * *   DD's for dictionary files
//SYSOUT   DD  SYSOUT=W
//SYS007   DD  SYSOUT=W
//SYS006   DD  *
MSKPRT mmm
/*
//

PC

Edit, as necessary, the control cards found in your local drive (LCLDRV) in the file named:

\MAGMF\MSKPRT.RDR

At the prompt, enter:

MSKPRTEX

TBLLIST

List MAGEC Lookup Tables

The batch utility program TBLLIST may be used to produce a hardcopy listing of any MAGEC Lookup Table(s) from the MAGEC TBL file. It accepts a control card to indicate which Table(s) are to be listed. More than one control card may be input to any one run.

TBLLIST Control Cards

Columns

Description

Card Format:

1 - 8

Constant 'TBLLIST '.

9 - 11

Starting Table Number. (must be numeric)

12

Constant ' - ' or blank.

13 - 15

Ending Table Number. (must be numeric or blank)

Control card example:

TBLLIST 001-999

TBLLIST Jobstream

VSE

* $$ JOB JNM=TBLLIST,CLASS=F
* $$ PRT CLASS=V
// JOB TBLLIST
// EXEC PROC=MAGECLIB       pvt libs & DLBLs for dictionary
// ASSGN SYS006,SYSIPT
// ASSGN SYS007,SYSLST
// EXEC TBLLIST,SIZE=(AUTO,20K)
TBLLIST xxx-yyy
/*
/&
* $$ EOJ

z/OS

//TBLLIST   JOB  CLASS=_,MSGCLASS=_
//STEP1    EXEC PGM=TBLLIST
//STEPLIB  DD  DSN=MAGEC.LOADLIB,DISP=SHR
* * * * * * * *   DD's for dictionary files
//SYSOUT   DD  SYSOUT=W
//SYS007   DD  SYSOUT=W
//SYS006   DD  *
TBLLIST xxx-yyy
/*
//

PC

Edit, as necessary, the control cards found in the file named:

\MAGMF\TBLLIST.RDR

At the prompt, enter:

TBLLISTX

APUNLOAD

Unload an Application

The APUNLOAD jobstream is used to unload a complete MAGEC application for transporting or transmitting to another MAGEC system whether on the same CPU or on another. It is not necessary for the two systems to be operating in the same environment as one another. You may copy an application developed and running on a DOS/VSE WESTI MAGEC system to an z/OS CICS system, for instance. Unless you have seriously violated the recommended standards for developing applications there should be no coding changes required, just a "re-compile" on the target system.

To copy an application from one system to another you must do three steps:

APUNLOAD Unload it from the source system.
APLOAD Load it onto the target system.
MMPCREAT Regenerate and compile on target system.

When you unload an application from the source system it is not removed from that system. Unloading is simply a process of reducing all the pertinent Dictionary data, including Customization Algorithms, Data Definitions, and Documentation, into 80-column card images which may be transmitted via RJE or passed from one system to another via a disk file or queue file or "link" in order to enable loading onto the other system. The same application will then operate on both systems. Transferring applications from ASCII to EBCDIC and vica-versa are supported since any "packed", binary, or hexadecimal fields are automatically decoded for transfer. It is also possible to rename an application as it is being loaded to the target system.

Portability

In order to ensure the "Portability" of your applications you must avoid using any techniques in your Customization which will not work the same way on any potential target system. For instance, if you are developing applications on a MAGEC CICS system which are to be used also on a MAGEC WESTI system, then you must not use CICS-only commands in your Customization (ie: SERVICE RELOAD, EXEC CICS, etc.) since they will not work the same way under WESTI. MAGEC provides "service routines" in the generated MMP's to handle all necessary commands; your Customization coding should PERFORM those built-in routines so that MAGEC can resolve the differences between environments.

The APUNLOAD jobstream consists of one step:

APUNLOAD

Unload an application definition or other dictionary data.

Verifying Output

A tabular statistical report is produced which indicates what types of dictionary data (and how many records of each) were unloaded. This report can be matched to a similar report produced by the APLOAD program when the data is loaded to the target system.

Control Cards

There are nine possible control cards accepted into the APUNLOAD utility program. They are:

Card 1
APLOAD control card - APUNLOAD simply passes this card on to the output stream where it will be found by APLOAD at the target system.

Card 2
APUNLOAD control card - indicates the MSK # (application identity) to be unloaded and also allows you to skip the unloading of some of the Dictionary files, if desired. A value of "NULL" may be used here when you wish to unload dictionary data (i.e. library members, default code, error messages, lookup tables, data definitions, domains, etc.) without unloading any particular application

Card 3
ERR number card - indicates a range of MAGEC ERR file records which are to be unloaded with the application. There may be more than one of these cards.

Card 4
TBL number card - indicates a range of MAGEC TBL file records to be unloaded along with the application. There may be more than one of these cards.

Card 5
Library Member card - indicates the name of a library member (usually a copybook) to be unloaded along with the application.

Card 6
Default Code card - indicates that a Default Algorithm is to be unloaded along with the rest of the Dictionary data.

Card 7
Data Definition card - indicates a Data Class whose entire definition is to be unloaded

Card 8
Domain card - indicates a Domain or range of Domains to be unloaded

Card 9
RENAME card - if present this card must immediately precede the APLOAD card (card 1). It enables you to unload an application and to have it reloaded under a different application name (MMP number or MBP number).

Control card 1 and 2 must be the first two cards into APUNLOAD. They are both required cards. The other cards are optional, they enable you to copy over your "copybooks" or Library routines from the source system and to copy over any ERR or TBL file entries which are needed for the application being unloaded. You can unload multiple applications in a single run of APUNLOAD by using multiple control cards 1 and 2. If you omit card 1 and only input card 2, APUNLOAD will automatically generate a card 1 for you.

The copybooks for the Elements accessed by your application (both from the primary Data Class, and from joined Data Classes) will automatically be copied for you, you need not code a control card to unload them. The DIT definitions for them will be unloaded, as well.

The APLOAD control card is not actually used by the APUNLOAD program, it is simply placed into the output stream so that APLOAD will be able to identify which application is to be loaded. It serves as one of the many "cross-checks" built into the APUNLOAD/APLOAD process to ensure that data is copied accurately from the source to the target system. That is very important when RJE communications are involved but it is also important even when transferring an application between two systems running on the same CPU.

In order to accommodate transferring from EBCDIC to ASCII (as in IBM mainframe to PC) and vice-versa, the APUNLOAD program will expand all binary and packed numeric data to zoned-decimal; the APLOAD program will convert it back. This is because the character conversion algorithms in most "link" packages would corrupt binary or packed data in the translation.

Pseudo JCL into APUNLOAD

In the DOS environment it is sometimes useful to have APUNLOAD put its output onto the POWER punch queue with a disposition=I so that it is immediately "turned around" as an input "reader queue" stream. To support that, APUNLOAD will accept pseudo JCL in its input stream and will convert it into real JCL and pass it through to the output stream. If disposition=I is specified on the POWER punch control card then the punched output will immediately execute. The punched output would be an APLOAD execution to load the unloaded application. You might use the job class or a different PROC defining the Dictionary files and system libraries to direct the APLOAD to load onto one system or another.

When APUNLOAD encounters pseudo JCL in its input stream it does the following transformations:

An example of how to use APUNLOAD's pseudo JCL to produce an output punch queue file which is "turned around" as an input reader queue file to immediately load the unloaded application is provided in this book under the name APCOPY. Refer to the example jobstreams in the APLOAD section which follows.

Unloading Dictionary Data

Sometimes it might be necessary to move dictionary data from one system to another without moving any particular application. This might involve moving lookup tables, error messages, library members, default algorithms, data definitions, or domains. All of these can be moved using APUNLOAD control cards either with or without also moving an application. If it is not desired that any particular application be moved along with such dictionary data, a specification of "NULL" in Control Card 1 (columns 10 - 13) will inform APUNLOAD that no application is to be moved along with the other data.

It should be noted that some of these types of data (library members, customization, default code, etc.) can be moved using the MAGECLBR utility also. The APUNLOAD/APLOAD process is somewhat more complete and thorough than MAGECLBR is in that they will move the library members' owner identification and password control along with the member, whereas MAGECLBR will not.

APUNLOAD Control Card Formats

Columns

Description

Card 1 Format:

1 - 9

Constant 'APLOAD '.

10 - 13

Mask # (SHD #) -or- MBP # -or- NULL.

14 - 18

Blank or 'NOREP'.

19

Blank.

20-80

Up to 12 Data Class names separated by commas ( , ).

Card 2 Format:

1 - 9

'APUNLOAD '.

10 - 13

MSK # (SHD #) -or- MBP #.

14

Blank.

15 - 18

Blank or 'SKIP'.

19

Blank.

20 - 80

Up to 12 Data Class names of Dictionary files separated by commas ( , ). Valid entries: MSK, KYF, FCD, REF, DOC, DCL, ELT, ALG, SCF, and MMP, in any order.

Card 3 Format:

1 - 9

'APUNLOAD '.

10 - 13

'ERR'.

14

Blank.

15 - 17

Starting ERR #.

18

Blank or slash ( / ).

19 - 21

Ending ERR #.

Card 4 Format:

1 - 9

'APUNLOAD '.

10 - 13

'TBL'.

14

Blank.

15 - 17

Starting TBL #.

18

Blank or slash ( / ).

19-21

Ending TBL #.

Card 5 Format:

1 - 9

'APUNLOAD '.

10 - 12

'LIB'.

13 - 14

Blank.

15 - 22

Member Name.

23

Blank or slash ( / ).

24 - 31

Modifier.

Card 6 Format:

1 - 9

'APUNLOAD '.

10 - 12

'DEF'.

13 - 14

Blank.

15 - 22

Parm Name.

23

Blank or slash ( / ).

24 - 31

'DEFAULT'.

Card 7 Format:

1 - 9

'APUNLOAD '.

10 - 12

'DCL'.

13 - 14

Blank.

15 - 17

Data Class name

Card 8 Format:

1 - 9

'APUNLOAD '.

10 - 12

'DOM'.

13 - 14

Blank.

15 - 20

Beginning Domain number

21

Dash (-)

22 - 27

Ending Domain number

Card 9 Format:

1 - 9

'RENAME '.

10 - 13

Old application number.

14

Blank, dash, or slash.

15 - 18

New application number

APUNLOAD Jobstream

VSE

* $$ JOB JNM=APUNLOAD,CLASS=F
* $$ LST CLASS=V
* $$ PUN CLASS=P
// JOB APUNLOAD       UNLOAD A MAGEC APPLICATION
// EXEC PROC=MAGECLIB  -pvt. libs. and

// ASSGN SYS006,SYSIPT       input control cards
// ASSGN SYS005,........     unloaded data here
// ASSGN SYS007,SYSLST       error report
// EXEC APUNLOAD,SIZE=(AUTO,20K)
RENAME   mmm /nnn 
APLOAD   mmm              mmm=Mask Number
APUNLOAD mmm  SKIP MSK,KYF,FCD,REF,DOC,DCL,ELT,ALG,SCF,MMP
APUNLOAD ERR  bbb/eee      bbb=beg. ERR#  -  eee=end.ERR#
APUNLOAD TBL  bbb/eee      bbb=beg. TBL#  -  eee=end. TBL#
APUNLOAD LIB  mmmmmmmm/xxxxxxxx       Member Name/Modifier
APUNLOAD DEF  pppppppp/DEFAULT    Parm Name/'DEFAULT'
APUNLOAD DCL  xxx                   Data Class ID
APUNLOAD DOM  bbbbbb-eeeeee      Beg. Domain# - End. Domain#

/*
/&
* $$ EOJ

z/OS

//APUNLOAD JOB (ACCT)      UNLOAD A MAGEC APPLICATION
//STEP1  EXEC PGM=APUNLOAD
//STEPLIB DD DSN=MAGEC.LOADLIB,DISP=SHR
* * * * * *  DD's for dictionary files
//SYS005     DD  DSN=....    unloaded data will go here
//SYS007     DD  SYSout=*    error report
//SYS006     DD  *           input control cards
RENAME   mmm /nnn 
APLOAD   mmm              mmm=Mask Number
APUNLOAD mmm  SKIP MSK,KYF,FCD,REF,DOC,DCL,ELT,ALG,SCF,MMP
APUNLOAD ERR  bbb/eee    bbb=beg. ERR# -  eee=end. ERR#
APUNLOAD TBL  bbb/eee     bbb=beg.TBL#- eee=end. TBL#
APUNLOAD LIB  mmmmmmmm/xxxxxxxx   Member Name/Modifier
APUNLOAD DEF  pppppppp/DEFAULT   Parm Name/'DEFAULT'
APUNLOAD DCL  xxx                   Data Class ID
APUNLOAD DOM  bbbbbb-eeeeee      Beg. Dom# -End.Dom#
//

PC

Edit, as necessary, the control cards found in the file named:

\MAGxx\APUNDLEX.RDR

At the prompt, enter:

APUNLDEX

The output goes to a file named:

\MAGxx\APUNLOAD.PUN

Note: Certain entities from the MAGEC Repository which pertain to data definitions are considered to be related and treated as a set when they are processed by APUNLOAD. If you do: APUNLOAD DCL, the DCL will be unloaded along with its subordinate KYF's (Key File definitions), ELT's (Element definitions), and each Element's subordinate Business Rules, DIT's (Data Item definitions), and Cobol copybook. If you do: SKIP DIT, APUNLOAD will assume that you intended to SKIP ELT, as well. If you do: SKIP ELT, APUNLOAD will also skip pulling the DIT's, Business Rules, and Cobol copybook for each ELT skipped.

Figure 01 — Entity Relationships

Figure 02 — Sample Diagram
Diagram developed using MAGEC's DataDiagram tool, shown as Figure 28 in Chapter 54
Data Definition Tutorial

APLOAD

Load an Application

The APLOAD jobstream is used to load a complete MAGEC application, or multiple applications, or other dictionary data unloaded via APUNLOAD to the system. The input is an unloaded application's Dictionary data from the APUNLOAD jobstream. The input data is in 80-column text file format with numerous cross-checks built in to detect missing or out of order cards. The first data card must be the APLOAD control card described below if an application's definition is being loaded; if only dictionary data definitions are being loaded without any application definition, use the 'NULL' value in the APLOAD control card (columns 10-13). In either case, the APLOAD control card cannot be omitted. If the application being loaded is to be renamed, then the RENAME card must immediately precede the APLOAD control card. APLOAD will check that the data being loaded is for the proper application by comparing it against the MSK # on the APLOAD control card.

APLOAD will re-construct the Dictionary file records from the input file data and will add (or update) them on the target system's files. If a record is already on file having the same key value as the one(s) being loaded then APLOAD will update it, if none is already on file APLOAD will add it.

A control card option on the APLOAD control card may be specified to tell APLOAD that it is not to update any matching records on the target system, just add the new ones. This option is handy in the case of, let us say, the ERR file where you might have unloaded a range of error numbers because the ones you want are scattered throughout that range. You can tell APLOAD to add the new ERR records but to just bypass those which are already on the file by using the 'NOREP' (no-replace) option. 'NOREP' tells APLOAD to not replace records currently on file, but to add those that are not already present.

The APLOAD jobstream has one step:

APLOAD

Load application to Dictionary.

You should also read the discussions about the APARC and APUNARC jobstreams which enable you to easily archive multiple versions of an application and to restore from any selected archived version on demand.

APLOAD Control Cards

There are two control cards accepted into the APLOAD program. The "APLOAD" card usually is passed from APUNLOAD in front of the unloaded data for each application (multiple applications can be loaded in a single run of APLOAD). If no application was unloaded (i.e. only error messages or data definitions were unloaded), there will be 'NULL' in columns 10-13.

Columns

Description

1 - 9

Constant 'APLOAD '.

10 - 13

Mask (SHD) number -or- MBP number -or- 'NULL'

14 - 18

Blank or 'NOREP'.

19

Blank.

20 - 80

Up to 12 Data Class names of Dictionary files separated by commas ( , ).

If you code 'NOREP' in column 14 of the APLOAD control card then you may list up to 12 names of Data Classes (files) which are not to have their records updated if a record being loaded is a match. NOREP means NO REPLACE, ADD ONLY.

The list of valid data class names which may be on the APLOAD control card after the NOREP parameter is:

ALG  (LIB will allow replacing Custom Algorithms, but not included Lib. members)
DCL
DIT
DOC
ELT
ERR
FCD
KYF
MMP
MSK
PRM
PRO
REF
RUL
SCF
SHD
TBL

RENAME Control Card

Another control card may be input to the APLOAD program. It is the RENAME card. As its name implies, it alllows you to rename an application. If used, it must immediately precede the APLOAD card. Its format is:

Columns

Description

1 - 9

Constant 'RENAME '.

10 - 13

Old Mask (SHD) NUMBER -or- MBP number.

14

Blank, dash, or slash separator.

15 - 18

New Mask (SHD) NUMBER -or- MBP number

This enables you to unload an application, say number 801, then to load it to another system under a different name, say 901. You could also reload it to the original source system under a different name to create a new test copy of your application.

APLOAD Jobstream

VSE

* $$ JOB JNM=APLOAD,CLASS=F
* $$ LST CLASS=V
// JOB  APLOAD       LOAD A MAGEC APPLICATION
// EXEC PROC=MAGECLIB   -pvt. libs. & DLBL's for dictionary
// ASSGN SYS006,........     unloaded appl. from APUNLOAD
// ASSGN SYS007,SYSLST       audit trail report
// EXEC APLOAD,SIZE=(AUTO,20K)
/*
/&
* $$ EOJ

z/OS

//APLOAD JOB (ACCT)       LOAD A MAGEC APPLICATION
//STEP1  EXEC PGM=APLOAD
//STEPLIB DD DSN=MAGEC.LOADLIB,DISP=SHR
* * * * * * *DD's for dictionary files
//SYS006     DD DSN=....     unloaded appl. from APUNLOAD
//SYS007     DD SYSOUT=*     audit trail report
//

PC

Edit, as necessary, the control cards found in the file named:

\MAGMF\APUNLOAD.PUN

At the prompt, enter:

APLOADEX

APCOPY Jobstream

VSE

* $$ JOB JNM=APCOPY,CLASS=S        <== runs on Source sys
* $$ PUN CLASS=T,DISP=I            <== route to Target sys
// JOB APUNLOAD       UNLOAD APPL. + GEN. JOB
// EXEC PROC=MAGECLIB       pvt libs & DLBL's for dictionary
// ASSGN SYS006,SYSIPT
// ASSGN SYS005,PUNCH
// ASSGN SYS007,SYSLST
// EXEC APUNLOAD,SIZE=(AUTO,20K)
¢ $$ JOB JNM=APCOPY,CLASS=T        <== runs on Target system
¢ $$ LST CLASS=A
¢¢ JOB  APLOAD       LOAD APPLICATION TO TARGET SYSTEM
¢¢ EXEC  PROC=MAGECLIB      pvt libs & DLBLS for dictionary
¢¢ ASSGN SYS006,SYSIPT
¢¢ ASSGN SYS007,SYSLST
¢¢ EXEC APLOAD,SIZE=(AUTO,20K)
APLOAD   mmm  mmm=MASK NUMBER
APUNLOAD mmm  SKIP MSK,KYF,FCD,REF,DOC,DCL,ELT,ALG,SCF,MMP
APUNLOAD ERR  bbb/eee    bbb = beg. ERR#  -  eee=end. ERR#
APUNLOAD TBL  bbb/eee    bbb = beg. TBL#  -  eee=end. TBL#
APUNLOAD LIB  mmmmmmmm/xxxxxxxx       Member Name/Modifier
APUNLOAD DEF  pppppppp/DEFAULT         Parm Name/'DEFAULT'
APUNLOAD DCL  xxx                   Data Class ID
APUNLOAD DOM  bbbbbb-eeeeee      Beg. Domain# - End. Domain#
¢F
¢J
¢ $$ EOJ
/*
/&
* $$ EOJ

z/OS

In an z/OS environment execute the APUNLOAD jobstream on the source system, followed by the APLOAD jobstream on the target system with APUNLOAD's SYS005 and APLOAD's SYS006 specifying the same DSN.

DCLDOC

Print Data Class Documentation

The DCLDOC utility program will print formatted, hardcopy documentation for a Data Class. The report includes all Keys, Elements, Data Items, and Where-Used references for Elements. The where-used reporting shows references as either the primary or joined data class for both online and batch applications. As the report is being produced the DCLDOC program searches for possible errors or inconsistencies in the definitions and flags them. At the end of the report a notice is produced telling on which pages such possible errors were flagged.

DCLDOC is a valuable aid for the Database Administrators and for Developers, particularly those doing "maintenance" to existing applications and data definitions.

DCLDOC Control Cards

There is only one control card into DCLDOC; however, you may submit multiples of the control card in one run.

Columns Description

1 - 7 constant "DCLDOC"

8 - 10 3-character Data Class

11 blank

12 uppercase flag

The Data Class name must be a valid one defined to MAGEC. A value of "U" or "Y" in the uppercase flag will cause all printed output to have all lowercase alphabetics converted to uppercase. This is helpful in mainframe environments where the print train does not contain the lowercase alphabetics.

In the PC MAGEC environment you should be aware that the control card file (DCLDOC.RDR) is in the \MAGMF directory and the .BAT file (DCLDOCEX.BAT) is in the \MAGMF\JCL directory.

DCLDOC Jobstream

VSE

* $$ JOB JNM=DCLDOC,CLASS=___

* $$ PRT CLASS=V

// JOB DCLDOC

// EXEC PROC=MAGECLIB    -pvt. libs. & dictionary DLBL's

// ASSGN SYS006,SYSIPT

// ASSGN SYS007,SYSLST

// EXEC DCLDOC,SIZE=(AUTO,20K)

DCLDOC xxx

/*

/&

* $$ EOJ

z/OS

//DCLDOC  JOB  CLASS=__,MSGCLASS=___, -etc-

//STEP1     EXEC PGM=DCLDOC

//STEPLIB  DD   DSN=MAGEC.LOADLIB,DISP=SHR

* * * * * DD's for MAGEC dictionary files

//SYSOUT   DD   SYSOUT=__

//SYS007   DD   SYSOUT=__

//SYS006   DD   *

DCLDOC xxx

/*

//

PC

Edit, as necessary, the control card(s) in the file:

\MAGMF\DCLDOC.RDR

At the prompt, enter:

DCLDOCEX

MBPEXEC

Executing a Generated MBP

The jobstream used to execute a batch program generated by MAGEC (MAGEC Batch Program [MBP]) will vary slightly from one program to another; however, it will usually be very similar to the example given in this chapter. The only differences from one program to another should be the addition of DD (or DLBL) statements for your data files accessed.

When MAGEC was originally installed on your computer the jobstream to execute MBP600B was also installed, that is the sample program created by doing the "Batch Developer" Tutorial project. You can likely produce any needed execute jobstreams thereafter by "cloning" that sample and modifying as needed (by adding DD or DLBL statements, usually).

On a PC the jobstream is in the \MAGMF\JCL directory and it is named: EXEC.BAT. The EXEC jobstream is coded so that it will execute any MBP. It accepts a parameter containing the full name of the program to be executed. This is possible because there are no DD or DLBL statements necessary in the PC MAGEC environment, and because the MS-DOS "batch file" support includes parameter substitution capabilities. There are no DD or DLBL statements needed because MAGEC's I/O module dynamically builds the necessary filespec's from the data in the dictionary about each file accessed.

You should keep in mind that the required mainframe region/partition size will vary with the number of data files you are accessing. In the PC environment you have a finite amount of memory which will limit the number of files which can be open at any given time. This limit is normally high enough for most needs (approximately 20 files), but may impose difficulties for very large programs accessing very many files with large block sizes.

The PC MAGEC jobstream (EXEC.BAT) directs the output print to a disk file, rather than to the printer. This enables you to review the output on your video screen before printing it and to print it multiple times, if desired. It also allows the program to execute faster and allows you to restart printing in the event of a paper jam at your printer.

The output print file (on disk) will be in the \MAGMF directory and will be named xxxxxxx.OUT (where xxxxxxx is the program name). You can print the file using the PRINT command, as:

PRINT \MAGMF\xxxxxxx.OUT

or, using the COPY command, as:

COPY \MAGMF\xxxxxxx.OUT LPT1 (or LPT2, etc.)

Also, you can review or edit the print file using any available text editor or word processor. It is a standard text file. The only unusual character you might see in it is the Form-Feed character (Hex '12') which usually displays as the "female" symbol the small circle with a small plus-sign below it.

MBPEXEC Jobstream

z/OS

//MBPEXEC  JOB   CLASS=__,MSGCLASS=___, -etc-

//STEP1    EXEC PGM=MBPrrrB

//STEPLIB  DD    DSN=YOUR.LOADLIB,DISP=SHR

* * * * * DD's for your data files

* * * * * DD's for MAGEC dictionary files

//SYS001   DD    DSN=&&SORTWK,DISP=SHR, etc.

//SYSOUT   DD    SYSOUT=__

//SYS007   DD    SYSOUT=__

//SYSPRINT DD    SYSOUT=__

//

VSE

* $$ JOB JNM=MBPEXEC,CLASS=___

* $$ PRT CLASS=V

// JOB MBPEXEC

// EXEC PROC=MAGECLIB    -pvt. libs. & dictionary DLBL's

* * * * * DLBL's for your data files

// ASSGN SYS001,DISK,...      sort work file(s)

// ASSGN SYS002...                  "

// ASSGN SYS003...                  "

// ASSGN SYS007,SYSLST

// EXEC MBPrrrB,SIZE=(AUTO,20K)

/*

/&

* $$ EOJ

Note: if you have definitions for your files, the sort work files, and/or the MAGEC dictionary files in your "standard labels" you may not need all of the statements above

PC

at the prompt type the command:

EXEC MBPrrrB

Note: In all of the above examples the (rrr) represent the desired MBP number.

DDAUDIT

Auditing the MAGEC Dictionary

One important concept which the authors of MAGEC have promoted among their customers involves the use of an "audit program" to validate the integrity of the database. This concept is valid for both applications' files and for the MAGEC dictionary files themselves. An audit program is simply a program which reads through the files checking for errors and reporting them. Occasionally the audit program can even correct some types of errors, as well.

As an example: an audit program for an accounts receivable system (highly simplified, for this example) might first sequentially read through the customer records checking the "current balance" figure for each customer by reading the invoice records for each customer and tallying them; it might next read through the invoice records checking that the "customer number" specified in each invoice is actually a valid customer defined on the customer file; and so forth. Although exhaustive editing in an online environment should theoretically preclude any such errors from occurring, unforseen hardware or program errors can definitely result in such inconsistencies.

In keeping with our philosophy regarding such matters, MAGEC includes just such an audit program for its dictionary. The program is named: DDAUDIT.

DDAUDIT processes several "phases" of validations against different areas of the dictionary (data definitions, application specifications, etc.). It produces a report which tells, at each phase, what is being validated and what errors were found (if any). The program can be run while online MAGEC is active, if desired.

DDAUDIT Control Card

There is only one control card into DDAUDIT.

Columns Description

1 - 9 constant "DDAUDIT "

10 "Y" or "N" (uppercase flag)

12 "Y" or "N" (auto-fix errors)

The uppercase flag specifies whether you wish the printed output to be converted from lowercase alphabetics to uppercase (necessary for some mainframe printers). "Y" indicates that you do wish uppercase translation. "U" is equivalent to "Y".

The auto-fix flag indocates that DDAUDIT is to corrrect those errors which it can correct as it is processing. "F" is equivalent to "Y".

DDAUDIT Jobstream

z/OS

//DDAUDIT       JOB CLASS=__,MSGCLASS=___, -etc-

//STEP1         EXEC PGM=DDAUDIT

//STEPLIB       DD DSN=MAGEC.LOADLIB,DISP=SHR

* * * * *  DD's for MAGEC dictionary files

//SYSUDUMP      DD SYSOUT=__

//SYSOUT        DD SYSOUT=__

//SYS007        DD SYSOUT=__

//SYSPRINT    DD SYSOUT=__

//SYS006        DD *

DDAUDIT Y Y

//

VSE

* $$ JOB JNM=DDAUDIT,CLASS=___

* $$ PRT CLASS=V

// JOB DDAUDIT

// EXEC PROC=MAGECLIB    -pvt. libs. & dictionary DLBL's

// ASSGN SYS006,SYSIPT

// ASSGN SYS007,SYSLST

// EXEC DDAUDIT,SIZE=(AUTO)

DDAUDIT Y Y

/*

/&

* $$ EOJ

Note: if you have definitions for the MAGEC dictionary files in your "standard labels" you may not need all of the statements above

PC

The control card is in the file "\MAGMF\DDAUDIT.RDR". You can modify it if necessary. Be sure your path includes \MAGMF\JCL since that is where the DDAUDTEX.BAT (or .CMD) file resides. You should not have \MAGMF in your path before \MAGMF\JCL. At the prompt, type the command:

DDAUDTEX

APARC

Archiving an Application

The APARC jobstream is used to archive a complete MAGEC application, or multiple applications, or other definitions from the MAGEC repository. You can retain an unlimited number of versions of any application. The archived applications are stored in a compact format within the repository; actually, they are stored as members in the Library (ALG-file). These members are distinguished from ordinary library members only by the member name prefix, which is "ARC".

Archived applications are stored with member names which are generated by the APARC jobstream. The member names consist of ("ARC" prefix not shown):

Appl-name/date+seq.# (date+seq.# format: YYMMDDSS)

For example: if you were to archive MMP600 on January 12, 2026, the archived application would have a member name of:

MMP600 /26011200

If you were to again archive the same application later that same day, the archived member would be named:

MMP600 /26011201

Similarly, if you were to archive a batch application, say, MBP500B, the archive member name would be:

MBP500B /26011200

If you were to archive miscellaneous repository definitions, perhaps some data definitions, lookup tables, error messages, and copybooks, without any particular application, the archive member name would be:

NULL /26011200

Archiving an application, or other data, does not remove it from the active repository, it merely creates an extracted, compacted file of the application's specifications and customization and then stores it in the Library. The stored member may be accessed via the ARCLOC, ARCSCN, and ARCFND functions. You can delete archived members using the ARCDEL function. The most common way to do this would be to list archive members via the LOC, SCN, or FND functions, then cursor-select a member. Cursor-selecting a member returns the ARCDEL screen to you.

The ARCDEL function allows you to delete a single member, or a group of members. Instructions displayed on the screen tell you that ENTER will delete one member (name shown), PF5 will purge all archive members for a certain application, for a certain date, and PF6 will purge all archive members for a given application, for all dates. PF3, or CLEAR will harmlessly abandon the action without deleting any members.

Archived versions of your application can be retreived and re-loaded to the active repository using the APUNARC jobstream discussed later in this chapter.

The APARC jobstream executes two programs: APUNLOAD and MAGARCV. The control cards for APUNLOAD are discussed earlier in this chapter (refer to APUNLOAD Control Card Formats). APUNLOAD produces an extract file of 80-character text records. That file contains control records identifying which application and/or definitions were extracted; MAGARCV senses those control records and generates the appropriate member name accordingly. Since more than one application may be unloaded via multiple control cards into APUNLOAD, MAGARCV may generate more than one archive member in a single execution.

The archive member for an application will contain all specifications, customization, documentation, screen formats, and security parameters, as well as data definitions and copybooks. Through the use of the standard APUNLOAD control cards you can also include table data, domain definitions, error messages, and miscellaneous library members. Everything needed to re-generate, maintain, and execute the application can be archived.

It is also possible to archive miscellaneous objects without archiving any particular application. This is done using the APUNLOAD NULL control card to specify a null application (none). Refer to the APUNLOAD discussion earlier in this Offline Utilities section.

Note: Jobstream examples are shown on the following page.

APARC Jobstream

VSE

* $$ JOB JNM=APARC,CLASS=F
* $$ LST CLASS=V
* $$ PUN CLASS=P
// JOB APARC       ARCHIVE A MAGEC APPLICATION
// EXEC PROC=MAGECLIB  -pvt. libs. and dictionary files
// ASSGN SYS006,SYSIPT       input control cards
// ASSGN SYS005,........     extracted data to MAGARCV
// ASSGN SYS007,SYSLST       error report
// EXEC APUNLOAD,SIZE=(AUTO,20K)
APUNLOAD ...    (one or more control cards)
/*
// EXEC PROC=MAGECLIB  -pvt. libs. and dictionary files
// ASSGN SYS006,........       extracted data from APUNLOAD
// ASSGN SYS007,SYSLST       error report
// EXEC MAGARCV,SIZE=(AUTO,20K)
/&
* $$ EOJ

z/OS

//APARC JOB (ACCT)      ARCHIVE A MAGEC APPLICATION
//STEP1  EXEC PGM=APUNLOAD
//STEPLIB DD DSN=MAGEC.LOADLIB,DISP=SHR
* * * * * *  DD's for dictionary files
//SYS005     DD  DSN=....    extracted data to MAGARCV
//SYS007     DD  SYSOUT=*    error report
//SYS006     DD  *           input control cards
APUNLOAD ...  (one or more control cards)
/*
//STEP2  EXEC PGM=MAGARCV
//STEPLIB DD DSN=MAGEC.LOADLIB,DISP=SHR
* * * * * *  DD's for dictionary files
//SYS006     DD  DSN=....    extracted data from APUNLOAD
//SYS007     DD  SYSOUT=*    error report
//

PC

Edit, as necessary, the control cards found in the file named: \MAGxx\APARC.RDR

At the prompt, enter:

APARC

APUNARC

Unarchiving an Application

The APUNARC jobstream is used to retrieve an archived version of an application and then restore it as the current active version in the MAGEC repository. The application must first have been archived using the APARC jobstream in order for you to retrieve it. You can specify exactly which version you wish to retrieve via a control card. After APUNARC has successfully completed executing, the current active version will have been replaced entirely by the version which was retrieved. If you wish to retain the current version in order to possibly restore it later, you should archive it (using APARC) before retrieving the older version.

Please refer to the prior discussion of the APARC (Archiving an Application) jobstream for a description of the archive members and their naming convention. The naming convention enables you to retrieve any archived version based upon its date and sequence number. To list archived versions for any application, enter the MAGEC online command:

ARCLOC nnnnnnnn

where: nnnnnnnn = the member name desired.

You can also query for a list of archive members for a certain date, etc., using the ARCSCN and ARCFND functions. They work exactly like ordinary SCN and FND functions do in MAGEC applications. This way you can easily list all archive members for a given date, for example.

The MAGUARCV control card is designed to allow you to omit the sequence number, or both the date and sequence number in order to default to the last sequence number for a given date, or the last sequence number for the current date.

Since the transfer medium used for both APARC and APUNARC is the standard text file format produced by APUNLOAD, you might wish to setup jobstreams which retrieve an archived application from one system (i.e. a "test" system) and load it to another system (i.e. a "production" system).

You might also wish to setup a jobstream which automatically archives the current version of an application on your production system before migrating a new version from the test system. Various other combinations are possible, enabling you to protect yourself against errors which might otherwise destroy a working version of an application.

The control card for APUNARC is in the format:

col 1-10 "-MAGUARCV "

col 11-18 member name

col 19-19 "/" (optional)

col 20-27 date/seq#

APUNARC Jobstream

VSE

* $$ JOB JNM=APUNARC,CLASS=F
* $$ LST CLASS=V
* $$ PUN CLASS=P
// JOB APUNARC       UNARCHIVE A MAGEC APPLICATION
// EXEC PROC=MAGECLIB  -pvt. libs. and dictionary files
// ASSGN SYS006,SYSIPT       input control cards
// ASSGN SYS005,........     retrieved data to APLOAD
// ASSGN SYS007,SYSLST       error report
// EXEC MAGUARCV,SIZE=(AUTO,20K)
-MAGUARCV xxxxxxxx/YYMMDDSS
/*
// EXEC PROC=MAGECLIB  -pvt. libs. and dictionary files
// ASSGN SYS006,........       retrieved data from MAGUARCV
// ASSGN SYS007,SYSLST       error report
// EXEC APLOAD,SIZE=(AUTO,20K)
/&
* $$ EOJ

z/OS

//APUNARC JOB (ACCT)      ARCHIVE A MAGEC APPLICATION
//STEP1  EXEC PGM=MAGUARCV
//STEPLIB DD DSN=MAGEC.LOADLIB,DISP=SHR
* * * * * *  DD's for dictionary files
//SYS005     DD  DSN=....    RETRIEVED data to APLOAD
//SYS007     DD  SYSOUT=*    error report
//SYS006     DD  *           input control cards
-MAGUARCV xxxxxxxx/YYMMDDSS
/*
//STEP2  EXEC PGM=APLOAD
//STEPLIB DD DSN=MAGEC.LOADLIB,DISP=SHR
* * * * * *  DD's for dictionary files
//SYS006     DD  DSN=....    retrieved data from MAGUARCV
//SYS007     DD  SYSOUT=*    error report
//

PC

Edit, as necessary, the control cards found in the file named: \MAGxx\APUNARC.RDR

At the prompt, enter:

APUNARC

Return Codes

In a DOS/VSE environment your MAGEC batch executions may result in a message indicating that a Return Code of 4095 was detected and that the run was abended. This message is not an item to be concerned over. It simply means that the MAGEC batch Cobol programs were compiled under an earlier version of the VSE operating system (pre-SP) which did not support return codes. There are two ways you can eliminate this error message from being issued.

First, you can re-compile all the MAGEC batch programs using your own compiler, thus including the newer Cobol logic which resets the return code to zero.

Second, you can include a statement in your JCL, after the // JOB card, to indicate that you wish to ignore a return code of 4095, we are aware of its meaning and it is harmless. The control statement to include is:

ON $RC=4095 CONTINUE

starting in column 1.

SYSnnn Standards

MAGEC's offline (batch) utilities adhere to a predictable set of standards in the file designations uesd in z/OS or VSE JCL, or in .CMD (for OS/2) or .BAT (for MS-DOS) files. Knowing these simple standards will help you to understand and maintain your jobstreams. The file designations are used as the DD Name, for z/OS; the DLBL Name, for VSE; or the SET Parameter Name for PC's. For example:

//SYSnnn DD ... (above is for z/OS)

// DLBL SYSnnn ... (above is for VSE)

SET SYSnnn=... (above is for PC)

SYS005

SYS005 is always used as the output "punch" file. For instance, in MMPCRE, SYS005 is the generated source program which passes on to the next step (translator, or compiler, etc.).

SYS006

SYS006 is nearly always used for the input "reader" file. This is where input control statements and data are read from by the programs. In rare cases it is used as an output file from a program which is generating "reader" input to the next step in the process, i.e. the MAGECSEP program (PC only) which precedes MMPCRE in the MMPCREAT job..).

SYS008

SYS008 is used as a second "reader" file in programs where two such files are needed. It is occasionally used as an output file passed to a later step, just like SYS006.

SYS007

SYS007 is always the print file output.

SYS010-019

This range of SYS numbers is used for tape, or other portable medium, files. For example, in the ALALDFIL program SYS010 is the input tape (mainframe) or diskettes which MAGEC Software distributes for upgrades to your MAGEC system.

SYS020-029

This range of SYS numbers is used for intermediate work disk files. These files are not normally of any use after the jobstream has completed execution, they are used to temporarily hold or pass data during the run.

Appendix A - PC Batch Files

All of MAGEC's programs are designed to be executed via .BAT or .CMD files, rather than standalone. All of the .BAT/.CMD files provided with MAGEC are in the \MAGMF\JCL directory. You should include \MAGMF\JCL in your path in order to have access to them. All of the programs themselves are in the \MAGMF directory, as are all of MAGEC's data files. It is wise to not include \MAGMF in your path; this eliminates the possibility of accidentally typing in a program name instead of a .BAT/.CMD file name and executing the program without the proper setup normally provided by the .BAT/.CMD files.

Many of the .BAT/.CMD files replicate jobstreams used with MAGEC on the mainframe. They are documented in the "Offline Utilities" chapter of the Programmer's Reference Guide. Some others which are useful are listed below.

REORG

MAGEC utilizes indexed files on the PC, emulating a VSAM or Datacom/DB environment on the mainframe. These files should be reorganized from time to time, just as on the mainframe. To simplify reorganizing the files MAGEC includes a .BAT/.CMD file named REORG. It will reorganize one file at a time. It is invoked from the prompt as:

REORG xxx

where xxx is a Data Class name defined to MAGEC. For example: REORG ALG would reorganize the MAGEC ALG file. The DOS file name for the ALG file is: ALGK1.DAT, according to MAGEC's standards. You can reorganize any of MAGEC's dictionary files or any of your own files this way.

Note: The REORG procedure will not reblock your files. If you wish to alter the block size, you can use the MAGUNLD followed by MAGLOAD procedures. MAGLOAD will set the block size based upon the specification on your DCL (Data Class) profile.

FILESTAT

You can display the statistics and specifications for an indexed file using the FILESTAT command. At the prompt, enter:

FILESTAT xxx

where xxx is the Data Class name of the file. The filespec is assumed to be xxxK1.DAT, according to the MAGEC standard.

CLEANLIB

As you compile programs on your MAGEC PC, you will be creating more and more miscellaneous text files in your \MAGMF directory. These files are not indexed files, they are merely sequential data files used in the program generation, compilation, and link processes. In order to recapture space on your disk you should periodically execute the CLEANLIB.BAT routine. It deletes those files.

The files in question include the Cobol listings from the compiler, the object modules from the compiler, the Cobol source file from the program generator, and the map file generated by the compiler for use in the debugger. These files have extensions of: .LST, .COB, .OBJ, .MAP,, etc.. There are certain .OBJ files which should never be deleted from your \MAGMF directory; therefore, you should not attempt to erase files manually. You shoud use the CLEANLIB routine to erase unneeded files. To do so, from the prompt, enter:

CLEANLIB

There are no parameters for CLEANLIB.

TRACE

When you are using the online facilities of MAGEC, you will ordinarily invoke MAGEC using the trans id of TS01. There is a TS01.BAT file in the \MAGMF\JCL directory. If you wish to invoke MAGEC and place it in debug mode, which enables you to trace your Cobol MMP's, you should execute the TRACE file, instead. To do so, from the prompt, enter:

TRACE

There are no parameters for TRACE. You will invoke the online MAGEC simulator with the debugger activated. Everything will be a bit slower, but will execute the same as it does ordinarily. When you execute an MMP which has the debugging files (MMPxxx.MAP, and MMPxxx.LST) on the \MAGMF directory, the debugger will display the source code and you can control execution step-by-step.

EXEC

When you execute generated batch programs (MBP's) normally, you do so by invoking the EXEC.BAT/.CMD file. To do so, from the prompt, enter:

EXEC xxxxxxxx

where xxxxxxxx is the actual program name to be executed (i.e. EXEC MBP600B).

DBUG

When you execute generated batch programs (MBP's) in debug mode, you do so by invoking the DBUG.BAT/.CMD file. To do so, from the prompt, enter:

DBUG xxxxxxxx

where xxxxxxxx is the actual program name to be executed (i.e. DBUG MBP600B). The program will execute with the debugger activated. If you have the necessary .MAP and .LST files present in the \MAGMF directory, you will be displayed the Cobol source and will be able to control execution step-by-step.

MAGINIT

When you are creating new files to be used by MAGEC, you must initialize them before they can be accessed from the online processes, very much like in the mainframe environment. To initialize a file you use the MAGINIT.BAT/.CMD file, as:

MAGINIT xxx

where xxx is the data class name as defined to MAGEC's dictionary. MAGINIT will prompt you for verification that you really wish to initialize the file specified. Initializing a file, if it already existed, will lose all records on that file. The result will be an empty file.

Note: MAGEC for the PC or PS/2 requires that the indexed files to be accessed conform to a particular naming convention, i.e. xxxK1.DAT (xxx = data class name), and that they be in the \MAGxx directory.

MAGLOAD

When you wish to load an indexed file using, as input, another file (perhaps a sequential file downloaded from a mainframe), you can do so using the MAGLOAD.BAT/.CMD file. The file to be loaded must be defined to the MAGEC dictionary. You type the command:

MAGLOAD xxx

where xxx is the data class name of the file to be loaded. The record length and block size are taken from the MAGEC dictionary definition for the Data Class (DCL).

MAGLOAD will prompt you for the name of the input file. If the input file is not in the \MAGxx directory you must include the path with the name. It will also ask whether the input file is in key sequence. A load operation will be faster if the input is in sequence since MAGLOAD must use random, rather than sequential adds if it is not in sequence.

MAGLOAD will also ask if you wish to ignore any duplicate keys found in the input file. This means duplicates of existing records, as well as of other records on the input file. It will abort upon encountering a duplicate key unless you specify to ignore them, in which case it will simply bypass those records and continue.

It will finally ask you whether you wish to merge (M) the new file's records into the existing records on the output file, or if you wish to clear the output file and initially load (I) it. If you specify I, any pre-existing records on the output file will be lost, the result will be a file containing only the records loaded from the input file.

MAGLOAD does not convert EBCDIC to ASCII or vice-versa, it is assumed that the input file is already properly translated, if appropriate. Your file transfer facility should accomplish any necessary translations " beware of incorrect translations of packed, binary, and signed numerics.

MAGLOAD assumes that the input file is a text file.

MAGUNLD

When you wish to unload a MAGEC indexed file, perhaps to transfer it to a mainframe, you can use the MAGUNLD.BAT/.CMD file. To execute MAGUNLD, enter the command:

MAGUNLD xxx

where xxx = the name of the data class to be unloaded.

MAGUNLD will prompt you to verify that you really wish to unload the specified file. If you made an error in entering the data class name, you will be able to correct it via the interactive prompts. It will then prompt you for the name of the output file to be created.

The output file name should include its drive and path