ISPF Library Allocation and Installation: ISR@ Libraries and Panel Library Setup

ISPF libraries are partitioned datasets (PDS) that store ISPF components like panels, messages, skeletons, and other resources. Proper allocation and installation of these libraries is essential for ISPF functionality. This tutorial covers ISR@ system libraries, panel library setup, allocation parameters, and installation procedures. Understanding library allocation is crucial for system administrators and developers who need to set up or customize ISPF environments.

ISPF uses a library concatenation system where multiple libraries are searched in order to find resources. System libraries (ISR@ libraries) contain ISPF system components, while user libraries allow customization and extension. Proper library allocation ensures ISPF can find and load its components correctly, and understanding the allocation process helps troubleshoot library-related issues.

Understanding ISPF Libraries

ISPF libraries are partitioned datasets that store various ISPF components. Each library type serves a specific purpose and has particular requirements.

Types of ISPF Libraries

ISPF uses several types of libraries:

• Panel Libraries: Store ISPF panel definitions (screen layouts). Panels define the user interface for ISPF applications.
• Message Libraries: Store ISPF messages displayed to users. Messages provide feedback, error information, and help text.
• Skeleton Libraries: Store skeleton templates used for generating output. Skeletons are templates with variable substitution.
• Table Libraries: Store ISPF table definitions used for data management and display.
• Help Libraries: Store help text and documentation accessible through ISPF help system.
• Macro Libraries: Store REXX and CLIST macros used for automation and customization.

Each library type has specific requirements, but all share common characteristics: they're partitioned datasets (PDS) with fixed-block records, 80-byte logical record length, and organized for efficient member access.

ISR@ System Libraries

ISR@ libraries are IBM-provided system libraries that contain ISPF system components. The "@" symbol is IBM's naming convention for system-level ISPF resources. Common ISR@ libraries include:

• ISR@PRIM: Primary option menu panels and related system panels
• ISR@PENU: Panel library containing standard ISPF panels
• ISR@MSGS: Message library with ISPF system messages
• ISR@SKEL: Skeleton library with system skeleton templates
• ISR@TBL: Table library with system table definitions
• ISR@HELP: Help library with ISPF help text

These libraries are typically allocated during ISPF installation and are required for ISPF to function. They're usually in system-managed datasets accessible to all users, and system administrators manage their allocation and maintenance.

ISR@ libraries are searched first in the library concatenation, providing default ISPF functionality. User libraries, if configured, are searched after system libraries, allowing users to override system resources with custom versions.

User Libraries

User libraries are allocated by individual users or organizations for custom panels, messages, and other resources. User libraries allow:

• Customization: Override system panels or messages with custom versions
• Extension: Add new panels, messages, or resources not in system libraries
• Organization: Organize project-specific or team-specific resources
• Isolation: Keep custom resources separate from system resources

User libraries follow the same allocation requirements as system libraries but are typically in user-specific or project-specific datasets. They're added to library concatenation through ISPF Settings or system configuration.

Allocating ISPF Libraries

Proper allocation of ISPF libraries requires understanding dataset attributes, space requirements, and organizational needs. This section covers allocation parameters and procedures.

Allocation Parameters

ISPF libraries require specific allocation parameters:

• Data Set Organization (DSORG): Must be PO (Partitioned Organization) to support multiple members. PDS format allows storing many panels, messages, or other resources as separate members.
• Record Format (RECFM): Typically FB (Fixed Block) for standard ISPF components. Fixed format ensures consistent record structure and efficient access.
• Logical Record Length (LRECL): Standard is 80 bytes, matching mainframe source code conventions. Some resources may use other lengths, but 80 is the standard.
• Block Size (BLKSIZE): Should be appropriate for the device type. Common values include 27920 for 3390 devices or device-optimal values. Larger block sizes improve I/O efficiency but must fit device constraints.
• Directory Blocks: Number of directory blocks determines how many members the library can contain. Allocate 5-10 directory blocks per expected member as a rule of thumb. Too few directory blocks prevent adding members; too many waste space.
• Space Allocation: Primary and secondary space quantities depend on expected library size. Small libraries might use TRACKS (5-10 primary), while large system libraries may need CYLINDERS (hundreds). Consider growth when allocating space.

These parameters ensure libraries can store ISPF components efficiently and are accessible by ISPF. Incorrect parameters can prevent ISPF from using libraries or cause performance issues.

Allocation Methods

ISPF libraries can be allocated using several methods:

Using ISPF Data Set Utility

ISPF Data Set Utility (Option 3.2) provides a user-friendly interface for allocating libraries:

• Navigate to Option 3.2 (Data Set Utility)
• Enter the dataset name for your library
• Use line command A (Allocate) or type ALLOCATE on the command line
• Specify allocation parameters in the allocation panel
• Confirm allocation

The Data Set Utility guides you through parameter specification and validates inputs, making it suitable for users less familiar with allocation syntax.

Using TSO ALLOCATE Command

TSO ALLOCATE command provides direct allocation with full parameter control:

