ARzOS CopyBook

5/28/2007The Home Depot, Inc.

CopyBook Creation 1

CopyBook Creation


CopyBook Creation 2

1. Introduction 3

2. Creating Elements 4

3. Creating Generated Copybooks 433.1 Building the Record 493.2 Add Copybook 683.3 Relate Copybook to Record 723.4 Generate Copybook 763.5 Check-In Copybook 863.6 Check-Out Copybook 953.7 Defining Special Clauses 1013.8 Special Topics 124

4. Creating DBDT Copybooks 138

5. Creating Non-Generated Copybooks 159

Table of Contents


CopyBook Creation 3

1. Introduction• Three types of copybooks exist:

– Generated Endevor type CPY– Non-generated Endevor type NGCPY– DBDT Endevor type DBCPY

• Generated copybooks are built in Allfusion Repository z/OS (ARz/OS) using approved elements.

• Non-generated copybooks are built in Endevor and typically represent:– BMS symbolic copybooks– Vendor copybooks

• DBDT copybooks are built in ARz/OS by Database Administrators

and represent DB2 tables.

TOC


CopyBook Creation 4

2. Creating Elements• Elements are the basic building block for creating a copybook.

• If the copybook you are creating has new elements, you need the ability to add these elements into ARz/OS.

• Each element is identified by a name, status and version.

• The element name should be limited to 18 characters if representing a DB2 column or 21 if not. In the copybook, the element will be prefixed by the copybook name and a hyphen which will account for 9 characters thus assuring the COBOL limitation for user-defined variables of 30 is not exceeded.

• Elements added by developers will use a status of “RQ” and elements added by Data Modelers will use a status of “DQ”.

• Elements may appear in copybooks having an “RQ” or “DQ” status and that copybook can be generated thus making it able to be included in COBOL programs; however, the copybook can not be checked-in until all elements have been approved which changes the status to “APPRV”.

• Data Modelers approve elements; however, not all Data Modelers have this approve authority.

TOC


CopyBook Creation 5

• An element version of “0” (zero) typically represents the preferred version if there exists more than one version of an element. The ELEMENT type will also have a flag indicating that it is the preferred version.

• Each element consists of two or more components where each component represents a valid Home Depot abbreviation.

• The last component also represents a standard class of elements; for example, NBR for number, DT for date, NM for name, etc.

• When composing a new element, determine which components you may use. To do this, use the “GLOSSARY” ARz/OS type.

• Another recommendation is to model an existing element that has similar attributes when inserting the new element. That way, you will limit the number of changes you have to make.

TOC


CopyBook Creation 6

