Setting Up ELIB Data Sets

How to organize
Endevor
base, delta, and listing libraries as Endevor LIB (ELIB) data sets
ce18-18-0-11
This article explains how to organize
Endevor
base, delta, and listing libraries as Endevor LIB (ELIB) data sets.
Data Sets
An Endevor LIB (ELIB) is a high-performance alternative to OS partitioned data sets under
Endevor
. You can organize
Endevor
base, delta, and listing libraries as ELIB data sets. Three concepts are important when working with ELIBs. These concepts are page size, record format, and target directory page.
  • Page size
    Specifies the size of the control interval used by ELIB for storage. All blocking is internal to ELIB and not available to operating system utilities. You cannot reblock an ELIB data set. If reblocking is necessary, reallocate the data set and copy members into it.
  • Record format
    ELIB data sets store members in compressed format with the record length stored at the front of each record. This format allows members of different record lengths to be stored in one ELIB data set.
  • Target directory pages
    ELIB locates members by going directly to one of its directory pages. If enough directory pages are allocated to avoid overflow, performance is enhanced.
    ELIB data sets allow you to allocate more directory pages spontaneously, using the BC1PNLIB utility.
Endevor
provides three utilities for use when setting up and maintaining ELIB data sets. The following lists these utilities and the purpose of each:
  • BC1PNLIB
    Set up, maintain, and print information about ELIB data sets.
  • BC1PNLST
    Print information about ELIB data sets.
  • BC1PNCPY
    Copy library members from and to ELIB data sets, and to copy members from and to any
    Endevor
    library format.
The ELIB utilities BC1PNLIB, BC1PNCPY, and BC1PNLST cannot be executed within an
Endevor
processor.
BC1PNLIB Utility
This utility lets you set up and maintain the ELIB data sets. It also lets you perform five actions against ELIB data sets:
A Sample JCL to execute the BC1PNLIB ELIB utility is provided with the
Endevor
installation files as member BC1JNLIB in the installation JCL library.
  • Initialize the space allocated to ELIB data sets.
  • Expand existing ELIB data sets.
  • Adjust space allocation in existing ELIB data sets.
  • Reorganize ELIB directories.
  • Print information about an ELIB data set, including:
    • Data set header information
    • Target directory page information
    • Data set member information
    • Data set analysis information