1
2
3
4
5
ALLOCATE DATASET('USERID.ISPFLIB.PANELS') NEW +
  SPACE(TRACKS,(10,5)) DIR(50) +
  RECFM(F,B) LRECL(80) BLKSIZE(27920) +
  DSORG(PO) VOLUME(volser) +
  UNIT(SYSDA)

This example allocates a panel library with:

• 10 primary tracks, 5 secondary tracks
• 50 directory blocks (sufficient for 250-500 members)
• Fixed block format, 80-byte records, 27920-byte blocks
• Partitioned organization
• Specific volume and unit

TSO ALLOCATE provides precise control but requires understanding allocation syntax and parameters.

Using JCL

For system libraries or automated allocation, JCL can be used:

1
2
3
4
5
6
7
8
9
10
11
//ALLOC    EXEC PGM=IEFBR14
//NEWLIB   DD   DSN=USERID.ISPFLIB.PANELS,
//             DISP=(NEW,CATLG,DELETE),
//             SPACE=(TRACKS,(10,5),RLSE),
//             DCB=(DSORG=PO,
//                  RECFM=FB,
//                  LRECL=80,
//                  BLKSIZE=27920,
//                  DIR=50),
//             UNIT=SYSDA,
//             VOL=SER=volser

JCL allocation is useful for batch allocation, system installation procedures, or when allocation needs to be documented and repeatable.

Space Planning

Proper space planning ensures libraries have adequate capacity:

• Estimate Members: Estimate the number of panels, messages, or other members you'll store. This helps determine directory blocks needed.
• Estimate Size: Estimate average member size. Panels are typically small (1-5 tracks each), but messages and skeletons vary. Plan for growth.
• Calculate Space: Multiply estimated members by average size, then add buffer for growth. Allocate 20-30% extra space for unexpected growth.
• Consider Secondary: Allocate sufficient secondary space to handle growth without frequent extent additions, which can impact performance.

Under-allocation causes problems when libraries fill up, while over-allocation wastes storage. Balance these concerns based on your specific needs.

Panel Library Setup

Panel libraries store ISPF panel definitions. Setting up panel libraries correctly ensures panels can be found and displayed by ISPF.

Panel Library Requirements

Panel libraries have specific requirements:

• PDS Format: Must be partitioned dataset (PO) to store multiple panel members
• Standard Attributes: RECFM=FB, LRECL=80, appropriate BLKSIZE
• Member Naming: Panel members typically use 8-character names following ISPF naming conventions
• Content Format: Panel members contain ISPF panel definition language (PDL) statements
• Accessibility: Must be accessible to users who need to display panels

Panel libraries are searched in concatenation order when ISPF needs to display a panel. The first library containing the requested panel member is used.

Creating Panel Library Members

After allocating a panel library, create panel members:

• Use ISPF Editor (Option 2) to edit the panel library
• Specify the library dataset name and member name
• Enter panel definition using ISPF Panel Definition Language
• Save the member

Panel definitions use ISPF Panel Definition Language with sections like )ATTR (attributes), )BODY (panel content), and )END (end of panel).

Example Panel Library Setup

Here's a complete example of setting up a panel library:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
1. Allocate the library:
   ALLOCATE DATASET('USERID.MYPANELS') NEW +
     SPACE(TRACKS,(5,2)) DIR(20) +
     RECFM(F,B) LRECL(80) BLKSIZE(27920) +
     DSORG(PO) UNIT(SYSDA)
 
2. Create a panel member:
   - Go to ISPF Editor (Option 2)
   - Edit USERID.MYPANELS(MYPNL01)
   - Enter panel definition:
     )ATTR
     @ TYPE(TEXT) INTENS(HIGH)
     )BODY
     +-------------------+
     | @ My First Panel  |
     +-------------------+
     )END
   - Save the member
 
3. Add library to concatenation:
   - Go to ISPF Settings (Option 0)
   - Navigate to Library Management
   - Add USERID.MYPANELS to panel library concatenation
   - Save settings

Library Concatenation

ISPF uses library concatenation to search multiple libraries for resources. Understanding concatenation order and configuration is essential for proper library setup.

How Concatenation Works

When ISPF needs a resource (panel, message, etc.), it searches libraries in concatenation order:

• Search Order: Libraries are searched from first to last in the concatenation
• First Match Wins: The first library containing the requested member is used
• Override Capability: User libraries searched after system libraries can override system resources
• Resource Types: Each resource type (panels, messages, skeletons) has its own concatenation

Concatenation allows system libraries to provide defaults while user libraries provide customization. Proper ordering ensures desired resources are found.

Configuring Library Concatenation

Library concatenation is configured through ISPF Settings:

• Navigate to ISPF Settings (Option 0)
• Access Library Management or Library Concatenation options
• Specify libraries for each resource type (PANEL, MESSAGE, SKELETON, etc.)
• Order libraries appropriately (system libraries first, then user libraries)
• Save settings to your ISPF profile