• Basic attributes are– Element name limited to 32 characters– Data Type internal storage type– Length maximum number of significant digits or characters– Decimal number of significant digits after decimal– Picture Clause if blank, generated based on data type, length and decimal– Blank Y for CO0BOL when BLANK WHEN ZERO– Justify Y for COBOL option JUSTIFIED– Sign Y for signed elements– Sign Position L (leading), T (trailing), S (leading separate, X (trailing

separate) – Upper Case only Y if element is upper case– Leading Zeros Y for COBOL option LEADING ZERO– Commas Y for COBOL option COMMAS– Assembler Operation Assembler Operation Code

• Group elements– grouping other groups or elements– make name unique in ARz/OS– support for 10 levels


CopyBook Creation 7

Invoke ARz/OS by typing “D;AR” from the “ISPF Primary Option Menu”.

Option “D;AE” invokes ARz/OS as well and additionally allows you to use QMF.


CopyBook Creation 8

This is the “Welcome” screen. Press <ENTER> with cursor positioned on “OK” to continue.


CopyBook Creation 9

This is the “Main” screen. If you have any other screen, you may use command “MAIN” to take you to this screen.

It depicts the version of ARz/OS you are working with.


CopyBook Creation 10

ARz/OS organizes information by dialogs and then types.

Commands illustrated take you the “GLOSSARY” type in the “DEV” dialog.

Note, commands are stacked by separating with a semi-colon (;).

Commands are not case sensitive.

Command “VD” is short for “View Dialog” and command “VT” is short for “View Type”.



The command “VLE Q” stands for “View List Query” and will allow us to find which abbreviations have a certain word in it.



Before composing the query, a technique to discover the column names is to put a “?” in the “COLUMNS” area and then press <ENTER>.



Highlight the column of interest and copy into your clipboard.



Copied column is pasted and the WHERE clause is completed.

Additionally, because we expect this to be a common query, the query will be saved:1. Assign a name limited to 8 chars. 2. Provide a meaningful description.3. Position cursor on QUERY toolbar option and press <ENTER>.4. Arrow down to “SAVE” in the pick list and press <ENTER> again.

Press <F3> to run the query.If you decide not to run the query, issue the “CAN” command.



Output may be scrolled.

Press <F3> when finished.



Slide depicts selecting a saved query:1. Position cursor on QUERY toolbar option and press <ENTER>.2. Press <ENTER> again as cursor is on the “SELECT” pick list option.3. Select the desired query.



This query will list all standard class abbreviations. Recall an element must end with one of these abbreviations.

Press <F3> to run the query.



Output may be scrolled.

Press <F3> when finished.



Command “VT ELEMENT” switches us to the ELEMENT type.



The command “VLE” stands for “View List Entity”. If executed with nothing below “ELEMENT NAME”, “STATUS” and “VER” , up to 999 elements will be listed. If anything is entered in these fields, only elements beginning with that string, status and version are returned. For example. If an “S” is entered, up to 999 elements beginning with an “S” are returned. If the entire element name is entered, only elements with that name are returned ( may have more than 1 version).



If only one element is returned, you do not need to select it; otherwise select the element(s) you desire in examining and press <ENTER>.

If you want to select them all, use the “TAG” command.



Command “VM” stands for View Mode an is used to toggle between a horizontal and vertical mode.

The horizontal mode is depicted in this slide.

You may still scroll left and right using F10 and F11 to see additional information.



Commands “NEXT” and “PREV” may be used to move forward and backward in the selected elements. However, it is easier to use a PF key.

Use the ISPF KEYS command to set up your keys.



PF4 was changed to “VD DEV” to view the DEV dialog.

PF6 will be used to advance to the “next” entity.

When you press <ENTER>, change PF18 to PREV for “previous” entity.

Press <PF3> to exit setting up the keys.



You may put a question mark in a field and press <ENTER> to see a list of choices.

Additionally, if you enter an “H” on the command line, you will help information on that field.



The choices for data type are presented.



ELEMENT INFORMATION: ELEMENT NAME ===> SKU_NBR STATUS, VERSION ===> APPRV V: 0 BUSINESS NAME ===> SKU NUMBER ===> OPTIONAL TEXT ===>

This section of information provides the key for the element; name, status and version and the description of the element contained in the BUSINESS_NAME column.

The OPTIONAL TEXT field contains the VARIATION_NAME from Brownstone unless the field contains “XML TAG” in which case the field will be blank.



ON SCREEN TIE INFORMATION: ALIAS OF ELM NM ===> STATUS, VERSION ===> V:

If an element is an alias of another element, then the root element and its status and version will appear in this area.



STORAGE PARAMETERS: DATA TYPE ===> INTEGER MAXIMUM LENGTH ===> 0 DECIMAL PLACES ===> 0 SIGNED ELEMENT ===> Y (Y/N) SIGN POSITION ===> N CUSTOM PICTURE ===> This section of information provides data type, length and other pieces of information that aid in generating the PICTURE clause for the element.

If a field has a standard length that is based upon its data type, the MAXIMUM LENGTH field will equal zero.

If the CUSTOM PICTURE is blank, ARz/OS will generate the PICTURE clause for the element using the other pieces of data; data type, length, sign, etc. If the CUSTOM PICTURE is not blank,it will be the actual PICTURE clause used for that element. Typically, those elements are special display type elements.



DETAIL INFORMATION: PREFERRED ===> Y (Y/N) TO BE RETIRED ===> N (Y/N) XML USAGE ===> (Y/N) VENDOR SOFTWARE ===> N (Y/N) XML TAG ===>

This section of information contains miscellaneous detail:

PREFERRED Element is the preferred usage when more than one version exists for the element.

TO BE RETIRED Element is to be retired. Originally element was in PP status in Brownstone. As it is still being used, it has an APPRV status and should not be considered for usage.

XML USAGE Element represents an XML field. During conversion, if the Brownstone VARIATION_NAME contained the text “XML TAG”, this field was set to a “Y”

VENDOR SOFTWARE Whether or not the element represents an element from a vendor.

XML TAG Contains the element name if the XML_USAG_FLG = “Y”



NAME INFORMATION: DB2 COLUMN NAME ===> BABY_SKU_NBR C NAME ===>

ASSEMBLER NAME ===>

This section provides the DB2 column name if the element represents a DB2 column. The other two name fields are not used.



DISPLAY ATTRIBUTES: COMMAS ===> N (Y/N) BLANK WHEN ZERO ===> N (Y/N) LEADING ZEROS ===> N (Y/N) RIGHT JUSTIFY ===> N (Y/N) UPPER CASE ONLY ===> N (Y/N)

This section provides display attributes.



ORIGINAL SYSTEM HISTORY: BROWNSTONE INTERNAL ID ===> 6229 CRT USER ID ===> DAJLP CRT DATE TIME VALUE ===> 91/09/21 18:08.09 UPD USER ID ===> ADRXF UPD DATE TIME VALUE ===> 95/11/01 16:18.22

This section of information contains original system information from Brownstone. Each Brownstone element was converted to an ARz/OS element.

The first field above is the value of the INTERNAL_ID from PRDDS50.E_ELM for the element in question (SKU_NBR).

The creator information provides who and when the element was first added to Brownstone and the update information provides who and when the last update against this element took place in Brownstone.



HISTORY INFORMATION: CREATED BY, DATE, TIME ===> ADRVD 2006-12-29 14.03.40 MOD BY, DATE, TIME ===> ADRVD 2007-02-22 16.31.48

This section of information contains information when the element was added to ARz/OS and subsequently updated.

The creator information provides who and when the element was first added to ARz/OS and the update information provides who and when the last update against this element took place in ARz/OS.

The creator information will come from the DBXLOAD load process if the element was converted from Brownstone. The modified information may also be from a DBXLOAD process if a latter load updated one or more of the attributes.



Creating the New Element

• The recommended steps for creating a new element:– Determine components of the element name using accepted Home Depot standard abbreviations

from the GLOSSARY entity and ending in a standard class word also in that same entity.– Match on an element with similar characteristics.– Change the element name you matched on to the new element name.– Enter a STATUS of RQ if you are a developer or DQ if you are a Data Modeler.– Enter a VERSION of 0.– For BUSINESS NAME, enter an appropriate description of the element.– For the remaining sections of the map, modify any parameter different than the modeled element.– Issue EDIT.INSERT or EI command to add new element.– Enter TD to provide a text description.

• These new elements may be used in a copybook; however, that copybook can not be checked in until a Data Modeler has approved it which changes the status to APPRV.



The element that the new element will be based on is displayed.



The following fields were changed:•ELEMENT NAME•STATUS •VERSION•BUSINESS NAME

EI command used to insert new element.



Components of element name representing abbreviations are expanded.



Map was scrolled to the bottom to illustrate “HISTORY INFORMATION” before typing“TD” command to provide text description.



A text description is provided.

Administrative notes can be provided using the “ADN” command. This is usually done by a Data Modeler.



DISPLAY SPECIAL

• In Brownstone, there was a special element type code, DS, representing “Display Special”. These elements typically had a non-standard PICTURE clause or represented a data type in Brownstone that was not directly supported; namely INTEGER or DECIMAL.

• These elements were converted to ARz/OS by adding them to a copybook and then scanning that copybook in.

• In many cases, these elements became standard elements in ARz/OS in that by storing the data type, length, scale, sign, etc., ARz/OS would be able to generate the appropriate PICTURE clause when using the element in a copybook.

• In those cases, where the PICTURE clause was truly a “display special”, the PICTURE clause is stored as a column in the ARz/OS metadata table ( DBX_DDL_ELEMENTS) and it is used as the PICTURE clause when attached to a copybook.

• The table on the following page will provide some examples.



Brownstone ---------------------------------------------- ARz/OS ---------------------------------------------PICTURE PICTURE DATA TYPE LENGTH DECIMAL SIGN COMMAS

9(5) blank NUMERIC 5 0 N N

S9(9) blank NUMERIC 9 0 Y N

-9(9).9(2) -9(9).9(2) NUMERIC 13 2 Y N

-ZZZZZZ -ZZZZZZ NUMERIC 7 0 N N

ZZ,ZZZ,ZZ9 ZZ,ZZZ,ZZ9 NUMERIC 10 0 N Y



3. Creating Generated Copybooks

• To start off, have an idea of what elements will exist in your copybook. Make a list and specify the order.

• If an element has more than one version, determine which version you want. Generally, a version of “0” is the preferred element. There will also exist a “PREFERRED” flag when looking at the element in ARz/OS in the “ELEMENT” type.

• Determine if any element will have “88” levels.

• You may also wish to verify you have the proper RACF security. You will need access to group $EN<SYS>ESI. For example, system code “TA” would need access to $ENTAESI. Use TSO command “BTSO LU <your TSO ID> i.e. “BTSO LU ADRVD”. Search the generated output.

• Creating the copybook will involve entering information in the following ARz/OS panel types in the steps specified:1. RECORD Builds the record structure2. COPYBOOK Adds the new copybook3. COPY REC Relates COPYBOOK to the record(s) it contains4. COPYBOOK Back to copybook to generate the copybook5. COPYBOOK Check-in the copybook

TOC



• A copybook will consist of a record possibly having one or more group items and one or more elementary items.

• Each record name will be unique and each group item name should be unique as well.

• Records and group items have the traditional Life Cycle Phases you are familiar with starting with AD ( Application Development ) or AT ( Architecture Test ). Once the copybook is checked in, their status will change as migration events occur to ST, QA and finally PR.

• Elementary items in the record represent elements also having a status and version. Their status will be different than the other two types.



• Status values for elements:

– APPRV Elements in an approved status

– RQ Elements in a request status awaiting to be approvedCreated by developers

– DQ Elements in a request status awaiting to be approvedCreated by data modelers

– INUSE Elements used in the environment that should be managed but are notShould be approved and changed to APPRV

– RET Elements that have been retired

• Before a copybook can be checked in, each element must be in the APPRV status.

• You may still use a generated copybook before the elements have been approved but run the risk of coding changes if the element name or its characteristics are not approved.



Copybook Metamodel



ARz/OS

Copybook -ST

Table - ST

Copybook -AD/AT

Copybook -QA

Copybook -PRTable - PR

Table - QA

Table AD/AT Migrate

Migrate

Migrate

Quick REC UserCreate/Edit

Endevor

Gen

erat

e Co

pybo

okLo

ad N

on-G

ener

atab

le C

opyb

ooks

No R

ecor

ds, G

roup

or E

lem

ents

External Source

Vender ProductDev around Vendor Prod

Bad Programmers

Scan

DBD

T Co

pybo

okDBA Edit

DBMSCatalog

Ele

men

ts

Gen

erat

e D

BD

T C

opyb

ook

Table - DE

ER/Win

Manage Non-Generatable copybooks

CatalogSync

DDL

CopyBook Flows

MigrateCopy

(GeneratableCopybooks only)



CPYLIB

STRUCT

STRUCT

ELM

BROWNSTONE

ELM

ARz/OSCOPYBOOK

RECORD

GROUP

ELEMENTELEMENT

This slide illustrates the similarities between Brownstone and ARz/OS in how generated

copybooks are structured.



From the main screen, go to the “RECORD” type in the “DEV” dialog.

If already in the “DEV” dialog, just use “VT RECORD” .

3.1 Building Record

TOC



The way a screen is viewed (horizontal versus vertical ) may be toggled with command “VM” (View Mode).

For data entry mode, use a vertical screen.



Key information is first entered;NAME, STATUS and VERSION. Use the values shown for STATUS and VERSION.

The record name should be unique.

New records initially have a status of “AD” .

A question mark (?) may be entered to present a window of the valid choices you may select from.



Choose the appropriate programming language that will use the record.

Most likely, you will use COBOL and the code value will be a “C”.



Command “EI” (Edit Insert) is used to add the record.

If you made an error in the record name after the insert, simply change the name and do an “EU” (Edit Update).



Note, when the record is inserted, audit information is maintained. See the last two fields on the screen.



To continue, the fields must be added to the record.

One way is to use the toolbar approach to drill down to the “Quick Record” facility:

OPTIONS -> QUICK -> REC

A shortcut is to use command “QREC”.



Position cursor on “MAX” to maximize the screen in order to see more data and press <ENTER>.



Group level item was entered and line command “I” used to insert a new line.

Note, all of the line commands you are familiar with may be used:D - DeleteI - InsertC - CopyM - Move A - AfterB - Before

Make the group item name unique. Verify against the “GROUP” type.



Command “VLE” can be executed on the “GROUPS” entity for groups beginning with “EMPL_” to verify if not only the record but any group items already exists.

The example to the left illustrates the record name and group items after our record has been built.



You must select the elements from a list:1. Enter a prefix followed by a “?” in the “GROUP / ELEMENT NAME” column.2 Change the status to “APPRV” 3. Blank out version 4. Press the <ENTER> key.

A list of elements beginning with that prefix in the “APPRV” status and any version will be displayed.



Results are shown. Select one or more of the elements, scrolling if necessary.

Press <ENTER> when you have finished selecting the fields.



Selected element now appears in the record structure.

Also note that the level number for this field was changed to “03” to make it subordinate to the field above; in effect make that field a group item.



Another group item has been added again making the name unique. Recall the line command “I” was used to insert new lines.

The second line will be used to insert new fields. The “LVL” was changed to “03”.



Three more elements were selected.

Now it is desired to rearrange some of the fields. Again line commands which you are already familiar with are used.

Note, it is not necessary to complete a record structure in one sitting. You can save along the way by using the toolbar option “PROCESS”.



Record structure is illustrated after fields have been rearranged and one more field is added.

Note, if you know the element name, type it followed by a question mark (?). If only one version exists, it will automatically be selected.



To examine a field’s attributes, choose the tool bar “DETAIL” option and then ‘VIEWEDIT” from the drop down list. You must select a field first.



Elements with a version of “0” are typically the “preferred” element.

You may view the view the element in the “ELEMENT” entity. One of the attributes is the “PREFERRED” flag.



Once you have selected all of the fields to build the record, you must use the “PROCESS” command to apply the changes. Simply, position the cursor on the toolbar option and press <ENTER>.

Press <F3> to exit the QuickRec facility.



The next step is to add the “COPYBOOK” instance. Use command “VT COPYBOOK” to go to that type.

3.2 Add Copybook

TOC



You may use the “VLE” command to list similar copybooks and then use one of them as a model to insert the new copybook.



Select the record you wish to model. As explained on the next slide, it should be from the same subsystem.



Command “EI” is used to insert the record. The record you modeled should be for the same subsystem; otherwise, you must change to the correct sub-system code. You may put a question mark “?” to see a valid list to choose from.

You should also change the “GENR VALUE CLAUSES” and “GENR 88 LEVELS” to a “Y” if you desire those features. Note, if you change these fields after the initial insert, you must use the “EU” command to update; otherwise, you will get a message that the entity has been changed but not updated.



The next step is to go the “COPY REC” relationship using the command:

GOTO COPY REC

This entity will relate the copybook to the record(s) it contains.

3.3 Relate Copybook to Record

TOC



The record name, status and version are entered as illustrated.

Then the “EI” command is used to insert the relationship.

If you are unsure of the entire RECORD NAME, you may enter a partial name and use the VLT (View List Target) to present a list to choose from.



The “COPY REC” relationship is illustrated after the insert.



COPYBOOKTIDA9001

1089046 557

GROUPEMPL_KEY_001_GRP001

1089045 25434

COPY RECTIDA9001.

EMPL_REC_001

1089047 570

RECORDEMPL_REC_001

1089043 200

REC MAPEMPL_REC_001.

EMPL_KEY_001_GRP001

1089061 25434

ELEMENTEMPL_SSN_NBR

891811 25434

GROUPSEMPL_KEY_001_GRP001

1089045 25434

FIELDEMPL_KEY_001_GRP001.

EMPL_SSN_NBR

1089052 207

FIELDEMPL_REC_001.

EMPL_KEY_001_GRP001

1089054 207


EMPL_KEY_001_GRP001

1089058 25434


SEX_TYP_CD.7

1089059 25434

RM VALUEEMPL_REC_001.

SEX_TYP_CD.7.FEMALE

1090828 25438

VALUEFEMALE

1090827 209

This slide contains the metadata model for our new copybook. Not all GROUPs, ELEMENTs, etc. are shown.



Final step is to “Generate” the record.

This action is done in the “COPYBOOK” entity. You may use the “GOTO” command to get to that entity.

Once you have generated your copybook, it may be used in COBOL compiles initiated in Endevor. However, if you have any element that is not in APPRV (approved) status, it can not be checked in.

3.4 Generate Copybook

TOC



Enter “G” on the command line to begin the process and then press <ENTER>.



Slide illustrates PDS location where copybook member is saved. The group will be “BMPX” if you are using the production version of ARz/OS. This presentation was constructed using the test version.



Review how the copybook looks. Again, you should have an idea of which fields should be present and their associated attributes. If you see one or more errors, use <F3> to cancel operation and then make corrections before reattempting the generate.

If satisfied with the output, enter the “GO” command and press <ENTER>.



Operation submits a job. Note the job name and number and go to SDSF to check the results.



The operation was successful as indicated by the condition codes.



The next few slides will illustrate examining the copybook, its record and finally the elements.

First, the “JUMP RECORD” command will be used to get to the “RECORD” entity.



Next, the “JUMP ELEMENT” command is used.



“VM” command is used to toggle to vertical mode.



Only the elementary elements are displayed. If you scroll right far enough, you will see other attributes such as data type and length.



In order for your new copybook to be migrated, you will need to check it in. This process will add it as a new element having a type of CPY to Endevor.

It is very important that all of your elements are in the “APPRV” status; otherwise, the check-in process will fail. The next three slides illustrate if one or more fields are not in “APPRV” status.

Use the command “CI” to initiate this process.

3.5 Check-In Copybook

TOC



When you view your job output in SDSF and select the first file

(JESMSGLG), the condition code (CC) will equal 0012.

If you view the last (SYSER01), you will see the field(s) having an incorrect status. You must get these elements approved before executing the check-in process again.

Note, the ST option for SDSF was chosen. If you use the held output option (H), the last two output files to the left will be in separate listings.



Output file illustrates the field(s) that are not approved as well as their status and version.



To see the error information to the left:1. Log onto Development CICS (C02TA09)

2. Use transaction code AAD13. Fastpath to dialog ALOGLST4. Enter your TSO ID in USER

ID field and press <ENTER>.

5. Put an “S” in the SELECT column of the 1st row and press <PF9>.

The relevant information will be found in the SDSF job output as noted on the prior slide.



After the “CI” command is issued, this is the next panel the user will see.

Slide illustrates the attributes to be used when adding the element to Endevor as well as the job card information for the job.

The “COMMENT” comes from the “DESCRIPTION” when the copybook was added.

Press <ENTER> to continue.



This is the PDS used by the compile process confirming success.

Again note, “AD” in the PDS name as the test system was used.



Element detail is illustrated in Endevor.



Once an element has been migrated beyond “AD” or “AT”, it can be checked out using the command “CO”. Because the listed copybook is at “ST”, it will be checked out from that LCP to “AD”.

3.6 Check-Out Copybook

TOC



Element detail is illustrated in Endevor.




.



Now there are two versions in ARz/OS.



… and there are two versions in Endevor.



When creating a record using the QuickRec facility, you may need to use techniques for specialty clauses:

• OCCURS / DEPENDING• ASCENDING KEY / DESCENDING KEY• INDEXED BY• REDEFINES• VALUE• 88 LEVELS• FILLER

3.7 Defining Special Clauses

TOC



OCCURS / DEPENDING

BROWSE CPRTA.SH.BMPX.AD.COPYSHR(AADA0201) Line 00000081 Col 001 080 Command ===> Scroll ===> CSR 05 AADA0201-DFLT-MAX-BU-CNT PIC S9(04) COMP 05 AADA0201-DFLT-BUS-UNT OCCURS 00050 TIMES INDEXED BY AADA0201-BU-TYP-CD-IDX.

BROWSE CPRSS.SH.BMPX.CPYSRC(AADF0031) Line 00000008 Col 001 080 Command ===> Scroll ===> CSR 05 AADF0031-CAN-STEP-ARRAY OCCURS 1 TO 1300 TIMES DEPENDING ON AADF0031-CAN-STEP-IDX-NBR. 10 AADF0031-CAN-STEP-NBR PIC S9(4) COMP. 10 AADF0031-CAN-STEP-ACTN-CD PIC X(1).

The number of occurrences is defined on the panel where the fields are listed by scrolling to the right and entering that number in the “OCC 1” column and if the number varies, the “OCC 2” column as well . If the number of occurrences varies, a “DEPENDING” function will be defined to specify the object of the clause ( CAN-STEP-IDX-NBR in the second example above).



Use the <F11> key to scroll right and overtype the zero in the “OCC 1” column to the number of occurrences you desire, 50 in our example (see next slide).

If the number of occurrences also varies, overtype the zero in the “OCC 2” column to the max number of occurrences you desire, 1300 in the second example on the prior page.



Note the other columns:OCC2 Max number of

occurrences

FNC Function defined on field

VAL “88” levels defined on field



ASCENDING KEY / DESCENDING KEY

BROWSE CPRSS.SH.BMPX.CPYSRC(AADD0101) CHARS 'ASCEND' foundCommand ===> Scroll ===> CSR 05 AADD0101-BP-SOBJ-ATTR. 10 AADD0101-BP-SOBJ-ATTR-TBL OCCURS 50 TIMES ASCENDING KEY IS AADD0101-SOBJ-ATTR-ID INDEXED BY AADD0101-SOBJ-ATTR-INDX. 15 AADD0101-SOBJ-ATTR-ID PIC X(24). 15 AADD0101-DATA-TYP-IND PIC X(9). 15 AADD0101-ATTR-VAL PIC X(30).

The “ASCENDING” key is defined as the “KEY” function. If desired, a descending key can also be defined and the function type is “DESC KEY”.



Select the field that has the clause (AADD0101-BP-SOBJ-ATTR-TBL on the prior page )and then position cursor on the toolbar option “DETAIL” and then press < ENTER>.

Arrow down to “FUNCTION” and press <ENTER> again and finally choose the “KEY” function and press <ENTER> one final time.

Note, one field may have more than one function. This one has two.



The target name field should be the field in the clause“ASCENDING KEY”.

Do not include the record prefix.



INDEXED BY

BROWSE CPRTA.SH.BMPX.AD.COPYSHR(AADA0201) Line 00000081 Col 001 080 Command ===> Scroll ===> CSR 05 AADA0201-DFLT-MAX-BU-CNT PIC S9(04) COMP 05 AADA0201-DFLT-BUS-UNT OCCURS 00050 TIMES INDEXED BY AADA0201-BU-TYP-CD-IDX.

The “INDEXED BY ” clause is defined as the “INDEX BY” function.



Select the field that has the clause (AADD0101-DFLT-BUS-UNT on the prior page ) and then position cursor on the toolbar option “DETAIL” and then press < ENTER>.

Arrow down to “FUNCTION” and press <ENTER> again and finally choose the “INDEX BY” function and press <ENTER> one final time.



The target name field should be the field in the clause“INDEXED BY”.




REDEFINES

BROWSE CPRSS.SH.BMPX.CPYSRC(AADA0201) CHARS 'REDEFINES' found Command ===> Scroll ===> CSR 05 AADA0201-PFKEY-AREA PIC X(228). 05 AADA0201-PFKEY-AREA-REDF REDEFINES AADA0201-PFKEY-AREA OCCURS 12 TIMES INDEXED BY AADA0201-PFKEY-AREA-IDX. 10 AADA0201-PFKEY-ASSG-CD PIC X(08). 10 AADA0201-PFKEY-SCRN-DESC PIC X(10). 10 AADA0201-DSPL-PFKEY-FLG PIC X(01). 88 AADA0201-DSPL-PFKEY-ON VALUE 'Y'. 88 AADA0201-DSPL-PFKEY-OFF VALUE 'N'.

The “REDEFINES” clause is defined as the “REDEFINE” function.



Select the field that has the clause (AADDA0201-PFKEY-AREA-REDF on the prior page ) and then position cursor on the toolbar option “DETAIL” and then press < ENTER>.

Arrow down to “FUNCTION” and press <ENTER> again and finally choose the choose the “REDEFINE” function and press <ENTER> one final time.



The target name field should be the field being redefined.




VALUE

BROWSE CPRSS.SH.BMPX.CPYSRC(AADA0201) Line 00000141 Col 001 080 Command ===> Scroll ===> CSR 05 AADA0201-ACCS-PRTCL-IND PIC X(08) VALUE 'HTTP'. 88 AADA0201-ACCS-PRTCL-BMS VALUE 'BMS'. 88 AADA0201-ACCS-PRTCL-HTTP VALUE 'HTTP'. 88 AADA0201-ACCS-PRTCL-CICS VALUE 'CICS'.

To assign a field an initial value, you use the technique to examine a field’s attributes. You must scroll forward until you see the field where that value is entered.



Select the field that has the clause (AADA0201-ACCS-PRTCL-IND on the prior page ) and then position cursor on the toolbar option “DETAIL” and then press < ENTER>.

Select the first option, VIEWEDIT, and press <ENTER>.



Scroll forward until you see “INITIAL VALUE” as indicated to the left. Type in the initial value using single quotes if the field is not numeric.



88 Levels

BROWSE CPRSS.SH.BMPX.CPYSRC(AADA0201) Line 00000011 Col 001 080 Command ===> Scroll ===> CSR 05 AADA0201-API-RTN-CD PIC S9(4) COMP. 88 AADA0201-RTN-CD-OK VALUE 0. 88 AADA0201-RTN-CD-WRN VALUE 1. 88 AADA0201-RTN-CD-FA VALUE -1.

“88” levels are defined as the “LEVEL-88” function.



Select the field that has the clause and then position cursor on the toolbar option “DETAIL” and then press < ENTER>.

Arrow down to “FUNCTION” and press <ENTER> again and finally choose the desired function again by highlighting the desired function and pressing <ENTER> one final time.



Type the “88” level in the “VALUE NAME” column and the value(s) in the “VALUE” column.

You may enter a “?” in the “VALUE NAME” column and press <ENTER> to select from a list.

If your “88” level is not defined, use a status of “AD” and a version of “0”.

“88” levels are stored in the “VALUE” dialog type. You can examine that entity if need be.



FILLERBROWSE CPRSS.SH.BMPX.CPYSRC(AADR3021) Line 00000000 Col 001 080 Command ===> Scroll ===> CSR ******************************** Top of Data ********************************** ****************************************************************** * COPYBOOK FOR STANDARD REPORT HEADERS * ****************************************************************** 01 AADR3021-RFM-STD-RPT-HDR. 05 AADR3021-RFM-HDR-LINE-1. 10 FILLER PIC X(01). 10 AADR3021-RFM-HDR-RPT-ID PIC X(08). 10 FILLER PIC X(42). 10 AADR3021-RFM-HDR-CO-NM PIC X(30). 10 FILLER PIC X(35). 10 AADR3021-RFM-PG-LIT PIC X(06) VALUE 'PAGE: '. 10 AADR3021-RFM-PG-NBR PIC ZZ,ZZZ,ZZ9.

Each FILLER is handled by selecting the field and then using the DETAIL option of VIEWEDIT to provide the length.



FILLER field is selected and DETAIL option of VIEWEDIT is chosen.



The length for the first FILLER is 1. Enter that value in the “MAXIMUM LENGTH” field. Continue for the remaining fields having FILLER.



Instead of using the toolbar options to invoke the “DETAIL” options, there are commands you may use.

The screen to the left, pulled down with the “SYSTEM” toolbar option and then “COMMANDS” option illustrates your choices. For example, 88 levels use command “LEVEL-88”. Remember you can customize these commands.



This section will discuss methods for handling the following type of special cases:

• Multiple Records in a Copybook• Reuse Existing Group Element

3.8 Special Topics

TOC



Multiple Records in a Copybook

• Normally one copybook contains a single record.

• However, it is possible to have multiple records in a single copybook.

• You create the copybook and records in the same manner.

• The connection is made in the COPY REC relationship.

• Each field of each record will be qualified by the copybook name; thus, if you have the same element in more than one record, you will have to qualify the field in the COBOL program.

• The following slides will illustrate key points about this process.



After creating the COPYBOOK and each of the 3 RECORDs, a

“GOTO COPY REC” was done for the first of three records.

For “COPY INFORMATION”, the copybook name, status, and version are entered. The name will be the same for all records.

For RECORD/GROUP INFORMATION, the record name, status and version are entered.

Under DETAIL PARAMETERS, the sequence number (1,2,3) is specified.

Repeat process for other 2 records.



Slide illustrates the effect of jumping from COPYBOOK (AADA9991) to RECORD after entering the COPY REC info for each of the 3 records.

Next two slides illustrate the generated copybook.



BROWSE CADTA.SH.BMPX.AD.COPYSHR(AADA9991) Line 00000000 Col 001 080 Command ===> Scroll ===> CSR ******************************** Top of Data ********************************** ****************************************************************** * NAME: AADA9991 * STATUS: AD * VERSION: 0 * SYNTAX GENERATED ON 05/15/2007 AT 13:08:39 * GENERATED BY: ADRVD ****************************************************************** * GENERATION FLAGS: VALUE-CLAUSE=Y LEVEL-88=Y 01 AADA9991-RFM-BGN-BLK. 05 AADA9991-RPT-ID PIC X(08). 05 AADA9991-REX-REC-TYP-IND PIC X(01). 88 AADA9991-RFM-BEGIN-REC VALUE 'B'. 88 AADA9991-RFM-DATA-REC VALUE 'D'. 88 AADA9991-RFM-END-REC VALUE 'E'. 05 AADA9991-SORT-FLD-TXT PIC X(100). 05 AADA9991-RFM-BGN-DATA-TXT. 10 AADA9991-RFM-AS-OF-DT PIC X(10). 10 AADA9991-RFM-RUN-DT PIC X(10). 10 AADA9991-RFM-RUN-TM PIC X(8). ***************************************************************** * NAME: RFM_DATA_BLK * STATUS: AD * VERSION: 0 * SYNTAX GENERATED ON 05/15/2007 AT 13:08:39 * GENERATED BY: ADRVD ***************************************************************** ******************************************************************



01 AADA9991-RFM-DATA-BLK. 05 AADA9991-RPT-ID PIC X(08). 05 AADA9991-REX-REC-TYP-IND PIC X(01). 88 AADA9991-RFM-BEGIN-REC VALUE 'B'. 88 AADA9991-RFM-DATA-REC VALUE 'D'. 88 AADA9991-RFM-END-REC VALUE 'E'. 05 AADA9991-SORT-FLD-TXT PIC X(100). 05 AADA9991-DATA-FLD-TXT PIC X(1198). ************************************************************ * NAME: RFM_END_BLK * STATUS: AD * VERSION: 0 * SYNTAX GENERATED ON 05/15/2007 AT 13:08:40 * GENERATED BY: ADRVD ************************************************************ ************************************************************* 01 AADA9991-RFM-END-BLK. 05 AADA9991-RPT-ID PIC X(08). 05 AADA9991-REX-REC-TYP-IND PIC X(01). 88 AADA9991-RFM-BEGIN-REC VALUE 'B'. 88 AADA9991-RFM-DATA-REC VALUE 'D'. 88 AADA9991-RFM-END-REC VALUE 'E'. 05 AADA9991-SORT-FLD-TXT PIC X(100). 05 AADA9991-RFM-END-DATA-TXT. AA10 AADA9991-RFM-DATA-RCDS-NBR PIC S9(09).

As each record has some common fields, you must qualify the field in the COBOL program:

IF AADA9991-SORT-FLD-TXT OF AADA9991-RFM-DATA-BLK > SPACES



Reusing Existing Group Element

• A group element consists of one or more elementary fields.

• If you have a common group of fields that exist in multiple records, entering the group name of an existing group while in QuickRec will pull in the elementary fields attached to that group.

• This example to illustrate reuse of a group element will take the copybook from the prior section that had three records in it. Each record had a common key, the first three fields. The first record will create a new group for this key and the two remaining records will then reuse it.



QuickRec layout prior to any changes.



First change was to DEFAULT STATUS to APPRV. Most fields will be elementary instead of group and this saves time when entering new non-group fields.

First field was overtyped with new group, REX_SORT_KEY, and status and version specified.

A new line is to be inserted after the new group field.



Inserted line was used to specify 1st field of sort key, the field that was overtyped with the new group. The question mark after the field, RPT_ID?, is required to make the connection to pull in the element’s info. Status and version are also specified.



Change the level (LVL) of the two remaining fields of the sort key.

After pressing <ENTER> make sure you use the toolbar option PROCESS to apply your changes before exiting (F3).



The QuickRec facility was invoked for the second record.

The first field was overtyped with the new group name including the question mark, REX_SORT_KEY?. The status and version were also typed.

The next two fields will be deleted.



You are done or the second record! Note, the three fields of the group item have been pulled in.

Again, use the toolbar option PROCESS.

Repeat this process for the third record.



BROWSE CADTA.SH.BMPX.AD.COPYSHR(AADA9991) Line 00000000 Col 001 080 Command ===> Scroll ===> CSR ********************************* Top of Data ********************************* ****************************************************************** * NAME: AADA9991 * STATUS: AD * VERSION: 0 * SYNTAX GENERATED ON 05/15/2007 AT 15:09:53 * GENERATED BY: ADRVD ****************************************************************** * GENERATION FLAGS: VALUE-CLAUSE=Y LEVEL-88=Y 01 AADA9991-RFM-BGN-BLK. 05 AADA9991-REX-SORT-KEY. 10 AADA9991-RPT-ID PIC X(08). 10 AADA9991-REX-REC-TYP-IND PIC X(01). 88 AADA9991-RFM-BEGIN-REC VALUE 'B'. 88 AADA9991-RFM-DATA-REC VALUE 'D'. 88 AADA9991-RFM-END-REC VALUE 'E'. 10 AADA9991-SORT-FLD-TXT PIC X(100).

Above example only illustrates the first record and only the new group item containing the sort key.



• DBDT copybooks represent DB2 tables.

• Copybooks are created by Database Administrators using ARz/OS while in the “TABLE” type.

• The “CIDB” command is used to kick off the process.

• Before this command may be used, following attributes must exist:– “RECORD PREFIX” – “DESCRIPTION”

• “RECORD PREFIX” can not be updated on the screen while “DESCRIPTION” may be.

• “RECORD PREFIX” will be DBDTnnn1 where:– DBDT is a constant– nnn represents short table ID and comes from the tablespace name.– 1 is a constant

4. Creating DBDT Copybooks

TOC



• An ARZOS table will store the “RECORD PREFIX”:

SELECT ENT_ID, SUBSTR(TB_NAME,1,18) , STATUS, VERSION, RECORD_PREFIX , SUBSTR(QUAL_TABLE_NAME,1,45) FROM AD6IS.DBX_DB2_TABLES -- WHERE TB_NAME = 'JOB_DRVR_PARM' WITH UR

ENT RECORD ID COL1 STATUS VERSION PREFIX COL2 ----------- ------------------ -------- ------- --------------- -------- 958879 JOB_DRVR_PARM AT 0 DBDTA441 NP1.AD1T

• Notice how it ties to the tablespace name:

SELECT CREATOR, NAME, TSNAME FROM SYSIBM.SYSTABLES WHERE CREATOR = 'AD1TI' AND NAME = 'JOB_DRVR_PARM' WITH UR

CREATOR NAME TSNAME -------- ------------------ -------- AD1TI JOB_DRVR_PARM AD1TIA44



• The “CIDB” command:– Submits a batch job. You should check that each step is successful in SDSF. – May be used only when the table’s STATUS is AD or AT.

• Upon successful completion:

– A new “COPYBOOK” entity will exist in ARz/OS (DBDTnnn1).

– A new PDS member will exist.

– A new Endevor element will exist.

• Which PDS the member is added to is dependent on the “STATUS” of the “TABLE” entity in

ARz/OS:

– A STATUS of “AD” adds the member to “CADSS.SH.BMPX.CPYSRC”.

– A STATUS of “AT” adds the member to “CATSS.SH.BMPX.CPYSRC”.

• The new Endevor element’s environment will be dependent on the table’s STATUS IN ARz/OS.



• For a STATUS of “AD”, the Endevor attributes are as follows:

ENDEVOR Location: ENVIRONMENT.. DEVL SYSTEM....... TA SUBSYSTEM.... DB ELEMENT...... DBDTnnn1 TYPE......... DBCPY

• For a STATUS of “AT”, the Endevor attributes are as follows:

ENDEVOR Location: ENVIRONMENT.. ARCH SYSTEM....... TA SUBSYSTEM.... DB ELEMENT...... DBDTnnn1 TYPE......... DBCPY



Invoke the “DBA” dialog and the “TABLE” type.



Start by using the “VLE” command to list the table you wish to create the DBDT copybook for.



Switch view mode to vertical mode from horizontal.



You might wish to do a cross reference before proceeding.



Cross reference display is depicted. Screen size was switched to MAX.



Update the “DESCRIPTION” if not present using the “EU” (Edit Update) command).