Initialize Function
This function of the BC1PNLIB utility initializes an ELIB data set. Space must have been allocated for the library. The syntax for the INITIALIZE function of the BC1PNLIB utility is shown next:
►►──INItialize──DDName──┬───┬──ddname─────────────────────────────────────────► └─=─┘ ►──¤──┬─────────────────────────────┬──¤──────────────────────────────────────► ├─DSName──┬───┬──dsname───────┤ │ └─=─┘ │ ├─TYPe──=──┬─VSAM─┬───────────┤ │ └─BDAM─┘ │ └─PAGe SIZe──┬───┬──page-size─┘ └─=─┘ ►──ALLocate PAGe──┬───┬──(#-primary-page,#-secondary-page)────────────────────► └─=─┘ ►──¤──┬─────────────────────────────────────────┬──¤──.──────────────────────►◄ ├─REServe PAGe──┬───┬──#-reserve-page─────┤ │ └─=─┘ │ ├─DIRectory PAGe──┬───┬──#-directory-page─┤ │ └─=─┘ │ └─DEStroy TO REUse────────────────────────┘
The following is a list of keywords used in the INITIALIZE syntax:
  • INITIALIZE
    Indicates that you want the BC1PNLIB utility to initialize an ELIB data set. You must have allocated space for this data set.
  • DDNAME
    The DDname of the data set you want to initialize.
  • DSNAME
    (Optional) Data set name for this ELIB data set. If you code the DSNAME statement, the system validates the DSname in this statement against the DSname in the JCL.
  • TYPE
    (Optional) Indicates whether this ELIB is a VSAM cluster or a BDAM data set. If you do not code a TYPE statement, the BC1PNLIB utility reads this information from the JCL.
  • PAGE SIZE
    (Optional) If you are using VSAM clusters, page size is system-defined by the IDCAMS utility as eight bytes less than the control interval size.
    If you are using BDAM data sets, page size equals block size. Block size is specified in the JCL. If you also code a PAGE SIZE statement, the system validates it against the block size you have specified in the JCL.
    If you code a PAGE SIZE statement, the entry can have up to six numeric characters.
  • ALLOCATE PAGES
    Determines number of pages in this ELIB data set. You can specify two numbers:
    • #-primary-pages
      Indicates the number of pages initialized as primary storage for this ELIB data set.
    • #-secondary-pages
      Indicates number of pages initialized as secondary storage during each automatic expansion of the ELIB data set.
    If you do not want to assign a secondary allocation quantity, do not specify secondary pages.
    The primary and the secondary entries can be up to six numeric characters.
  • RESERVE PAGES
    (Optional) Determines when the system allocates a secondary storage block to this ELIB data set. Expressed as a number of pages (up to six numeric characters). When this number of pages remain unused within the current storage allocation,
    Endevor
    automatically attempts to allocate a secondary storage block.
    • If you assign a RESERVE PAGES value, assign a value that is greater than the number of pages you expect the largest data set member to take up. Very often, assigning a value equal to one cylinder of storage is adequate.
    • If you omit this clause, the reserve threshold defaults to 1/16 of the number of pages allocated to primary storage. For example, if the primary allocation is 400, the reserve threshold defaults to 25 (400/16).
    • If you assign a value of 0, ELIB will not automatically expand. In this situation, once the primary allocation is filled any attempts to store a new member fails until you manually expand the library.
    If ELIB tries to expand the library and runs out of space, it automatically sets the reserve threshold value to zero.
  • DIRECTORY PAGES
    (Optional) Number of target directory pages. The default allocation is 7 pages.
    If you want to allocate a different number of target directory pages, enter that number (must be greater than 7) in this statement. This can be up to six numeric characters with a maximum value of 32500. If you specify less than 7, or more than 32500, a warning message will be issued and the number of directory pages will be set to the nearest valid number. This specifically means a limit between 7 or 32500.
    When estimating the number of target directory pages bear in mind that:
    • Each directory member requires 84 bytes.
    • Each directory page has 32 bytes reserved.
    This means that if your page size is 4096 bytes, a target directory page could hold [(4096-32)/84] = 48 members.
    If a member is added and the directory page is full, the page overflows, eventually degrading performance. To avoid overflow, allocate target directory pages so that member directory information fills less than 50 percent of the available target directory page space.
    Example
    : Your target directory page size is 4096 bytes, and you want to store directory information for approximately 24 members per page (half of the maximum of 48 members). If you estimate that 1,000 members will reside in the data set, allocate the data set with 1,000/24 = 42 target directory pages.
    If you omit this clause, the BC1PNLIB utility automatically calculates the number of pages within the ELIB data set needed for its directory. It does this step by allocating enough target directory pages to support one member per each four pages of the primary allocation.
  • DESTROY TO REUSE
    (Optional) Code this statement only if you are re-initializing an ELIB data set.
If you code this statement, all data in the existing data set are lost.
Expand Function
Normally, ELIB expands automatically according to your secondary allocation value. The EXPAND function of the BC1PNLIB utility allows you to expand ELIB data sets manually. The syntax for the EXPAND function of the BC1PNLIB utility is shown next:
►►──EXPand──DDName──┬───┬──ddname─────────────────────────────────────────────► └─=─┘ ►──¤──┬─────────────────────────────────────────┬──¤──.──────────────────────►◄ ├─DSName──┬───┬──dsname───────────────────┤ │ └─=─┘ │ ├─ALLocate PAGe──┬───┬──#-secondary-page──┤ │ └─=─┘ │ └─REServe PAGe──┬───┬───#-reserve-page────┘ └─=─┘
The following describes the keywords used in the syntax for the EXPAND function:
  • EXPAND
    Indicates that you want the BC1PNLIB utility to acquire secondary storage for an ELIB data set.
  • DDNAME
    The DDname of the data set you want to expand.
  • DSNAME
    (Optional) Data set name for this ELIB data set. If you code the DSname statement, the system validates the DSname in this statement against the DSname in the JCL.
  • ALLOCATE PAGES
    (Optional) Determines number of additional pages in the expanded ELIB data set. If you do not code this statement the secondary allocation originally specified during the INITIALIZE function is used.
  • RESERVE PAGES
    (Optional) Lets you respecify the RESERVE threshold established in the INITIALIZE function for this library. If you want to keep the existing RESERVE threshold, do not code this statement.
Adjust Function
The ADJUST function allows you to modify the specifications for secondary storage and the reserve threshold for an ELIB data set. The syntax for the ADJUST function is shown next:
►►──ADJust──DDName──┬───┬──ddname─────────────────────────────────────────────►S └─=─┘ ►──¤──┬─────────────────────────────────────────┬──¤──.──────────────────────►◄ ├─DSName──┬───┬──dsname───────────────────┤ │ └─=─┘ │ ├─ALLocate PAGe──┬───┬──#-secondary-page──┤ │ └─=─┘ │ └─REServe PAGe──┬───┬───#-reserve-page────┘ └─=─┘
The following describes the keywords used in the syntax for the ADJUST function:
  • ADJUST
    Indicates that you want the ADJUST function of the BC1PNLIB utility to adjust the reserve threshold and/or the secondary storage allocation.
  • DDNAME
    The DDname of the data set you want to adjust.
  • DSNAME
    (Optional) Data set name for this ELIB data set. If you code the DSname statement, the system validates the DSname in this statement against the DSname in the JCL.
  • ALLOCATE PAGES
    (Optional) Determines number of pages to be allocated in subsequent secondary allocations.
  • RESERVE PAGES
    (Optional) Allows you to respecify the RESERVE threshold established in the INITIALIZE function for this library. If you want to keep the existing RESERVE threshold, do not code this statement.
When using the ADJUST function, you may code the ALLOCATE PAGES statement or the RESERVE PAGES statement, or both statements.
Reorganize Function
The reorganize (REORG) function of the BC1PNLIB utility allows you to reorganize ELIB data sets. During this process, you can respecify the number of pages allocated to the data set directory. The system re-allocates storage for the directory according to this specification, and rewrites the directory entries. The syntax for the REORG function of the BC1PNLIB utility is shown next:
►►──REOrg──DDName──┬───┬──ddname─────────────────────────────────────────────► └─=─┘ ►──¤──┬──────────────────────────────────────────┬──¤──.────────────────────►◄ ├─DSName──┬───┬──dsname────────────────────┤ │ └─=─┘ │ └─DIRectory PAGe──┬───┬──#-directory-page──┘ └─=─┘
The following describes the keywords used in the syntax for the REORG function:
  • REORG
    Indicates that you want the REORG function of the BC1PNLIB utility to respecify the number of pages allocated to the directory of an ELIB data set.
  • DDNAME
    The DDname of the data set you want to reorganize.
  • DSNAME
    (Optional) Data set name for this ELIB data set. If you code the DSname statement, the system validates the DSname in this statement against the DSname in the JCL.
  • DIRECTORY PAGES
    Indicates the number of pages you want to allocate for the directory of the ELIB data set specified by the DDname. This can be up to six numeric characters with a maximum value of 32500. If you specify less than 7, or more than 32500, a warning message will be issued and the number of directory pages will be set to the nearest valid number. This specifically means a limit between 7 or 32500.
Inquire Function
The INQUIRE function of the BC1PNLIB utility allows you to print summary statistics about the library directory and/or individual members, and also allows you to check the integrity of the library. The following syntax is for the INQUIRE function of the BC1PNLIB utility:
►►──INQuire──DDName──┬───┬──ddname──┬───────────────────────────────┬───────────► └─=─┘ └──OPTion──¤──┬───────────┬──¤──┘ ├─DIRectory─┤ ├─ANAlyze───┤ └─MEMber────┘ ►──.───────────────────────────────────────────────────────────────────────────►◄
The following describes the keywords used in the syntax for the INQUIRE function:
  • INQUIRE
    Indicates that you want to use the INQUIRE function of the BC1PNLIB utility.
  • DDNAME
    (Required) The DDname of the data sets for which you want to print information.
  • OPTION
    (Optional) Allows you to specify more reporting options. You can use any or all options whenever you run the INQUIRE function of the BC1PNLIB utility. If you omit this clause,
    Endevor
    prints only data set header information.
    • DIRECTORY--Tells
      Endevor
      to print information about target directory page utilization.
    • MEMBERS--Tells
      Endevor
      to print footprint information plus member size in pages, records, and bytes.
    • ANALYZE--Tells
      Endevor
      to print an analysis of data set integrity.
BC1PNLST Utility
This utility lets you inquire against directories and/or members of an ELIB data set. This utility provides read-only access to ELIB data sets.
A Sample JCL to execute the BC1PNLST ELIB utility is provided with the
Endevor
installation files as member BC1JNLST in the installation JCL library.
The following is the BC1PNLST syntax:
►►──INQuire──DDName──┬───┬──ddname──┬───────────────────────────────┬───────────► └─=─┘ └──OPTion──¤──┬───────────┬──¤──┘ ├─DIRectory─┤ └─MEMber────┘ ►──.───────────────────────────────────────────────────────────────────────────►◄
The following keywords in the INQUIRE request allow you to specify options that provide more detailed output. Code any or all of the options that you want to use.
  • INQUIRE
    Indicates that you want to use the INQUIRE function of the BC1PNLST utility to retrieve information about an ELIB data set.
  • DDNAME
    The DDname of the data sets you want to inquire against.
  • OPTION
    (Optional) Lets you specify more reporting options. You can use any or all of these options whenever you run the INQUIRE function of the BC1PNLST utility. If you do not want more detail, you can omit this clause entirely; only summary library information is printed.
    • DIRECTORY
      The DIRECTORY option displays the number of members for each directory page, and summary directory usage statistics.
    • MEMBERS
      The MEMBERS option lists each member of the library, with full
      Endevor
      footprint information plus member size in pages, records, and bytes.
BC1PNCPY Utility
This utility lets you copy between any
Endevor
supported library types, while preserving the original
Endevor
footprint of copied members. You can use this utility to copy all or selected members of an existing base, delta, or listing library from a PDS or PDS/E to an ELIB or the reverse. A Sample JCL to execute the BC1PNCPY ELIB utility is provided with the
Endevor
installation files as member BC1JNCPY in the installation JCL library.
For large libraries, BC1PNCPY takes a great deal of time to run. It requires exclusive control of the input and output libraries, for integrity.
When an element name is longer than eight characters and you copy to a PDS or PDS/E, the element name is truncated at eight characters. When truncation occurs, different input members can truncate to the same input name.
If the UPDATE IF PRESENT
option is specified
, the last duplicate member overwrites all prior duplicates. If the UPDATE IF PRESENT
option is not specified
, only the first encountered duplicate member is overwritten. Any subsequent duplicate member names does not overwrite the first duplicate member.
The following is the BC1PNCPY syntax:
►►──COPy──INPut──┬──FILe──┬───┬──filename──┬─────────────────────────────────────────► │ └─=─┘ │ └──DDName──┬───┬──ddname──┘ └─=─┘ ►──¤──┬───────────────────────┬──¤───────────────────────────────────────────────────► ├─UNPacked──────────────┤ └─DSName──┬───┬──dsname─┘ └─=─┘ ►──OUTput──┬─FILe──┬───┬──filename─┬─────────────────────────────────────────────────► │ └─=─┘ │ └─DDName──┬───┬──ddname─┘ └─=─┘ ►──¤──┬──────────────────────────────────────────┬──¤────────────────────────────────► ├─UNPacked─────────────────────────────────┤ ├─DSName──┬───┬──dsname────────────────────┤ │ └─=─┘ │ └─UPDate──┬────┬──┬───────────┬────────────┘ └─IF─┘ └──PREsent──┘ ►──┬──────────────────────────────────────────────────────────┬──.──────────────────►◄ │ ┌──────────────────────────────────────────────────────┐ │ └─▼─MEMber──┬───┬──membername-1──┬─────────────────────┬─┴─┘ └─=─┘ └─THRu──membername-x──┘
The following keywords in the COPY request let you specify options that provide more detailed output. Code any or all options that you want to use.
  • COPY
    Indicates that you want to use the BC1PNCPY utility.
  • INPUT FILE \ DDNAME
    Identifies the source file or DDname.
  • UNPACKED
    (Optional) The UNPACKED option is used with PDS or PDS/Es only, and only if a PDS or PDS/E is not an
    Endevor
    compressed library. When you use this option with the INPUT statement BC1PNCPY does not attempt to decompress the members being read from the input data set.
  • DSNAME
    (Optional) If you use the DSNAME option, the data set name of the input library is validated against the DDNAME in the JCL. If the DSN contains periods, it must be enclosed in single quotes.
  • OUTPUT FILE \ DDNAME
    Identifies the target file or DDname.
  • UNPACKED
    (Optional) The UNPACKED option is used with PDS or PDS/Es only, and only if a PDS or PDS/E is not an
    Endevor
    compressed library. When you use this option with the OUTPUT statement, BC1PNCPY does not attempt to compress the members being written to the output data set.
  • DSNAME
    (Optional) If you use the DSNAME option, the data set name of the target library is validated against the DDNAME in the JCL. If the DSN contains periods, it must be enclosed in single quotes.
  • UPDATE IF PRESENT
    (Optional) Use this option to update (replace) members with the same name within the target library. If you do not use this option, the utility does not replace members of the same name.
  • MEMBER ...[THRU ...]
    The MEMBER clauses limits the COPY request to specific members only. You can specify a single member or a range of members (using the THRU clause). When entering MEMBER and THRU clauses, you can use the standard
    Endevor
    wildcard capability.
    A period must be coded at the end of each complete statement. If you specify any MEMBER [THRU] clauses, enter the period after the last of those clauses. If you specify more than one MEMBER [THRU] clause, do
    not
    code a comma between the clauses.
    By default BC1PNCPY's parser stack supports 1000 MEMBER= statements. If more than 1000 statements are needed, the parameter MEMBERS can be passed to the utility using the PARM= field on the EXEC statement:
    //JS10 EXEC PGM=NDVRC1,PARM='BC1PNCPYMEMBERS=nnnnnn'
    Where nnnnnn is a 1 to 6 digit number specifying the approximate number of MEMBER= statements coded. When present, the parser stack is increased to 'nnnnnn' entries. If the specified value is 1000 or less, the default value of 1000 is used.
    Specifying this parameter may increase the storage requirements for the step. Approximately 40 bytes per member is needed. Specify an appropriate REGION size to accommodate the requests.
How to Allocate and Initialize an ELIB Data Set
Allocate and initialize an ELIB set before it can be used. To allocate and initialize a data set, proceed as follows:
  1. Select an access method: BDAM or VSAM.
  2. Estimate space requirements for the data set.
  3. Allocate the appropriate data set (BDAM data set or VSAM cluster), then initialize the data set with the ELIB utility program
    BC1PNLIB
    .
Select an Access Method for ELIB Data Sets
Decide what physical format you want to use for the ELIB data sets (VSAM or BDAM). Your choice of access method depends on your site preferences. The following list describes the features of VSAM and BDAM access methods:
  • VSAM provides better performance by exploiting 31-bit storage and better data set protection mechanisms. VSAM also supports spanned volumes
  • BDAM provides slightly better performance and simpler installation and de-installation, but spanned volumes are not supported.
Estimate Space Requirements for ELIB Data Sets
Space requirements are a function of the number of members in your libraries, their size and volatility. Listed next are suggestions for estimating the size of base, delta and listings libraries. These suggestions assume an established collection of code. If you are expecting a great deal of growth within your systems, you may want to consider larger growth factors.
  • For an ELIB base library, figure out how many members are in the library, and how much space they take up in the data set after the data set has been compressed. Then add 20 percent to this figure, for expansion.
  • For an ELIB delta library, estimate approximately half the size of the corresponding base library. If you are an existing
    Endevor
    user, you may want to use a larger percentage, to accommodate for the growth of your delta libraries over time.
  • For an ELIB listing library, estimate 80% of the space required for the corresponding members in a PDS or PDS/E (measured after the PDS has been compressed).
You can use the ISPF "3.2" utility to examine space used by a PDS or PDS/E.
If you estimate space requirements that are too low, ELIB lets you increase the library size without reorganizing.
How to Allocate and Initialize the Data Set
Once you select an access method and estimate space requirements, allocate a BDAM data set or a VSAM cluster. See the following JCL examples when you are ready to allocate data sets.
Allocate and Initialize a BDAM ELIB Data Set
To allocate a BDAM ELIB data set, use a JCL stream similar to the following sample:
//ALLOCBDAM EXEC PGM=IEFBR14 //LIBRARY DD DSN=
ELIB.DATASET
,DISP=(NEW,CATLG), // UNIT=PDASD,SPACE=(CYL,(
5
,
2
)), // DCB=(DSORG=DA,BLKSIZE=
4096
,LRECL=
4096
,RECFM=FBS)
In this example, the IEFBR14 utility allocates five cylinders to primary storage and 2 cylinders to secondary storage. The LRECL and BLKSIZE for this BDAM ELIB data set are 4096 bytes.
To initialize this data set as an ELIB data set, convert your estimated space requirements to their page equivalents. This step is necessary because the BC1PNLIB utility needs all its specifications in pages.
In BDAM data sets, the BLKSIZE is the same as the page size. The number of 4096-byte pages per track and per cylinder varies by DASD device, as shown in the following table:
Device
Page size
Pages per track
Pages per cylinder
3380
4096
10
150
3390
4096
12
180
The BDAM data set in this example would therefore have a capacity of 750 pages in primary storage and 300 pages in secondary storage when using a 3380 device, and 900 pages in primary storage and 360 pages in secondary storage when using a 3390 device.
Use the BC1PNLIB utility to initialize the data set. The following JCL assumes that you are using a 3380 device.
//ELIBINIT EXEC PGM=BC1PNLIB //STEPLIB DD DISP=SHR,DSN=iprfx.iqual.CSIQAUTU // DD DISP=SHR,DSN=iprfx.iqual.CSIQLOAD //* //* OMIT THE FOLLOWING DCB INFORMATION IF VSAM //* //BDAMINIT DD DSN=
BDAM.DATASET
, // DCB=(DSORG=DA,BLKSIZE=
4096
,LRECL=
4096
,RECFM=FBS), // DISP=(OLD,KEEP) //SYSPRINT DD SYSOUT=* //BSTERR DD SYSOUT=* //SYSUDUMP DD SYSOUT=* //SYSIN DD * INIT DDNAME =
BDAMINIT
PAGE SIZE = 4096
ALLOCATE = (750
,
300
) RESERVE PAGES =
150
DIRECTORY PAGES = 14
.
INQUIRE DDNAME =
BDAMINIT
.
/*
In the previous example, you have allocated and initialized a BDAM data set as an ELIB data set with 750 pages initialized as primary storage. When 150 pages remain in this primary storage area,
Endevor
automatically attempts to allocate and initialize secondary storage with a capacity of 300 pages. In addition, you have requested the BC1PNLIB utility to list statistical information about this data set after initialization.
Allocate and Initialize a VSAM ELIB Data Set
The ELIB data set format supports z/OS VSAM extended addressability for VSAM data sets. The extended addressability feature lets you allocate VSAM data sets that are larger than 4 GB. If extended addressability is enabled in z/OS for any of your VSAM ELIB data sets,
Endevor
recognizes that this option is enabled and handles ELIB access appropriately. You do not need any changes in
Endevor
to enable support for extended addressability. Ask your Storage Administrator to determine whether z/OS VSAM extended addressability is available for your site and how you can implement it.
To allocate a VSAM cluster, use the IBM IDCAMS utility in a JCL stream similar to the following sample:
//ALOCVSAM EXEC PGM=IDCAMS //SYSPRINT DD SYSOUT=* //SYSIN DD * DEFINE CLUSTER - (NAME(
VSAM.DATASET
) - MASTERPW(
plant
) - CONTROLPW(ENDEVOR) - UPDATEPW(ENDEVOR) - RECORDSIZE(
4088
4088
) - CONTROLINTERVALSIZE(
4096
) - SHAREOPTIONS(3,3) - VOLUMES(
BST001
) - CYLINDERS(
5
,
2
) - NONINDEXED - ) - DATA (NAME(
VSAM.DATASET
.DATA) - MASTERPW(
plant
) - CONTROLPW(ENDEVOR) - UPDATEPW(ENDEVOR) - )
In this example, the IDCAMS utility defines a VSAM cluster named
VSAM.DATASET
. The control interval for this data set is
4096
bytes, and the record size is
4088
bytes. In VSAM data sets the record size is the same as the page size. IDCAMS allocates
5
cylinders of primary storage, and
2
cylinders to secondary storage for the data set. The data set resides in a DASD volume with a serial number of
BST001
. The master password to the data set is
plant
.
Choose a master password to protect your data. This password is required whenever you want to delete or rename the cluster.
Endevor
processing uses the built-in password
ENDEVOR
for all update processing. If you omit the master password, this library is unprotected.
Before initializing this data set as an ELIB data set, convert your estimated space requirements to their page equivalents. This step is necessary because the BC1PNLIB utility needs all its specifications in pages.
In VSAM data sets, the page size is eight bytes smaller than the control interval size, in this case 4088 bytes. The number of 4088 byte pages per track and per cylinder varies by DASD device, as shown in the following table:
Device
Page size
Pages per track
Pages per cylinder
3380
4088
10
150
3390
4088
12
180
The VSAM data set in this example would therefore have a capacity of 750 pages in primary storage and 300 pages in secondary storage when using a 3380 device, and 900 pages in primary storage and 360 pages in secondary storage when using a 3390 device.
If you are using VSAM, specify one less page than fits in the primary space allocation. VSAM uses one control interval for an end-of-file mark. For example, on a 3380 device with one cylinder of primary space allocation, specify 149 pages per cylinder.
Use the BC1PNLIB utility to initialize the data set. The following JCL assumes that you are using a 3380 device.
//ELIBINIT EXEC PGM=BC1PNLIB //STEPLIB DD DISP=SHR,DSN=iprfx.iqual.CSIQAUTU // DD DISP=SHR,DSN=iprfx.iqual.CSIQLOAD //* //* //* //INITVSAM DD // DSN=
VSAM.DATASET
,DISP=(OLD,KEEP) //SYSPRINT DD SYSOUT=* //BSTERR DD SYSOUT=* //SYSUDUMP DD SYSOUT=* //SYSIN DD * INIT DDNAME =
INITVSAM
PAGE SIZE = 4088
ALLOCATE = (749
,
300
) RESERVE PAGES =
150
DIRECTORY PAGES = 14
.
INQUIRE DDNAME =
INITVSAM
.
/*
In this example, you have allocated and initialized a VSAM data set as an ELIB data set with 749 pages initialized as primary storage. When 150 pages remain in this primary storage area,
Endevor
automatically attempts to allocate and initialize secondary storage with a capacity of 300 pages. In addition you have requested the BC1PNLIB utility to list statistical information about this data set after it has been initialized.
Reinitialize an ELIB Data Set
  1. Delete and reallocate the library
  2. Rerun the initialization procedure, with the following more clause: DESTROY TO REUSE.
    If you use this clause, any data currently in the library is destroyed. Use this option with caution.
How to Expand ELIB Data Sets
Typically, ELIB data sets expand automatically according to your secondary allocation value. However, if you specify a reserve threshold of 0 (reserve pages=0) when you initialize the ELIB data set, automatic expansion cannot occur. In this case,  run the BC1PNLIB utility to force expansion of the data set into a secondary allocation.
The following example shows a sample JCL and the control statements that you can use to accomplish this task:
//EXPAND EXEC PGM=BC1PNLIB //STEPLIB DD DISP=SHR,DSN=iprfx.iqual.CSIQAUTU // DD DISP=SHR,DSN=iprfx.iqual.CSIQLOAD //
INITVSAM
DD DSN=
VSAM.DATASET
, // DISP=(SHR,KEEP) //SYSPRINT DD SYSOUT=* //BSTERR DD SYSOUT=* //SYSUDUMP DD SYSOUT=* //SYSIN DD *
EXPAND
DDNAME =
INITVSAM
ALLOCATE PAGES = 300
.
INQUIRE DDNAME =
INITVSAM
.
/*
In this example, you have specified a secondary storage allocation of 300 pages. This causes two cylinders of secondary storage to be allocated and initialized for this data set. You have also requested a listing of statistical information about this expanded data set, using the INQUIRE facility.
How to Adjust ELIB Data Sets
You can change the primary, secondary, and reserve threshold space allocations for an ELIB data set by using the ADJUST function of the BC1PNLIB utility.
You can use the ADJUST function to do the following tasks:
  • Adjust the secondary storage allocation after expanding an ELIB data set, so that subsequent expansions allocate a different amount of space.
  • Adjust the reserve threshold so that additional space is allocated based on a different threshold of unused space.
  • Reset the reserve threshold after
    Endevor
    resets the reserve threshold value to zero. It does this after attempting to expand a data set and, failing to do so, to prevent repeated failures. If this situation occurs, follow these procedures:
  • Copy the data set to a larger DASD allocation.
    • Adjust the reserve threshold value (that is, the threshold at which ELIB expands to a new extent) for future expansions.
    • You might also want to adjust the secondary allocation quantity assigned during initialization.
The following example shows a sample JCL and the control statements that you can use to adjust an ELIB data set:
//ADJUST EXEC PGM=BC1PNLIB //STEPLIB DD DISP=SHR,DSN=iprfx.iqual.CSIQAUTU // DD DISP=SHR,DSN=iprfx.iqual.CSIQLOAD //INITVSAM DD DSN=
VSAM.DATASET
, // DISP=(SHR,KEEP) //SYSPRINT DD SYSOUT=* //BSTERR DD SYSOUT=* //SYSUDUMP DD SYSOUT=* //SYSIN DD * ADJUST DDNAME=
INITVSAM
ALLOCATE PAGES = 600
RESERVE PAGES = 300
.
INQUIRE DDNAME=
INITVSAM
.
/*
In this example, a secondary storage allocation of 600 pages was specified, and a reserve threshold of 300 pages. This allocation changes the original specifications for the ELIB data set INITVSAM. After this code is run, subsequent secondary allocations are 600 pages rather than 300 pages, and the threshold of unused space that triggers automatic expansion is 300 pages rather than 150.
You have also requested a listing of statistical information about this expanded data set, using the INQUIRE facility.
How to Reorganize ELIB Directory Pages
If your library has too few directory pages, ELIB data sets allocate new pages as needed, but in discontinuous storage. This step can slightly degrade performance. To alleviate this problem, use the ELIB utility
BC1PNLIB
to reorganize the directory with a larger number of pages. BC1PNLIB can also be used to reduce the number of directory pages in the library to prevent wasting space.
ELIB locks the library during the reorganization procedure, but this process is usually brief.
The reorganization process is memory-intensive. Therefore, give the utility a region large enough to avoid multiple passes against the directory.
To reorganize a directory, use JCL and control statements similar to the following sample:
//REORG EXEC PGM=BC1PNLIB //STEPLIB DD DISP=SHR,DSN=iprfx.iqual.CSIQAUTU // DD DISP=SHR,DSN=iprfx.iqual.CSIQLOAD //INITVSAM DD DSN=
VSAM.DATASET
, // DISP=(SHR,KEEP) //SYSPRINT DD SYSOUT=* //BSTERR DD SYSOUT=* //SYSUDUMP DD SYSOUT=* //SYSIN DD * REORG DDNAME=
INITVSAM
DIRECTORY PAGES = 20
.
INQUIRE DDNAME=
INITVSAM
.
/*
In this example, the number of target directory pages allocated to the ELIB data set was reset to 20.
How to Print ELIB Data Set Information
The ELIB utility includes an INQUIRY function that allows you to retrieve statistical information about ELIB data sets. This function is included in two utilities, BC1PNLIB and BC1PNLST
  • The BC1PNLIB utility allows you to print header information for ELIB data sets, information about members and/or target directory pages, and to analyze the integrity of the data set.
  • The BC1PNLST utility allows you to perform all functions except for data set integrity analysis.
How to Print Data Set Header Information
You can code the INQUIRY statement with no further specification in the BC1PNLIB and the BC1PNLST utilities. In both instances, the system prints header information for the ELIB data sets that you specify, and a bit map of space utilization for the data set.
To use the INQUIRY function to print header information, use JCL similar to the following sample:
//INQUIRE EXEC PGM=BC1PNLST //STEPLIB DD DISP=SHR,DSN=iprfx.iqual.CSIQAUTU DD DISP=SHR,DSN=iprfx.iqual.CSIQLOAD //ELIB DD DSN=
ELIB.DATASET
, // DISP=(SHR,KEEP) //SYSPRINT DD SYSOUT=* //BSTERR DD SYSOUT=* //SYSUDUMP DD SYSOUT=* //SYSIN DD * INQUIRE DDNAME=
ELIB
.
/*
How to Print Member Information
You can code the INQUIRY statement with the MEMBER option in the BC1PNLIB or the BC1PNLST utility. In both instances, the system generates reports listing information about the members in the ELIB data sets that you specify.
To print member information, use JCL similar to the following sample:
//INQUIRE EXEC PGM=BC1PNLST //STEPLIB DD DISP=SHR,DSN=iprfx.iqual.CSIQAUTU DD DISP=SHR,DSN=iprfx.iqual.CSIQLOAD //ELIB DD DSN=
ELIB.DATASET
, // DISP=(SHR,KEEP) //SYSPRINT DD SYSOUT=* //BSTERR DD SYSOUT=* //SYSUDUMP DD SYSOUT=* //SYSIN DD * INQUIRE DDNAME=
ELIB
OPTION
MEMBERS
.
/*
How to Print Target Directory Page Information
You can code the INQUIRY statement with the DIRECTORY option in the BC1PNLIB or the BC1PNLST utility. In both instances, the system generates reports listing information about the directories in the ELIB data sets that you specify.
To use the INQUIRY function to retrieve directory information, use JCL and control statements similar to the following sample:
//INQUIRE EXEC PGM=BC1PNLST //STEPLIB DD DISP=SHR,DSN=iprfx.iqual.CSIQAUTU DD DISP=SHR,DSN=iprfx.iqual.CSIQLOAD //ELIB DD DSN=
ELIB.DATASET
, // DISP=(SHR,KEEP) //SYSPRINT DD SYSOUT=* //BSTERR DD SYSOUT=* //SYSUDUMP DD SYSOUT=* //SYSIN DD * INQUIRE DDNAME=
ELIB
OPTION
DIRECTORY
.
/*
How to Print Data Set Analysis Information
You can code the INQUIRY statement with the ANALYZE option only in the BC1PNLIB utility. Use the ANALYZE option to validate the integrity of specified ELIB data sets. The analysis verifies the integrity of each member in the directories and ensures that the allocation bit map is valid. Damaged members, if any, are identified, as are misallocated pages. The ANALYZE function must run in dedicated mode, and locks the library while sweeping it.
To verify the integrity of an ELIB library, use JCL and control statements similar to the following sample
//ANALYZE EXEC PGM=BC1PNLIB //STEPLIB DD DISP=SHR,DSN=iprfx.iqual.CSIQAUTU // DD DISP=SHR,DSN=iprfx.iqual.CSIQLOAD //ELIB DD DSN=
ELIB.DATASET
, // DISP=(SHR,KEEP) //SYSPRINT DD SYSOUT=* //BSTERR DD SYSOUT=* //SYSUDUMP DD SYSOUT=* //SYSIN DD * INQUIRE DDNAME=
ELIB
OPTION
ANALYZE
.
/*
The report produced by the analyze function can contain the following messages:
  • *** ORPHAN: MEMBER= PAGE= NEXT= PREV= STAMP= BYTES USED=
    The page or range of pages in the message are marked as occupied in the allocation bit map, but are not associated with any members in the data set header, allocation map, or directory pages.
  • *** MEMBER= STAMP= PAGE= FOUND MEMBER= STAMP=
    Part of the member identified in the MEMBER=, STAMP=, and PAGE= fields has been overlaid by the member identified in the FOUND MEMBER= and following STAMP= fields.
  • *** MEMBER= STAMP= LIDPAGES= ACTUAL PAGES=
    The member identified in the MEMBER= and STAMP= fields is listed in the directory as occupying the number of pages in the LIDPAGE= field, but the analysis utility has determined that it actually occupies the number of pages in the ACTUAL PAGES= field.
  • *** PAGE= OF MEMBER= IS FREE. NEXT= PREV= STAMP= BYTES USED=
    The allocation map shows the named page to be free, but the directory associates the same page with the member identified in the MEMBER= and STAMP= fields, and shows that the page contains the number of bytes in the BYTES USED= field. The immediately preceding and subsequent pages in the directory are shown in the PREV= and NEXT= fields. The location of the directory entry with this information is shown in a message like this sample:
    *** E-LIB DIR CHUNK= 1ST PAGE
How to Convert to or from ELIB Format
The ELIB copy utility, BC1PNCPY, allows you to copy members between any
Endevor
supported library types, while preserving the original
Endevor
footprint of copied members. You can use this utility to copy all or selected members of an existing base, delta, or listing library from a PDS or PDS/E to an ELIB data set or the reverse.
For large libraries, BC1PNCPY takes a great deal of time to run. In addition, it requires exclusive control of the input and output libraries, for integrity.
To copy between
Endevor
libraries or from/to an external library, use JCL and control statements similar to the following sample:
//CONVERT EXEC PGM=NDVRC1,PARM='BC1PNCPY' //STEPLIB DD DISP=SHR,DSN=iprfx.iqual.CSIQAUTU // DD DISP=SHR,DSN=iprfx.iqual.CSIQAUTH //CONLIB DD DISP=SHR,DSN=iprfx.iqual.CSIQLOAD //
OLDBASE
DD DSN=
BST.OLD.BASE
, // DISP=(OLD,KEEP) //
NEWELIB
DD DSN=
BST.NEW.BASE
, // DISP=(OLD,KEEP) //SYSPRINT DD SYSOUT=* //BSTERR DD SYSOUT=* //SYSUDUMP DD SYSOUT=* //SYSIN DD * COPY INPUT DDNAME =
OLDBASE
OUTPUT DDNAME =
NEWELIB
.
/*
In this example, the system copies all members from the OLDBASE data set to the NEWELIB data set.