System-level concatenation (affecting all users) requires system administrator privileges and may involve updating ISPF installation parameters or system configuration datasets.

Concatenation Best Practices

• Order Matters: Place frequently accessed libraries first to improve performance
• System First: Keep system libraries (ISR@) before user libraries to maintain system functionality
• Minimize Libraries: Too many libraries in concatenation can slow searches; include only necessary libraries
• Document Order: Document concatenation order for troubleshooting and maintenance
• Test Changes: Test concatenation changes to ensure resources are still found correctly

Installation Procedures

Installing ISPF libraries involves allocation, population, and configuration. This section covers installation procedures for both system and user libraries.

System Library Installation

System library installation is typically performed by system administrators during ISPF installation:

• Allocate Libraries: Allocate ISR@ libraries with appropriate space and attributes
• Load Components: Load ISPF system components (panels, messages, etc.) into libraries
• Configure Concatenation: Set up system-level library concatenation
• Verify Installation: Test ISPF functionality to verify libraries are working
• Document Configuration: Document library locations and concatenation for maintenance

System installation procedures vary by organization and ISPF version. Follow vendor or organizational procedures for system library installation.

User Library Installation

Users can install their own libraries for customization:

• Allocate Library: Allocate PDS with appropriate parameters for your needs
• Create Members: Create panels, messages, or other resources as members
• Add to Concatenation: Add library to your ISPF profile concatenation
• Test Functionality: Test that resources are found and work correctly

User libraries allow customization without modifying system libraries, maintaining separation between system and user resources.

Verification Procedures

After installation, verify libraries are working:

• Check Allocation: Verify libraries are allocated and accessible using TSO LISTALC or dataset utilities
• Verify Concatenation: Check ISPF Settings to verify concatenation is configured correctly
• Test Resource Access: Test accessing resources (display panels, view messages) to verify they're found
• Check for Errors: Review ISPF session for library-related error messages
• Verify Functionality: Test ISPF features that depend on libraries to ensure everything works

Maintenance and Troubleshooting

Library maintenance ensures continued functionality, and troubleshooting helps resolve library-related issues.

Common Issues

Common library-related issues include:

• Library Not Found: Library not in concatenation or incorrect dataset name
• Member Not Found: Member doesn't exist in any library in concatenation
• Access Errors: Insufficient permissions to access library or members
• Space Exhausted: Library out of space or directory blocks
• Concatenation Order: Wrong library found due to concatenation order

Understanding these issues helps diagnose and resolve library problems quickly.

Troubleshooting Steps

When troubleshooting library issues:

• Verify Allocation: Confirm library is allocated and accessible
• Check Concatenation: Verify library is in concatenation and in correct order
• Verify Members: Confirm members exist in libraries
• Check Permissions: Verify you have access to libraries and members
• Review Errors: Check ISPF error messages for specific issues
• Test Access: Try accessing libraries directly to isolate problems

Explain Like I'm 5: ISPF Libraries

Think of ISPF libraries like bookshelves in a library:

• Libraries are like bookshelves that hold books (members). Each bookshelf can hold many books, and you need to set up the bookshelf before you can put books on it!
• ISR@ Libraries are like the main library bookshelves that everyone uses. They have all the standard books (system panels and messages) that everyone needs. These are set up by the librarians (system administrators) for everyone to use!
• User Libraries are like your own bookshelf at home. You can put your own books (custom panels) on it, and when you're looking for a book, you check your bookshelf first, then the main library if you don't find it!
• Concatenation is like having a list of which bookshelves to check in order. You check the first bookshelf, then the second, then the third, until you find the book you need. The order matters because you use the first book you find, even if the same book exists on later bookshelves!
• Allocation is like building a new bookshelf. You need to decide how big to make it (space), how many books it can hold (directory blocks), and where to put it (volume). Once it's built, you can start putting books on it!

So ISPF libraries are like organized bookshelves where ISPF stores all its panels, messages, and other resources, and concatenation tells ISPF which bookshelves to check and in what order!

Practice Exercises

Practice library allocation and setup with these exercises:

Exercise 1: Allocate a Panel Library

Objective: Practice allocating a panel library.

Steps:

• Use ISPF Data Set Utility (Option 3.2) to allocate a new PDS for panels
• Specify appropriate parameters: RECFM=FB, LRECL=80, DSORG=PO
• Allocate sufficient space (5-10 tracks) and directory blocks (20-30)
• Verify the library is allocated and accessible

Exercise 2: Create and Test a Panel

Objective: Create a panel member and verify it works.

Steps:

• Edit a new member in your panel library
• Create a simple panel definition
• Save the member
• Use Dialog Test (Option 7) to display the panel
• Verify the panel displays correctly

Exercise 3: Configure Library Concatenation

Objective: Add your library to ISPF concatenation.

Steps:

• Access ISPF Settings (Option 0)
• Navigate to Library Management or Library Concatenation
• Add your panel library to the panel library concatenation
• Save settings
• Test that your panel is found when referenced by name

Related Concepts