You will have to scroll forward to see this attribute.

If omitted, the “CIDB” command will fail. Pressing <F1> will provide a descriptive error message.



The “CIDB” command which stands for “Check-In DataBase” initiates the process to create the DBDT record.



Slide illustrates PDS location where copybook member is temporarily saved. The group will be “BMPX” if you are using the production version of ARz/OS. This presentation was constructed using the test version.

As this process continues and adds the element to Endevor, the PDS will be:

TestCADSS.SH.BMPX.AD.CPYSRC

ProdCADSS.SH.BMPX.CPYSRC



Review how the DBDT structure looks. Again, you should have an idea of which table columns should be present and their associated attributes. If you see one or more errors, use <F3> to cancel operation and then make corrections before reattempting the operation.



If satisfied with the output, enter the “GO” command and press <ENTER>.



If the structure has one or more elements not in approved status (APPRV), you will see a panel showing the fields and their status and version.

Note, this is from a different table containing columns not representing elements in the “APPRV” status.



You may browse the copybook from the COPYBOOK entity.



DBDT copybook depicted in the PDS used for compiles. Again note, in production, “AD” will not be in the dataset name.



DBDT copybook depicted in Endevor illustrating type, environment, system and subsystem.



Copybook master information is displayed in Endevor.



• These type of copybooks are created in Endevor preferably using the QuickEdit facility.

