unisys
imagine it. done.
OS 2200
Shared File System (SFS 2200)
Administration and Support Reference Manual
Release Level 4R1
NO WARRANTIES OF ANY NATURE ARE EXTENDED BY THIS DOCUMENT. Any product or related information described herein is only furnished pursuant and subject to the terms and conditions of a duly executed agreement to purchase or lease equipment or to license software. The only warranties made by Unisys, if any, with respect to the products described in this document are set forth in such agreement. Unisys cannot accept any financial or other responsibility that may be the result of your use of the information in this document or software material, including direct, special, or consequential damages.
You should be very careful to ensure that the use of this information and/or software material complies with the laws, rules, and regulations of the jurisdictions with respect to which it is used.
The information contained herein is subject to change without notice. Revisions may be issued to advise of such changes and/or additions.
Notice to U.S. Government End Users: This is commercial computer software or hardware documentation developed at private expense. Use, reproduction, or disclosure by the Government is subject to the terms of Unisys standard commercial license for the products, and where applicable, the restricted/limited rights provisions of the contract data rights clauses.
7831 0786–003 iii
Contents
Section 1. About This Manual
1.1. Documentation Updates ... 1–1 1.2. Prerequisites ... 1–2
Section 2. Introducing SFS
2.1. What Is SFS? ... 2–2 2.2. Benefits of SFS ... 2–2 2.3. Who Should Use SFS? ... 2–2 2.4. Related Software Products ... 2–3 2.5. SFS File Features ... 2–3 2.6. SFS Requirements ... 2–4 2.7. Using SFS to Access Files Created with PCIOS ... 2–6 2.8. Example of DSDF File Access ... 2–6 2.9. Example of MSAM File Access ... 2–7 2.10. Changing Computed Block Size with DFP ... 2–8 2.11. TIP Processing with SFS ... 2–9 2.11.1. Defining TIP Files ... 2–9 2.11.2. Registering and Reserving TIP Files... 2–9 2.11.3. Defining a Storage Area ... 2–10
2.11.4. Specifying the Storage Area Name in a Program ... 2–11
2.11.5. Passing the Storage Area Name to SFS ... 2–11 2.11.6. Summary ... 2–12
Section 3. Using Banks, Programs, and Files
3.1. SFS Banks ... 3–2
3.2. Processing Programs Compiled in Basic Mode
Programming Environment ... 3–3 3.3. How SFS Processes UCS Programs ... 3–8 3.4. Using Explicit and Implicit Thread Control ... 3–10 3.5. Using Multiple Application Groups ... 3–11
3.5.1. Programs Compiled in Basic Mode Environment ... 3–11
3.5.2. Programs Compiled with Universal Compiling
System (UCS) ... 3–15 3.6. Collecting Multiple Data Model Programs ... 3–18 3.7. Linking Multiple Data Model Programs ... 3–20
3.7.1. Dynamic Linking to Standard Application Group ... 3–20
3.7.2. Static Linking to Standard Application Group ... 3–20 3.7.3. Linking to Alternate Application Group... 3–21 3.8. A Closer Look at the Processor Interface Module ... 3–26 3.9. SFS Bank Descriptions ... 3–27
Contents
Section 4. SFS Input/Output Operations
4.1. Calling SFS ... 4–2 4.1.1. Setting Up Environment ... 4–2 4.1.2. Initializing Registers ... 4–2 4.1.3. Setting Up Request Packet ... 4–2 4.1.4. Calling the SFS ICR ... 4–3 4.2. Performing I/O Operations on DSDF Files ... 4–3 4.3. DSDF Skeletonization ... 4–4 4.4. DSDF Input/Output Processing ... 4–4 4.4.1. DSDF OPEN FILE Command ... 4–5 4.4.2. General Rules for OPEN Command ... 4–6 4.4.3. DSDF READ RECORD Command ... 4–7
4.4.4. DSDF READ NEXT RECORD Command ... 4–8
4.4.5. DSDF REWRITE RECORD Command ... 4–9
4.4.6. DSDF DELETE RECORD Command ... 4–10
4.4.7. DSDF WRITE RECORD Command ... 4–10
4.4.8. DSDF START Command ... 4–11 4.4.9. DSDF CLOSE FILE Command ... 4–12 4.5. Performing I/O Operations on MSAM Files ... 4–13 4.6. MSAM Input/Output Processing ... 4–14 4.6.1. MSAM OPEN FILE Command ... 4–15
4.6.2. MSAM READ RECORD Command ... 4–16
4.6.3. MSAM READ NEXT RECORD Command ... 4–17
4.6.4. MSAM WRITE RECORD Command ... 4–18
4.6.5. MSAM REWRITE RECORD Command ... 4–21
4.6.6. MSAM DELETE RECORD Command ... 4–23
4.6.7. MSAM START Command ... 4–24 4.6.8. MSAM CLOSE FILE Command ... 4–25
Section 5. Recovering SFS Files
5.1. SFS File Recovery ... 5–2 5.2. The UDS Recovery Model ... 5–3 5.3. How Recovery Works ... 5–5 5.3.1. Rollback ... 5–5 5.3.2. Short and Long Recovery... 5–5 5.3.3. Deferred Updates ... 5–5 5.3.4. Quick-Looks ... 5–6 5.3.5. Audit After-Looks ... 5–6
Contents
7831 0786–003 v
6.5.1. Recovery Unit ... 6–6 6.5.2. COMMIT Command ... 6–6 6.5.3. Implicit End Thread... 6–6 6.5.4. Page Lock Duration ... 6–7 6.5.5. Explicit End Thread ... 6–7 6.6. SFS Locking Summary ... 6–8 6.6.1. Exclusive and Protected File Locks ... 6–8 6.6.2. Exclusive and Protected Page Locks ... 6–8 6.7. Special SFS MASM Routines... 6–10 6.7.1. Exclusive Open Mode ... 6–10 6.7.2. Protected Open Mode ... 6–10 6.7.3. Read and Unlock ... 6–10 6.8. Sample ACOB Program ... 6–11 6.8.1. ACOB Source Program ... 6–11
6.8.2. Collecting ACOB Programs with SFS MASM
Routine ... 6–13
Section 7. SFS Control Tables
7.1. SFS Control Table Usage ... 7–2 7.2. Storage Control Table Format for DSDF ... 7–3 7.3. Storage Control Table Format for MSAM ... 7–4 7.3.1. Save Area Record (SAR) ... 7–5 7.3.2. Operation Control Block (OCB) ... 7–6 7.4. File Control Table Format for DSDF ... 7–9 7.4.1. File Control Block Format for DSDF ... 7–10 7.4.2. Buffer Control Block Format for DSDF ... 7–14 7.5. File Control Table Format for MSAM ... 7–18 7.5.1. File Control Block Format for MSAM ... 7–18 7.5.2. Buffer Control Block Format for MSAM ... 7–23
7.5.3. Indexed Key Table (IKT) Format for MSAM ... 7–24
7.5.4. Key Type Packets ... 7–28 7.6. Data Definition Packet Format ... 7–31 7.6.1. Data Definition Table Format ... 7–36 7.6.2. Environment Table Format ... 7–38 7.6.3. MSAM Index Table Format ... 7–42 7.6.4. Value Table Format... 7–44 7.6.5. ENAME Table Format ... 7–45 7.6.6. Status Table Format ... 7–47 7.7. Data Access Packet Format ... 7–51
Section 8. Data File Formats
8.1. Accessing SFS Files ... 8–2 8.2. DSDF File Contents ... 8–2 8.3. DSDF File Layout ... 8–3 8.4. DSDF Label Record Format ... 8–4 8.5. DSDF Record Control Word Format ... 8–10 8.5.1. Data Record Control Word Format ... 8–10 8.5.2. Special Record Control Word Format ... 8–11 8.6. End-of-File Record Format ... 8–11
Contents
8.7. Multi-Indexed Sequential Access Method (MSAM) File
Contents ... 8–12 8.7.1. Information Block Contents ... 8–12 8.7.2. Label Area Format ... 8–13 8.7.3. Indexed Key Table Area Contents ... 8–18 8.7.4. Statistics Table Contents ... 8–18 8.7.5. Partially Filled Data Block List ... 8–20 8.8. Index Block Structure ... 8–21 8.9. Data Block Structure ... 8–25 8.10. File Size Considerations ... 8–29 8.11. MSAM Record Placement ... 8–31 8.12. MSAM Programming Considerations ... 8–32
Section 9. SFS Error Processing
9.1. Error Processing in Basic Mode Programming
Environment ... 9–2
9.1.1. C2SFSERR Error Word Format for DSDF Files ... 9–2
9.1.2. C2SFSERR Status Codes for DSDF Files ... 9–3 9.1.3. PIM Error Code Processing... 9–6
9.1.4. Status Information for MSAM Files Compiled in
Basic Mode Programming Environment ... 9–7
9.1.5. MSAM Error Codes in Basic Mode Programming
Environment ... 9–9 9.2. Program Error Processing for UCS Programs ... 9–12 9.2.1. Status/Area Format ... 9–12 9.2.2. UCS DSDF Error Messages ... 9–17 9.2.3. UCS MSAM Error Messages ... 9–20
9.2.4. MSAM and DSDF Status Codes Returned by
LDM ... 9–22
Appendix A. Computing Buffer Sizes
A.1. DSDF Files ... A–1 A.2. MSAM Files ... A–1 A.3. Problems When Audit Buffer Is Too Small ... A–1 A.4. Computing Correct Exec Buffer and Transfer Size ... A–2 A.4.1. Example 1: Buffered Audit ... A–2
7831 0786–003 vii
Figures
3–1. Simplified Processing Sequence for Program Compiled in Basic Mode
Programming Environment ... 3–4
3–2. Processing of Program Compiled in Basic Mode Programming
Environment ... 3–6
3–3. SFS Processing of Program Compiled in Extended Mode Programming
Environment ... 3–9 5–1. Recovery Model ... 5–3 7–1. Storage Control Table ... 7–3 7–2. Storage Control Table Format ... 7–4 7–3. Save Area Record Format ... 7–5 7–4. Operation Control Block ... 7–6 7–5. File Control Table ... 7–9 7–6. File Control Block ... 7–10 7–7. Buffer Control Block for DSDF File ... 7–14 7–8. File Control Block for MSAM ... 7–19 7–9. Buffer Control Block for MSAM ... 7–23 7–10. MSAM Indexed Key Table, Fixed Portion ... 7–25 7–11. Variable-Length Portion of IKT ... 7–28 7–12. Data Definition Packet ... 7–31 7–13. Data Definition Table ... 7–36 7–14. Environment (ENV) Table ... 7–38 7–15. MSAM Index Table ... 7–42 7–16. MSAM Index Table Key Packet ... 7–43 7–17. Value Table ... 7–44 7–18. ENAME Table ... 7–45 7–19. Status Table ... 7–47 7–20. Data Access Packet ... 7–51 8–1. DSDF File Layout ... 8–3 8–2. DSDF Label Record Format 2 ... 8–4 8–3. Data Record Control Word Format ... 8–10 8–4. Special Record Control Word Format ... 8–11 8–5. EOF Record Control Word Format ... 8–11 8–6. MSAM Information Block Format ... 8–12 8–7. MSAM Label Area Format ... 8–13 8–8. MSAM Index Block Format ... 8–21 8–9. MSAM Data Block Format ... 8–26 9–1. Error Word Format ... 9–3
7831 0786–003 ix
Tables
3–1. SFS I-Banks ... 3–2 4–1. Permissible DSDF Input/Output Commands ... 4–5 4–2. Permissible MSAM Input/Output Commands ... 4–14 6–1. File Usage Mode Compatibility ... 6–4 6–2. Lock Duration ... 6–7 6–3. File Usage and Locking Strategy ... 6–9 8–1. HDR1 Format ... 8–17 8–2. Statistics Table Contents ... 8–18 8–3. Contents of Partially Filled Data Block List ... 8–20 9–1. C2SFSERR Status Codes ... 9–3 9–2. Status Field 1 Conditions for Basic Mode Programming Environment ... 9–7 9–3. Status Field 2 Conditions for Basic Mode Programming Environment ... 9–8 9–4. MSAM Error Codes in Basic Mode Programming Environment ... 9–9 9–5. Status Field 1 Conditions ... 9–13 9–6. Status Field 2 General Conditions ... 9–13 9–7. Conditions for Status Fields 1 and 2 ... 9–15 9–8. UCS DSDF Status Conditions ... 9–17 9–9. UCS MSAM Status Conditions ... 9–20 9–10. MSAM and DSDF Status Codes ... 9–22
7831 0786–003 1–1
Section 1
About This Manual
Purpose
This manual describes SFS software. SFS is a Universal Data System (UDS) software product that provides shared access to data files from programs compiled in the traditional programming environment and in the Universal Compiling System (UCS). Shared access gives multiple programs simultaneous access to a single file, improving processing throughput. And, since SFS takes advantage of the UDS locking and recovery functions, users do not sacrifice data integrity.
This manual enables you to understand how SFS manages the concurrent processing of MSAM and DSDF files by multiple applications operating within the UDS environment.
Scope
This manual introduces SFS and its interface with UDS Control. It explains SFS input/output operations, the file recovery process, file and page locks, control tables, data file formats, and SFS error processing.
It does not explain the commands that enable a program to access SFS. If a language, such as ASCII FORTRAN, contains commands indicating that a file is shared, its applicable programmer reference guide provides the exact syntax for the commands. Otherwise, you must indicate that a file is shared by using the Define File Processor (DFP). Section 1 of this manual discusses how to use DFP. For a full description of DFP,
see the DFP Operations and Programming Reference Manual.
Audience
This manual is for programmers and systems analysts who need a technical description of SFS level 4R1 software.
1.1.
Documentation Updates
This document contains all the information that was available at the time of publication. Changes identified afterrelease of this documentare included in problem list entry (PLE) 18726165. To obtain a copy of the PLE, contact your Unisys service representative or access the current PLE from the Unisys Product Support Web site:
http://www.support.unisys.com/all/ple/18726165
About This Manual
1.2.
Prerequisites
The assumption in this manual is that the reader may have advanced knowledge and experience with either ASCII COBOL, ASCII FORTRAN, UCS COBOL, or UCS FORTRAN. You should also be familiar with the UDS environment, multi-indexed and sequential files, and, if applicable, the UCS environment.
7831 0786–003 2–1
Section 2
Introducing SFS
This section describes the Shared File System (SFS) and discusses the following topics:
• Benefits of SFS
• Attributes of shared files
Introducing SFS
2.1.
What Is SFS?
The Shared File System (SFS) is a Universal Data System (UDS) software product that consists of a collection of file access routines. It is a data management program that provides shared access to data files created and maintained by application languages such as ASCII COBOL and ASCII FORTRAN. Shared access allows more than one application program to access a file at the same time.
SFS provides the flexibility of writing files with an application program developed in one programming language and reading or updating those files with application programs developed in other languages.
Because SFS operates in the UDS environment, it has the recovery and locking features provided by Integrated Recovery Utility (IRU) and locking subsystem (LSS) software components. Users can access files concurrently and update the same file at the same time without sacrificing data integrity. When you update a record, SFS calls the UDS locking subsystem to lock the page until you commit the updates, making them permanent. When a record is read, SFS calls LSS to lock the page. SFS calls LSS to unlock the page as soon as the lock is no longer needed.
2.2.
Benefits of SFS
SFS provides the following benefits:
• Increased throughput
SFS allows concurrent access by multiple programs to the same multi-indexed sequential access method (MSAM) and direct system data format (DSDF) files. This capability can increase processing throughput, saving time and money.
• Data safeguarding
SFS uses the full recovery features of UDS to provide recovery for MSAM and DSDF files. These features include program rollback, short recovery, selective recovery, and long recovery.
• Data integrity
SFS uses the locking features of UDS to ensure data integrity when files are accessed by multiple users.
Introducing SFS
7831 0786–003 2–3
2.4.
Related Software Products
You must install these OS 2200 products before you can install and use SFS:
• SCS (System Control Software)
• UDS Control (Universal Data System Control)
• IRU (Integrated Recovery Utility)
• UREP (Unisys Repository Manager)
You usually use SFS with an OS 2200 compiler or language processor. You can also use SFS with IMS 1100.
Without the key tape installed, the data storage definition (DSD) processor in UREP is available to create the file definition tables (FDT) necessary for SFS execution. However, the full function of UREP is not available. See the UDS Configuration Guide.
2.5.
SFS File Features
To use SFS, you must first define the file as shared. There are two ways of doing this:
• Use the Define File Processor (DFP) to define the file as shared. DFP is a stand-alone processor that provides external file descriptions to OS 2200 language processor interface modules (PIM). You can find out more about DFP in 2.6, 2.10, and 3.2. See the DFP Operations and Programming Reference Manual for detailed instructions on how to describe a file as shared.
• The following OS 2200 language processors provide syntax to define a file as shared:
ASCII COBOL, ASCII FORTRAN, UCS FORTRAN, and UCS COBOL. DFP is not needed in these instances.
Files that you plan to share must have these features:
• They must be DSDF or MSAM files. (See Section 4 for details.)
• They must be cataloged public files or TIP files.
• They must each have a permanent directory entry that declares the attributes of a
file. These entries reside in the file description table (FDT) of the repository. You use UREP commands to create these entries. Both SFS and UDS Control use the FDT when SFS files are processed. SFS files can be defined with a domain of USER, USER-UDS, UDS-TIP, or UDS.
If a shared file is not a TIP file, it may be assigned to UDS Control banks, or you can optionally assign it to a user runstream. The assignment depends on the domain defined in the FDT for the file.
Introducing SFS
Sharing files in the UDS Control architecture allows you to take advantage of these UDS features:
• The UDS Control cache manager controls operations to and from shared files
through UDS page banks, which makes pages of data available for shared access.
• You can define UDS dedicated page banks or in-memory files. The UDS cache
manager controls input from files, reading data into page banks. Once pages from a file go into one or more page banks, they are dedicated to that file. If a file is small or only part of it is going to be used, once it is loaded into memory it can stay there permanently and be described as an in-memory file.
You specify whether a file is dedicated or in-memory by using the UREP PROCESS
command with the CONFIGURATION entity. The UREP Programming Reference
Manual describes how to use the PROCESS command.
• You can declare a shared file to be recoverable, allowing it to be automatically restored to a consistent state should the program or OS 2200 software fail.
• You can specify the file as audited, which allows you to invoke long recovery and restore the file to a consistent state in the event of disk failure.
If the file is not audited and it resides on a system with a cache disk subsystem, the file should be cataloged with the S option on the @CAT statement to prevent data corruption if the cache disk subsystem should fail.
2.6.
SFS Requirements
In order to use SFS successfully, your system must fulfill the following requirements:
• Shared files must have file description tables (FDT).
You must create and install a file description table (FDT) for each storage area (SFS file) using the data storage definition (DSD) processor in UREP. (See the UREP Programming Reference Manual for information on how to create and maintain FDTs.) In the FDT for an SFS file, “schema name” equals the file qualifier; “storage area name” equals the file name; “domain” can be USER-UDS, UDS, UDS-TIP, or USER.
• You must identify the SFS file to your run.
In order to locate the FDT for an SFS Exec file, you must supply its external qualifier and file name by attaching a use name to the external file name. If you have defined the FDT for this file with a domain of UDS, you must not assign the file.
Introducing SFS
7831 0786–003 2–5
Before you execute the program, you must do the following:
@USE PAYROLL.,JUNE*PAYROLL.
@ASG,A JUNE*PAYROLL. (optional if the domain is USER-UDS; mandatory if the domain is USER. Do not do this for files defined with a domain of UDS or UDS-TIP.)
TIP (domain UDS-TIP) files must not be assigned. If an SFS file is not assigned to your run and does not have a use name, SFS software assumes the file may be a TIP file and attempts to locate an FDT for it using the schema name of TIP$SFS.
• You must define the file as shared, either by using program syntax or by using DFP.
− In ASCII COBOL and in UCS COBOL, the SELECT clause implementor name
A-SHARED-FILE indicates that SFS is to process the file rather than PCIOS. For example
SELECT internal-name ASSIGN TO A-SHARED-FILE external-name...
The use of A-SHARED-FILE as the implementor name causes the ACOB PIM to bypass all DFP processing for that file.
In ASCII FORTRAN and in UCS FORTRAN, the RFORM clause in the OPEN statement is used to describe a file as shared. This is the syntax:
RFORM = { 'LS' | 'MS' | 'ES' | 'FS' | 'US' | 'VS' }
where ’S’ indicates shared. For example
OPEN(10,access='direct',recl=101,rform='ls')
− You can use DFP to indicate a file as shared as follows (S-FILE is the file name):
@ASG,T DFP$.,F
@DFP,EL S-FILE.,DFP$. SHARE = YES
END
SHARE = YES causes the file to be processed by SFS. SHARE = NO causes the file to be processed by PCIOS.
This overrides the ’S’ values of the FORTRAN RFORM clause in the OPEN statement.
• Files assigned to removable disk packs must be cataloged with an initial reserve
equal to the maximum allowable size.
Files assigned to removable disk packs cannot be expanded across packs, unless more than one removable disk pack is specified when the file is cataloged. If the initial reserve for the file is smaller than the maximum allowable size, it is possible that at the time when the file is expanded from its current size to accommodate more records, the removable pack may be too full to accommodate the additional space. This situation is likely to occur on a COMMIT command or END THREAD command rather than on a WRITE command.
Introducing SFS
If this situation does occur, the Exec passes an I/O error 026 to the UDS cache manager, SFS returns an error status to the user program indicating an I/O error was received from the cache manager, and the file is left in a corrupted state if the thread is not rolled back.
2.7.
Using SFS to Access Files Created with PCIOS
You can use SFS to access and maintain files you created by using the Processor Common Input/Output System (PCIOS).
SFS provides features similar to PCIOS in a shared access environment that supports data locking and data recovery.
2.8.
Example of DSDF File Access
This sample procedure accesses a DSDF Exec file through SFS, using language syntax to define the file as shared. (See 2.11 for a TIP example.)
Step 1
First, define the file by using ASCII COBOL or UCS COBOL syntax. This example defines a shared DSDF file:
FILE-CONTROL.
SELECT PZ ASSIGN TO A-SHARED-FILE D-FILE ORGANIZATION IS RELATIVE
ACCESS MODE IS RANDOM .
. .
Step 2
Next, define an FDT for the storage area for the shared file SFS*D-FILE:
@DD,LE
CREATE SCHEMA SFS.
CREATE STORAGE-AREA D-FILE FOR SCHEMA SFS. ADD FILE-TYPE EXEC.
Introducing SFS
7831 0786–003 2–7
Step 3
Connect the program file name (D-FILE) to the external file name (SFS*D-FILE) by specifying a use name; then execute the program:
@USE D-FILE.,SFS*D-FILE. @XQT PROGRAM-P1
D-FILE is the name used in the program for the DSDF data file. SFS*D-FILE is the Exec qualifier and file name for the file. PROGRAM-P1 represents the executable program with the sample ASCII or UCS COBOL syntax specified in step 1.
2.9.
Example of MSAM File Access
This sample procedure accesses an MSAM Exec file through SFS using DFP to define the file as shared.
Step 1
First, define the file using COBOL syntax. This example defines an MSAM file:
FILE-CONTROL.
SELECT MZ ASSIGN TO DISC M-FILE ORGANIZATION IS INDEXED
RECORD KEY IS M-KEY .
. .
Step 2
Next, define an FDT for the storage area for the file SFS*M-FILE:
@DD,LE
CREATE SCHEMA SFS.
CREATE STORAGE-AREA M-FILE FOR SCHEMA SFS. ADD FILE-TYPE EXEC.
ADD DATA-FORMAT MSAM. ADD AUDITED TRUE. ADD DOMAIN USER-UDS. ADD PAGE-SIZE 1792. ADD RECOVERED TRUE.
PROCESS STORAGE-AREA M-FILE FOR SCHEMA SFS INSTALL. EXIT.
Step 3
Use DFP to define file SFS*M-FILE as shared:
@ASG,T DFP$.
@DFP,EL M-FILE.,DFP$. SHARE = YES
Introducing SFS
Step 4
Connect the program file name (M-FILE) to the external file name (SFS*M-FILE) by applying a use name, then execute the program:
@USE M-FILE.,SFS*M-FILE. @XQT PROGRAM-P1
M-FILE is the name used in the program for the MSAM data file. SFS*M-FILE is the Exec qualifier and file name for the file. PROGRAM-P1 represents the executable program with the sample COBOL syntax specified in step 1.
2.10.
Changing Computed Block Size with DFP
You can use DFP to set the block (page) size for initial MSAM file load. SFS always uses the block size in the program file description, disregarding the block size specified for the FDT storage area. You may want to use DFP to reset the relatively large block size set by
ASCII COBOL. See the DFP Operations and Programming Reference Manual for a full
description of this process.
This example demonstrates how to use the DFP to reset block size: 1. Create a define file block using the DFP.
@DFP,LE FILENAME.,PROGRAM-FILE. BLOCK=896/////WORDS
SHARE=YES END
2. Put a use name of DFP$ on the file containing the define file block:
@USE DFP$.,PROGRAM-FILE.
3. Execute the file load program with the MSAM file for output. The system searches
PROGRAM-FILE for the define file block FILENAME and uses its block size of 896 words for the MSAM file.If an MSAM file is already created, SFS uses the block size in the label.
4. If COBOL language syntax declares the file as shared, the ACOB PIM bypasses
processing the define file block completely.
Introducing SFS
7831 0786–003 2–9
2.11.
TIP Processing with SFS
You can define and access shared files under TIP file control with SFS, placing SFS storage areas under TIP. Using TIP file control eliminates much Exec input/output overhead and reduces the need for file assignment. You can also use a combination of TIP and Exec file control.
Thus, a program using SFS can access
• Exec files
• TIP files
• A combination of TIP and Exec files
2.11.1.
Defining TIP Files
You can define TIP files during TIP generation or through TIP runstream control
statements. The file must be defined to TIP before it can be used as a TIP file. See the
Transaction Processing Programming Reference Manual for details about defining TIP files.
2.11.2.
Registering and Reserving TIP Files
Before SFS can process a TIP file, you must register and reserve a cataloged file by using the TIP FREIPS library routines.
Here is an example of the registration and reservation process:
@TIP-LIB.FREIPS,IUX application-number TREG TIP$SFS*M-FILE1.,fix
RES,G 403,999,1792,,M-FILE1 @EOF
In this example, TIP-LIB is the TIP library file containing the FREIPS functions.
TIP$SFS*M-FILE1 is the SFS TIP file. The TIP file number is 403. M-FILE1 on the RES command is the Exec file name, the same file name on the TREG command.
Introducing SFS
2.11.3.
Defining a Storage Area
Before using a shared file as a TIP file, you must define a storage area for the file. This example shows how to define a storage area for a TIP file, TIP$SFS*M-FILE1, processed by SFS.
Step 1
First, catalog the file with a TIP$SFS qualifier:
@CAT,P TIP$SFS*M-FILE1. ,F///999
Step 2
Now, define an FDT for the storage area:
@DD,LE
CREATE SCHEMA TIP$SFS.
CREATE STORAGE-AREA M-FILE1 FOR SCHEMA TIP$SFS. ADD FILE-TYPE UDS-TIP.
ADD UDS-TIP-CODE 403. ADD DATA-FORMAT MSAM. ADD AUDITED TRUE. ADD PAGE-SIZE 1792. ADD RECOVERED TRUE.
PROCESS STORAGE-AREA M-FILE1 FOR SCHEMA TIP$SFS INSTALL. EXIT.
For SFS, the file name is the storage area name. The schema name for a TIP storage
area must be TIP$SFS. See the UREP Programming Reference Manual for UREP
Introducing SFS
7831 0786–003 2–11
2.11.4.
Specifying the Storage Area Name in a Program
Specify the storage area name (M-FILE1) as the program file name in the SELECT clause in the File Control Section of the ASCII COBOL or UCS COBOL program, as in either of these examples:
FILE-CONTROL.
SELECT MSAM-S ASSIGN DISC M-FILE1 ORGANIZATION IS INDEXED
ACCESS MODE IS SEQUENTIAL .
. .
or FILE-CONTROL.
SELECT M-FILE1 ASSIGN DISC ORGANIZATION IS INDEXED ACCESS MODE IS SEQUENTIAL .
. .
2.11.5.
Passing the Storage Area Name to SFS
You can pass the storage area name to SFS in one of two ways:
• Method 1
Attach the program file name (M-FILE1) to the external file name TIP$SFS*M-FILE1. When SFS receives the file name, it checks to see whether it is a use name.
@USE M-FILE1. ,TIP$SFS*M-FILE1.
• Method 2
If you do not specify @USE to attach the program file name to the external file name, the file name must be unique. This name must be the same as the storage area name for UREP and as is specified in the SELECT clause of the COBOL program. SFS assumes that the schema name is TIP$SFS and uses it as a prefix to the program filename, M-FILE1. SFS uses the fully qualified name TIP$SFS*M-FILE1 to retrieve the file description table.
If a storage area of TIP$SFS*M-FILE1 has been defined, SFS uses the UDS TIP code specified for this file description table. If SFS cannot find the file registered and reserved with TIP, UDS issues an error and rolls back the thread.
Introducing SFS
2.11.6.
Summary
When using TIP files with SFS, you must
1. Create a storage area (with UREP commands) that describes the TIP file.
2. Register and reserve TIP areas by using the FREIPS routines.
3. Ensure that the file name in the program SELECT clause is the same as the storage
area name you define with UREP commands. In the example just used, the storage area name and the name in the COBOL SELECT clause is M-FILE1.
4. If your site does not use the @USE method, make sure that file names used in
SELECT clauses are unique across all programs.
7831 0786–003 3–1
Section 3
Using Banks, Programs, and Files
This section discusses the following topics:
• SFS banks
• How SFS processes programs compiled in the extended mode and basic mode
programming environments
• How to execute SFS from the default or alternate application group
Using Banks, Programs, and Files
3.1.
SFS Banks
SFS is made up of a group of alternate file common banks accessible on an OS 2200 system. These instruction banks (I-banks) contain SFS code that can be simultaneously shared by many programs.
UDS provides each program calling SFS with a local thread data bank (D-bank) while logical data managers, such as SFS, can access the UDS global data banks. The thread D-bank contains data unique to the program. The global data banks contain data and tables that are shared throughout UDS to control UDS processing.
SFS banks use UDS Control to lock direct system data format (DSDF) and multi-indexed sequential access method (MSAM) shared files. The locking subsystem queues user threads (sequences of user commands) so that each can access data in order. The system resolves more serious conflicts, known as deadlocks, by rolling back one of the accessing threads. Section 6 discusses SFS locking in detail.
The SFS DSDF and MSAM storage record handler (SRH) processing calls the UDS locking subsystem routines and the UDS cache manager. When you request a payroll record, for example, the SRH first calls the UDS locking subsystem routines to lock the page containing the record. The SRH next calls the UDS cache manager to write to or read from the database. In UDS architecture, storage record handlers are referred to as storage record managers.
Table 3–1 identifies SFS I-banks.
Table 3–1. SFS I-Banks
Bank Name Contents
C2P$ This bank converts old table formats to new SFS formats.
C2PICR$ Intercept and connect routine (ICR) bank for SFS
C2SFSD$ DSDF interface bank
C2SFSE$ Bank containing C2ERR messages C2SFSM$ MSAM interface bank
Using Banks, Programs, and Files
7831 0786–003 3–3
3.2.
Processing Programs Compiled in Basic Mode
Programming Environment
SFS processes requests from programs created for the UCS programming environment or programs compiled in the basic mode environment, such as those written in ASCII COBOL or ASCII FORTRAN. The following paragraphs describe the processing sequence for programs not compiled in the UCS environment.
The processing sequence begins with the compiled program code transferring control to a processor interface module (PIM). The PIMs consist of compiler run-time library code that connects program input/output requests with an appropriate SFS interface bank. Each language has its own PIM, allowing the compiled code in one language to interact with its PIM differently from the compiled code in another language.
An SRH is responsible for a specific type of file format and its open, close, read, and write functions. These requests let the SFS functions support the variety of input/output statements encountered in different languages.
Figure 3–1 shows a simplified processing chain. Dashed lines represent program flow; solid lines show data flow.
Using Banks, Programs, and Files
7831 0786–003 3–5
After control is transferred to the PIM, the PIM passes the input/output requests to either the C2SFSD$ or the C2SFSM$ bank, which in turn passes the requests to the C2P$ bank. The C2P$ bank refers to the storage control table (SCT) and the file control table (FCT) built by the PIM and builds the Data Definition (DD$) and Data Access (DA$) packets from them.
The SCT and FCT contain file attribute data, such as page size, record size, key size, and file name. This information and other table descriptions are discussed more fully in Section 7. The C2P$ bank converts the SCT and FCT tables to the DD$ and DA$ data packets, which are used by the DSDF and MSAM storage record handlers.
The DD$ packet contains the information needed to define the SFS file and is passed by an OPEN command. The DA$ packet contains the information needed to process an SFS command and is passed by the other SFS commands, such as READ, WRITE or CLOSE. The C2P$ bank calls the SFS intercept and connect routine (ICR) and passes the DA$ and DD$ packets to it.
The SFS ICR intercepts incoming input/output requests and links them with UDS Control code, transferring them to UDS thread control. The ICR also performs the environment switch, preparing the input/output requests to enter the UDS environment and
transferring data between the user program and UDS. If no thread environment exists, UDS thread control sets up a new one.
UDS thread control passes input/output requests, user commands, or threads to the SFS logical data manager (LDM). The SFS LDM translates input/output requests for logical data into requests for a particular file type and passes them to the MSAM or DSDF SRH. The SFS storage record manager is composed of the MSAM and DSDF SRHs. The MSAM and DSDF storage record handlers are SFS components compatible with UDS Control architecture. Each storage record handler translates I/O requests for logical data into requests for physical data and calls on the cache manager to perform I/O operations. The cache manager performs the I/O operations, allocating memory space in the UDS Control buffers, a set of common data bank buffers called a cache.
Figure 3–2 shows a more detailed SFS processing chain for programs compiled in the basic mode programming environment. The dashed lines in Figure 3–2 indicate program flow, and the solid lines show data flow.
As indicated in the diagram, either SFS or PCIOS can be called from the PIM. The processing branch is chosen according to your specification in DFP, or the language syntax. (See 2.6.) ASCII FORTRAN, for example, has syntax which indicates that a file is shared and should be processed by SFS.
Using Banks, Programs, and Files
7831 0786–003 3–7
Define File Processor Functions
The DFP is a stand-alone processor. You can use DFP to provide a data file description external to the program processing the file and to indicate if a file is shared. For more
information on how to use DFP, refer to the DFP Administration and Programming
Reference Manual.
The DFP produces a define file block containing the data file description. A user program processing the data file implicitly refers to the define file block before accessing an SFS module.
When the user program opens the data file, the PIM accesses the define file block and modifies the original program file description from the data stored in it. This process alters file descriptions without recompiling and recollecting programs accessing those files. Defining the file as shared through DFP or language syntax calls SFS.
DSDF Storage Record Handler
The DSDF SRH component of SFS processes DSDF files in a sequential, random, or dynamic access mode. Files created by this component can also be processed by the PCIOS DSDF I/O module or can be read by the PCIOS sequential system data format (SSDF) I/O module. The SFS DSDF SRH can also read and modify DSDF files created by PCIOS.
The data content of items in DSDF file records can be of any data type, since the SFS DSDF storage record handler does not process data in records. Records in a direct access file can vary in size up to a user-specified maximum record size.
MSAM Storage Record Handler
The MSAM SRH component of SFS processes MSAM files in a sequential, random, or dynamic access mode. SFS supports variable-length records in an MSAM file. Records can be processed for any items declared as key fields for the records. Data content of items in indexed records and their key fields can be of any data type. Files created by this module can be processed by the PCIOS MSAM module. Files created by the PCIOS MSAM module can also be processed by the SFS MSAM SRH.
Using Banks, Programs, and Files
3.3.
How SFS Processes UCS Programs
The extended mode programming environment includes programs compiled by UCS COBOL, UCS FORTRAN, UCS C, and UCS Pascal. While processors in the basic mode programming environment require a PIM to access SFS common banks, UCS processors do not have this requirement. The UCS Runtime System includes code that replaces the PIM; the Runtime System calls the SFS ICR directly.
Figure 3–3 shows the SFS interface with UCS programs. Dashed lines represent program flow; solid lines show data flow.
The UCS Runtime System directly creates the DD$ and DA$ packets. Intermediate steps involving an SCT and FCT are unnecessary. The Runtime System presents DD$ and DA$ packets directly to UDS Control. The SFS LDM and the MSAM and DSDF SRHs process the packets in the UDS Control framework.
The UCS Runtime System calls PCIOS or SFS in a way similar to that described in the previous section. You can use DFP to indicate that a file is shared. UCS Runtime System uses the define file block in file DFP$, if present, to update the program specifications for the file. For more information on how to use DFP, see the DFP Administration and Programming Reference Manual.
UCS FORTRAN and UCS COBOL provide syntax that defines a shared file; thus, the DFP does not need to be used.
Using Banks, Programs, and Files
7831 0786–003 3–9
Figure 3–3. SFS Processing of Program Compiled in Extended Mode Programming Environment
Using Banks, Programs, and Files
3.4.
Using Explicit and Implicit Thread Control
Thread control commands (BEGIN THREAD, END THREAD, OMIT THREAD, COMMIT THREAD, and so on) can be executed explicitly in some SFS programs. These programs are described as using explicit thread control. If these thread control commands are not executed explicitly in the program, the software issues these commands implicitly as required by the user commands in the program. These programs are described as using implicit thread control.
In most cases, you can use either explicit or implicit thread control in a program.
However, there are three exceptions to this rule. In the following three cases, you must use explicit thread control:
• DPS or multiple MCB commands are used in an SFS program.
• The SFS program accesses an alternate application group that shares I-banks with
another application group.
• The SFS program contains specified TIP CONNECT and DISCONNECT commands.
In this case, you must specify the TIP CONNECT command before the BEGIN THREAD command and the TIP DISCONNECT command after the END THREAD command.
Using Banks, Programs, and Files
7831 0786–003 3–11
3.5.
Using Multiple Application Groups
You can execute SFS in both the default and alternate application groups. You must install SFS into each application group in which you will execute it. You specify the group SFS is installed in during installation of SFS on your system. See the UDS Configuration Guide for more information about application groups and installation.
Programs compiled in both the basic mode and UCS environment can access SFS either in the default application group or in an alternate application group. However, the method used to indicate the application group in which SFS is executed is different for these two environments.
Two assumptions are made in the following discussions on application groups:
• SFS and RDMS are installed in the default application group without the TEST
keyword on the COMUS INSTALL command.
• SFS and RDMS are installed in alternate application groups with the TEST keyword
on the COMUS INSTALL command.
If SFS and RDMS are installed in the default application group with the TEST keyword, the default application group is treated like an alternate application group. If your site uses an alternate application group in which SFS and RDMS are installed without the TEST keyword, that alternate application group is treated like the default application group.
3.5.1.
Programs Compiled in Basic Mode Environment
Programs compiled in the basic mode environment access the default application group by default. To access an alternate application group, you must include the relocatable element CBEP$$SFS when you collect the program. CBEP$$SFS is the SFS relocatable element produced by an SFS generation that is built for a particular application. This element can be found in file 1 and file 2 of the generated output and in the file in which SFS is installed.
Accessing Alternate Application Groups through ASCII COBOL
Programs
If RDMS is not installed, programs compiled in the basic mode environment cannot issue thread control commands (BEGIN THREAD, END THREAD, OMIT THREAD, COMMIT THREAD) explicitly; the software issues these commands implicitly as required by the user command. These programs are referred to as using implicit thread control commands. In order for these programs to access an alternate application group, you must also include a LIB of the relocatable COBOL library in the program collection. If RDMS is installed, you can use explicit thread commands in your program. With explicit thread commands, you specify an application group name or alias. You must specify these commands in the programs, and then compile and collect them.
Using Banks, Programs, and Files
This user program collection uses the default application group:
@map,a ,test ibank,m user-id,01000 lib cobol-library in .run dbank,dm user-id in .run end where:
cobol-library is the relocatable COBOL library.
run is the relocatable element produced by the COBOL compiler.
The following example illustrates a user program collection to use an alternate application group: @map,a ,test ibank,m user-id,01000 lib cobol-library in .run dbank,dm user-id in .run in abs$.cbep$$sfs end where:
cobol-library is the relocatable COBOL library.
run is the relocatable element produced by the COBOL compiler.
cbep$$sfs is the SFS relocatable element produced by the generation of SFS
for the application group.
Accessing Alternate Application Groups through ASCII FORTRAN
Programs
Using Banks, Programs, and Files
7831 0786–003 3–13
where F$RDMR
is the RDMS entry point.
SQL-command
is the scalar character data item or character constant containing the SQL command.
error-status
is a scalar CHARACTER*4 data item (not a constant) that on exit from the CALL statement contains the status of the command; the value ‘0000’ means normal completion.
auxiliary-information
is a scalar integer data item (not a constant) that on exit from the CALL statement contains additional information depending on the value of error-status.
program-variable-i
is a scalar data item name in the ASCII FORTRAN program that is associated with an RDMS parameter.
An SQL BEGIN THREAD command must precede program commands accessing any SFS file. This command connects the program with UDS Control in the specified application group.
After all SFS files accessed through the program are closed, an SQL END THREAD command must be used. This command disconnects the program from UDS Control.
Using Banks, Programs, and Files
The following example shows a FORTRAN program connecting with application group two.
Note: FORTRAN programs calling F$RDMR must have type-checking enabled. You should include the following statement:
. . . INTEGER COLPOS CHARACTER*4 ERRCOD . . . COMPILER (ARGCHK=00)
CALL F$RDMR('BEGIN THREAD FOR APPLICATION APPTWO;', + ERRCOD, COLPOS) IF (ERRCOD .NE. '0000') GO TO 9999 . . . C (SFS file accesses) . . .
CALL F$RDMR('END THREAD;', ERRCOD, COLPOS) IF (ERRCOD .NE. '0000') GO TO 9999
. . .
The following example shows a MAP of a FORTRAN program relocatable element named ‘ftn-rel’ in TPF$. In this example, it is assumed that the FORTRAN relocatable library is in FTN$ and ‘nnn’ indicates the required application group (for example, one, svn, and so on).
@MAP,F ,ftn-abs
lib ftn$(useri/$odd,userd/$even) ibank,md useri,01000
Using Banks, Programs, and Files
7831 0786–003 3–15
3.5.2.
Programs Compiled with Universal Compiling System
(UCS)
UCS programs can link statically and dynamically to SFS in both the default and alternate application groups. SFS must be installed in the application group before linking to it. Once a program execution begins a step in one application group, it cannot access any other application group.
If the Linking System exists on your system, an SFS generation creates an object module, CBEP$$SFS, which provides the SFS entry points for that generation. This element is installed in file SYS$LIB$*SFSLIB for the default application group and into the file UDS$$nnn*SFSLIB for an alternate application group, where nnn is the application group number (for example, SVN for application group 7).
Also during the SFS installation, COMUS updates the appropriate library search chain (LSC) for the application group. If SFS is being installed into application group 7, for example, SYS$*DATA$.SSDEF$ in part, looks like this (assuming RDMS and DMS are already installed): Define Lsc sfs$app7 Search uds$$svn*sfslib. Define Lsc app$7 Search $local Search rdms$app7 Search dms$app7 Search sfs$app7 . . .
The software executes thread control commands implicitly as needed for user
commands for programs compiled by UCS compilers that do not include explicit thread control commands.
You do not need RDMS to execute explicit thread control commands in programs compiled by UCS compilers. These commands are supported directly by the UCS compiler.
Dynamic Linking to Default Application Group
Default mechanisms automatically resolve external references to the correct application
group when SFS is called. For further information, see the Linking System Programming
Using Banks, Programs, and Files
Static Linking to Default Application Group
You may want to link your program statically to access the default application group. To enhance performance, all TIP and HVTIP programs must be statically linked. As long as the Linking System uses the default SSDEF$ element in file SYS$*DATA$, the program is automatically linked to the correct application group. It does not, however, include a specific object module. To ensure that the default SSDEF$ element is used, do not use a @USE statement to attach the name LINK$PF to a file.
The following example illustrates static linking and execution:
@free link$pf @link ,program
Include program-object-module @eof
@xqt program
where program-object-module is the UCS compiler output.
Linking to Alternate Application Group
Within the SSDEF$ element in SYS$*DATA$ is a search chain called UCS$EMUSER. The search chain includes all products that may be referred to from a UCS product compilation. The ACTIVE$APP entry within the UCS$EMUSER search chain defines the application group being used to define the execution environment.
The default value of ACTIVE$APP is defined in SYS$*DATA$.SSDEF$ when the default application group number is solicited during the Linking System installation. If no answer is given, application group 3 is assumed.
You can override the default ACTIVE$APP value by directing the Linking System to another definition of ACTIVE$APP with a @USE LINK$PF statement. Definitions of the nine possible application groups are installed with the Linking System in unique files, where the file names denote the associated application group and n is the application group number, in the following format:
SYS$LIB$*APP$n
Each file contains a short SSDEF$ element to redefine the default value of ACTIVE$APP. For example, the file holding the branch to application group 7, SYS$LIB$*APP$7,
Using Banks, Programs, and Files
7831 0786–003 3–17
Dynamic Linking to Alternate Application Group
Use the following procedure to link your program dynamically to an alternate application group:
1. Attach a use name of LINK$PF to the appropriate application group file.
2. Execute the object module.
The following example illustrates dynamic linking to application group 7:
@use link$pf.,sys$lib$*app$7. @xqt program-object-module
where program-object-module is the UCS compiler output.
Static Linking to Alternate Application Group
Use the following procedure to link your program statically to an alternate application group:
1. Attach a use name of LINK$PF to the appropriate application group file.
2. Statically link the UCS object module with pertinent link commands. Use a RESOLVE
ALL REFERENCES USING LCN command so that references are resolved using the library code names in LINK$PF.SSDEF$. This enables the Linking System to find the correct definition of ACTIVE$APP.
The following example illustrates static linking to application group 7:
@use link$pf.,sys$lib$*app$7. @link,s ,program
Include program-object-module Resolve all references using lcn Process for extended
Delete all definitions except start$ @eof
@xqt program
Using Banks, Programs, and Files
3.6.
Collecting Multiple Data Model Programs
With UDS, you can write a program that accesses one, two, or all three of its data models: flat file (SFS), network (DMS), and relational (RDMS). A program that accesses more than one data model requires more preparation than a program that calls only one model.
Linking and collecting are processes that resolve references a program makes to programming entities outside the program. Linking goes with the Universal Compiling
System (UCS)also called extended modeprograms and object modules; collecting goes
with the basic mode case.
This subsection explains how to collect and link programs that call more than one data model.
The procedure for collecting a multiple data model program is essentially a combination of the separate procedures.
A program that calls all three data models and accesses the standard application group must be collected with the relocatable files required by each data model manager, as in the following example:
@ACOB program-source, program-relocatable @MAP ,program-absolute LIB cobol-library IBANK,M USERIB,01000 IN program-relocatable IN SYS$LIB$*RSA.RDMR-ACOBDAT IN SYS$LIB$*SFSLIB.CBEP$$SFS IN SYS$LIB$*RSA.CBEP$$RSA DBANK,MC USERDB IN program-relocatable IN SYS$LIB$*DMRMT$.CLSEG$ IN file-name.S$WORK/subschema IN file-name.D$WORKrun-id END where:
Using Banks, Programs, and Files
7831 0786–003 3–19
A program that accesses an alternate application group should be collected with relocatable files from the products’ alternate application files. These are the files into which COMUS installs the products.
To collect a program for a particular application group, you do much the same as in the preceding example. The only difference is that you use the qualifier of your application group instead of the qualifier of the default application group. For example, to collect a program for application group seven, you substitute UDS$$SVN (the recommended qualifier for application group seven) for SYS$LIB$.
Since a request from a program goes through the ICR of the data manager before it reaches the data manager of the desired application group, a program can access one application group even though it is collected with the relocatable elements of another application group. The ICR directs the request to the data manager of the desired application group. RSA has no ICR; therefore, you must collect your program with the version of RDMR-ACOBDAT and CBEP$$RSA for the desired application group.
Using Banks, Programs, and Files
3.7.
Linking Multiple Data Model Programs
This subsection describes two cases: linking to the standard application group and linking to an alternate application group. Two methods of linking are available for each case: dynamic and static.
Before proceeding, consider the following:
• Once a program execution begins a step in one application group, it cannot access
any other application group. If the program is executed again, it may access another application group, but it may access only one application group during that execution.
• You cannot link to DMS, RDMS, or SFS until they are installed in the desired
application group.
3.7.1.
Dynamic Linking to Standard Application Group
Dynamic linking requires no intervention on your part. Default mechanisms automatically resolve external references to the data managers when they are called.
3.7.2.
Static Linking to Standard Application Group
You may want to link your program statically to access the standard application group. One reason may be to improve run-time performance. Also, all TIP/HVTIP transactions must be statically linked. The procedure is similar to that for DMS, with some
modifications for RDMS and SFS:
1. After compiling your program, use the @LINK processor to link it. You do not have to include any DMS, RDMS, or SFS object modules. They are linked automatically, as long as the Linking System uses the default SSDEF$ element
(SYS$*DATA$.SSDEF$). To ensure that it uses SSDEF$, do not use a @USE statement to attach the name LINK$PF to a file.
2. Use an @XQT statement to execute your program.
The following example illustrates static linking of a program to the standard application group.
Step 1
Using Banks, Programs, and Files
7831 0786–003 3–21
3.7.3.
Linking to Alternate Application Group
The execution environment of UCS programs is defined by subsystem definition elements, specifically named SSDEF$ elements. The contents of SSDEF$ elements produced during the installation of the Linking System and each of the products that make up an application group define the execution environment for the application group.
UCS application groups use three tiers in the search process. Users should be aware of how to use the search process to access the appropriate application group. System administrators should read this discussion for background.
For search tier 1, within the SSDEF$ element in SYS$*DATA$ is a search chain called UCS$EMUSER. The search chain includes all products that may be referenced from an UCS product compilation. The ACTIVE$APP entry within the UCS$EMUSER search chain defines the application group being used to define the execution environment. A
segment of element SYS$*DATA$.SSDEF$ follows:
Define lsc UCS$EMUSER Search $ LOCAL Search RTS$EMSRVC Search DPS$LIB Search ACTIVE$APP . . .
For search tier 2, ACTIVE$APP is defined in two ways:
1. The default value of ACTIVE$APP is defined in SYS$*DATA$.SSDEF$ when the
default application group number is solicited during the Linking System installation. If no answer is given, application group 3 is assumed. The resulting entry in the system default SSDEF$ element becomes
Define lsc ACTIVE$APP Search APP$3
2. Users can override the default ACTIVE$APP value by directing the Linking System to
another definition of ACTIVE$APP with a @USE LINK$PF statement. Definitions of the nine possible application groups are installed with the Linking System in unique files, where the file names denote the associated application group in the following format:
SYS$LIB$*APP$n
Using Banks, Programs, and Files
Each file contains a short SSDEF$ element to redefine the default value of ACTIVE$APP. For example, the file holding the branch to application group 1, SYS$LIB$*APP$1, contains the following SSDEF$ element:
Define lsc ACTIVE$APP Search APP$1
Users direct the Linking System to use this alternate definition for ACTIVE$APP by attaching the use name LINK$PF to the SYS$LIB$*APP$1, as follows:
@use link$pf,sys$lib$*app$1
For search tier 3, as each site installs the products that make up the application group or groups, entries are made in the corresponding application group search chain or chains for those products within the system default SSDEF$ element. For example, if DMS, RDMS, MCB, and SFS are installed in application group 1, the following entries appear in element SYS$*DATA$.SSDEF$: Define lsc APP$1 Search $LOCAL Search DMS$APP1 Search RSA$APP1 Search MCB$APP1 Search SFS$APP1
The definition for each application group contains only those products installed
specifically by a site. Some application groups, therefore, may include only the $LOCAL entry; other application groups may contain a number of products, as the preceding example illustrates.
For the user interface, for DMS, RDMS and SFS, the changes entered during the alternate application group generation process result in the creation of the object modules DMSSHELL-BDI/OM, RSAC-UCSEMOM, and CBEP$$SFS, as well as the required changes to COMU$INSTALL, to enable COMUS to update SSDEF$ during the installation of the products.
Dynamic Linking to Alternate Application Group
Use this procedure to link a program dynamically to an alternate application group. The primary use for dynamic linking is to execute an object module.
Using Banks, Programs, and Files
7831 0786–003 3–23
Example
In this example, a UCS COBOL program is to access application group 7, which is accessed through the SSDEF$ element in SYS$LIB$*APP$7:
@use link$pf,sys$lib$*app$7
@ucob source.npe-cobol-program,source.new-object-module @xqt source.new-object-module
Static Linking to Alternate Application Group
Depending on the type of object module desired, users can produce standard object modules, zero overhead object modules (ZOOM), bound object modules, TIP ZOOMs, or HVTIP ZOOMs.
• To produce a standard object module
1. Attach a use name of LINK$PF to the file associated with the appropriate
application group. The file name is SYS$LIB$*APP$n, where n is the application group number from 1 to 9.
2. Statically link the UCS COBOL or UCS FORTRAN object module to produce a
new object module.
3. Execute the new object module.
Example
In this example, a UCS COBOL object module is to access application group 7, which is defined in the SSDEF$ element in SYS$LIB$*APP$7. Moreover, the subschema is defined by an object module named S$WORK.
@use link$pf,sys$lib$*app$7 @link,s ,new-object-module
include file-name.npe-cobol-object-module include file-name.s$work/subschema-name resolve all references using lcn
process for extended
delete all definitions except start$ @eof
@xqt new-object-module
• To produce a zero overhead object module (ZOOM)
1. Attach a use name of LINK$PF to the file associated with the appropriate
application group. The file name is of the form SYS$LIB$*APP$n, where n is the application group number from 1 to 9.
2. Statically link the UCS COBOL or UCS FORTRAN object module to produce a
new object module.
Using Banks, Programs, and Files
Example
In this example, a UCS COBOL object module is to access application group 7, which is defined in the SSDEF$ element in SYS$LIB$*APP$7:
@use link$pf,sys$lib$*app$7 @link,s ,new-object-module
include file-name.npe-cobol-object-module include file-name.s$work/subschema-name resolve all references using lcn
process for extended zoom
delete all definitions except start$ @eof
@xqt new-object-module
• To produce a bound object module
1. Attach a use name of LINK$PF to the file associated with the appropriate
application group. The file name is of the form SYS$LIB$*APP$n, where n is the application group number from 1 to 9.
2. Statically link the UCS COBOL or UCS FORTRAN object module to produce a
new object module. Include the OUTPUT BOUND OM directive.
3. Execute the new object module.
Example
In this example, a UCS COBOL object module is to access application group 7, which is defined in the SSDEF$ element in SYS$LIB$*APP$7:
@use link$pf,sys$lib$*app$7 @link,s ,new-object-module
include file-name. npe-cobol-object-module include file-name.s$work/subschema-name output bound om
resolve all references using lcn process for extended
delete all definitions except start$ @eof
@xqt new-object-module
• To produce a TIP ZOOM
Using Banks, Programs, and Files
7831 0786–003 3–25
Example
In this example, a UCS COBOL fast load ZOOM is to access application group 7, which is defined in the SSDEF$ element in SYS$LIB$*APP$7:
@use link$pf,sys$lib$*app$7 @link,s ,new-object-module
include file-name.npe-cobol-object-module include file-name.s$work/subschema-name output fast load
resolve all references using lcn delete all definitions except start$ @eof
@xqt new-object-module
• To produce an HVTIP ZOOM
1. Attach a use name of LINK$PF to the file associated with the appropriate
application group. The file name is of the form SYS$LIB$*APP$n, where n is the application group number from 1 to 9.
2. Statically link the UCS COBOL or UCS FORTRAN object module to produce a
new object module. Include the OUTPUT HVTIP directive; omit any PROCESS directives.
3. Execute the new object module.
Example
In this example, a UCS COBOL ZOOM is to access application group 7, which is accessed through the SSDEF$ element in SYS$LIB$*APP$7. This is the initial control program (ICP). ZOOM subprograms can also be used if necessary. For an
example of a ZOOM subprogram, see the Linking System Programming Reference
Manual. @use link$pf,sys$lib$*app$7 @link,s ,new-object-module include file-name.npe-cobol-object-module include file-name.s$work/subschema-name output hvtip
resolve all references using lcn delete all definitions except start$ set lowadr = 0200000 for hvtip$$dbank @eof
Using Banks, Programs, and Files
3.8.
A Closer Look at the Processor Interface
Module
For programs compiled in the basic mode programming environment, each processor accessing SFS common banks has its own processor interface module (PIM). Programs compiled in the extended mode environment, however, call the UCS Runtime System, which replaces the PIM and calls the SFS ICR directly for both MSAM and DSDF files. Hence, they do not require a separate PIM for each processor.
Processor run-time libraries contain unique PIMs for these processors: ASCII FORTRAN, ASCII COBOL, IMS 1100, Sort/Merge, QLP, and RPG II.
Check the appropriate processor installation guide to ensure that the PIM supports SFS. Each processor that interacts with a PIM has unique requirements. While PIMs meet specific processor requirements, they perform these general functions:
• Generate the storage control table (SCT), if it was not generated when the program
was compiled.
• Generate the file control table (FCT), if not generated when compiled. Each data file processed must have its own FCT.
• Initialize to zero, at open time, the SCT and FCT fields that do not contain pertinent information for file opening and file processing.
• Allocate space (for buffer and record areas) that was not allocated when compiled.
• Test the validity of the compiler-generated I/O request.
• Perform record editing when necessary.
• Call appropriate SFS functions to perform the I/O request.
• Process error codes returned by SFS.
Using Banks, Programs, and Files
7831 0786–003 3–27
3.9.
SFS Bank Descriptions
The following list reviews the role of each I-bank in the chain of processing:
C2SFSE$ The SFS error message bank. It is called by the PIM for DSDF errors.
C2SFSM$ The MSAM interface bank. C2SFSM$ is called by the language
processors.
C2SFSD$ The DSDF interface bank. C2SFSD$ is called by the language
processors.
C2P$ C2P$ is called by the C2SFSM$ or the C2SFSD$ bank. C2P$
converts SCT and FCT table formats (PCIOS formats) produced by programs compiled in the basic mode environment to the DD$ and DA$ packet formats of SFS.
C2PICR$ The ICR bank. C2PICR$ is called by C2P$, the UCS Runtime System,
IMS 1100, or other banks. The ICR saves the calling environment and routes control to a UDS thread control bank that initiates the thread.
7831 0786–003 4–1
Section 4
SFS Input/Output Operations
This section discusses the following topics:
• How to call SFS
• SFS entry conditions
• DSDF skeletonization
• DSDF commands
SFS Input/Output Operations
4.1.
Calling SFS
Before calling SFS, the UCS Runtime System in the extended mode environment sets up the correct environment, initializes registers, sets up the SFS request packet, and then calls the SFS ICR.
In the basic mode environment, the SFS C2P bank sets up this environment before the SFS ICR.
4.1.1.
Setting Up Environment
These bank descriptor registers are used:
BDR0 Calling bank/C2PICR$ bank
BDR1 Unspecified
BDR2 User D-bank
BDR3 Unspecified
On return from SFS, the calling environment is restored.
4.1.2.
Initializing Registers
SFS uses two registers:
X11 Caller bank descriptor index (BDI), caller return address
A0 Address of the request packet, DD$ or DA$
4.1.3.
Setting Up Request Packet
The DD$ or DA$ request packet contains the parameters for the SFS command. (See 7.6 and 7.7 for detailed descriptions of these packets.) Every command generates different parameters. The OPEN command, which is always the first command, is the only one that passes the DD$ packet. Each READ, START, WRITE, DELETE, REWRITE, and CLOSE command passes the DA$ packet.
SFS Input/Output Operations
7831 0786–003 4–3
4.1.4.
Calling the SFS ICR
All SFS commands for both MSAM and DSDF files share a common entry point to the SFS ICR.
The calling sequence is
L A0,request-packet-address LXI,U X11,C2PICR$
LIJ X11,UDSC$PCI$ICR
C2PICR$ is the BDI of the SFS ICR bank. UDSC$PCI$ICR is the entry point to the SFS ICR.
The SFS ICR saves these registers