• They first must be registered in ARz/OS by adding to the COPYBOOK entity.

• They represent either BMS symbolic maps or Vendor supplied copybooks.

• If the copybook is a BMS symbolic map, then the correct name should be used and the BMS map should exist.

• The name should be: – ssDSnnn1

• ss 2 character subsystem code• DS constant• nnn three digit number• 1 constant

• The BMS map that should exist will have a name the same as the symbolic map except minus

the third character “D”.

5. Creating Non-Generated Copybooks

TOC



• For example, if the symbolic map is ‘TIDS3101”, the BMS map will be “TIS3101” and also:

– be the member name in the source library C<LCP><SYS>SH.BMPX.CMPLSRC(TIS3101)

– value of the DFHMSD macro in the source code:

TIS3101 DFHMSD TYPE=&SYSPARM, X LANG=COBOL, X MODE=INOUT, X TERM=3270-2, X CTRL=FREEKB, X DATA=FIELD, X CURSLOC=YES, X STORAGE=AUTO, X



• The exception is if the copybook represents a BMS symbolic map and its BMS map is already defined in Endevor. That means the naming conventions have been followed as outlined on the previous slide. Then when the copybook is added to Endevor, it is automatically approved.

• The table on the next slide illustrates various conditions and what dataset the copybook is added to and what the various flags will be in ARz/OS.

• Vendor copybooks will always be added to ARz/OS with the NON-GENR APPROVED FLAG set to “N”. This requires a Data Modeler to approve the copybook and then the Endevor GENERATE facility must be done again.

• Only the copybook is added to ARz/OS; none of the elements will be added.



--------------------- BEFORE --------------- -------------- AFTER ---------------AR/zos Endevor AR/zos

BMS Type In Non-Genr ARz/OS Job Non-Genrin Endevor ARz/OS ? Approved Flag Dataset Name Max CC Approved Flag

No No N/A COPYSHR 12 N

Yes No N/A CPYSRC 0 Y

No Yes Y CPYSRC 0 Y

N/A No N/A COPYSHR 12 N

N/A Yes Y CPYSRC 0 Y

Yes for “Symbolic Map” means that the map follows the naming convention for a symbolic map.

BEFORE indicates status prior to add or generate in Endevor, AFTER indicates status after the Endevor job has run.

The dataset name is only the last node. It will be either CAD<ss>.SH.BMPX.COPYSHR or CADSS.SH.BMPX.CPYSRC. If the member is in CPYSRC, it will also be in COPYSHR.



If your non-generated copybook is a BMS symbolic map, verify that the BMS exists in Endevor first. That way, as long as the proper naming conventions are followed, your copybook will automatically be approved when it is added to ARz/OS.



Register the copybook in ARz/OS by entering the information as depicted to the left.

The “DESCRIPTION” and “PROGRAMMING LANGUAGE” attributes are required.

You will not be able to set the “ENDEVOR ELEMENT TYPE”.When you create the copybook in Endevor, this field will be updated to “NGCPY” from “CPY”.



Use the “CR” command and complete the Endevor location attributes as indicated to the left. You will also want to specify a CCID and a comment.



If the copybook has not been registered in AR/zOS, you can not create it in Endevor.



Rather than type your BMS symbolic map from scratch, either copy in an architecture shell member or another from your system and subsystem.

The example illustrates an architecture shell member.



The member after being copied in.



To change the field prefix, use the “CHANGE ALL” command.



Command is used again.



Generally, the lines you will be modifying are between the header and the footer or the “SCRN-INPUT”.



When you exit from making changes, a batch job will be submitted to add your element to Endevor.



Output in SDSF indicates a successful operation.



Because the BMS map existed in Endevor prior to creating the symbolic map, the process was able to approve the copybook.



Copybook can be browsed in ARz/OS.



Endevor master detail is displayed.

ARzOS CopyBook

Documents

Transcript of ARzOS CopyBook