unisys OS 2200 Shared File System (SFS 2200) Administration and Support Reference Manual imagine it. done. Release Level 4R1 June

Transcription

1 unisys imagine it. done. OS 2200 Shared File System (SFS 2200) Administration and Support Reference Manual Release Level 4R1 June

2 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. Unisys is a registered trademark of Unisys Corporation in the United States and other countries. All other brands and products referenced in this document are acknowledged to be the trademarks or registered trademarks of their respective holders.

3 Contents Section 1. About This Manual 1.1. Documentation Updates Prerequisites Section 2. Introducing SFS 2.1. What Is SFS? Benefits of SFS Who Should Use SFS? Related Software Products SFS File Features SFS Requirements Using SFS to Access Files Created with PCIOS Example of DSDF File Access Example of MSAM File Access Changing Computed Block Size with DFP TIP Processing with SFS Defining TIP Files Registering and Reserving TIP Files Defining a Storage Area Specifying the Storage Area Name in a Program Passing the Storage Area Name to SFS Summary Section 3. Using Banks, Programs, and Files 3.1. SFS Banks Processing Programs Compiled in Basic Mode Programming Environment How SFS Processes UCS Programs Using Explicit and Implicit Thread Control Using Multiple Application Groups Programs Compiled in Basic Mode Environment Programs Compiled with Universal Compiling System (UCS) Collecting Multiple Data Model Programs Linking Multiple Data Model Programs Dynamic Linking to Standard Application Group Static Linking to Standard Application Group Linking to Alternate Application Group A Closer Look at the Processor Interface Module SFS Bank Descriptions iii

4 Contents Section 4. SFS Input/Output Operations 4.1. Calling SFS Setting Up Environment Initializing Registers Setting Up Request Packet Calling the SFS ICR Performing I/O Operations on DSDF Files DSDF Skeletonization DSDF Input/Output Processing DSDF OPEN FILE Command General Rules for OPEN Command DSDF READ RECORD Command DSDF READ NEXT RECORD Command DSDF REWRITE RECORD Command DSDF DELETE RECORD Command DSDF WRITE RECORD Command DSDF START Command DSDF CLOSE FILE Command Performing I/O Operations on MSAM Files MSAM Input/Output Processing MSAM OPEN FILE Command MSAM READ RECORD Command MSAM READ NEXT RECORD Command MSAM WRITE RECORD Command MSAM REWRITE RECORD Command MSAM DELETE RECORD Command MSAM START Command MSAM CLOSE FILE Command Section 5. Recovering SFS Files 5.1. SFS File Recovery The UDS Recovery Model How Recovery Works Rollback Short and Long Recovery Deferred Updates Quick-Looks Audit After-Looks Managing Rollback in COBOL Programs Using SFS COBOL USE Procedure Sample COBOL Program with USE Procedure Section 6. SFS Locking 6.1. How SFS Locks Shared Files Lock Granularity How Usage Mode Determines File Locking Page Lock Function Factors Controlling Lock Duration iv

5 Contents Recovery Unit COMMIT Command Implicit End Thread Page Lock Duration Explicit End Thread SFS Locking Summary Exclusive and Protected File Locks Exclusive and Protected Page Locks Special SFS MASM Routines Exclusive Open Mode Protected Open Mode Read and Unlock Sample ACOB Program ACOB Source Program Collecting ACOB Programs with SFS MASM Routine Section 7. SFS Control Tables 7.1. SFS Control Table Usage Storage Control Table Format for DSDF Storage Control Table Format for MSAM Save Area Record (SAR) Operation Control Block (OCB) File Control Table Format for DSDF File Control Block Format for DSDF Buffer Control Block Format for DSDF File Control Table Format for MSAM File Control Block Format for MSAM Buffer Control Block Format for MSAM Indexed Key Table (IKT) Format for MSAM Key Type Packets Data Definition Packet Format Data Definition Table Format Environment Table Format MSAM Index Table Format Value Table Format ENAME Table Format Status Table Format Data Access Packet Format Section 8. Data File Formats 8.1. Accessing SFS Files DSDF File Contents DSDF File Layout DSDF Label Record Format DSDF Record Control Word Format Data Record Control Word Format Special Record Control Word Format End-of-File Record Format v

6 Contents 8.7. Multi-Indexed Sequential Access Method (MSAM) File Contents Information Block Contents Label Area Format Indexed Key Table Area Contents Statistics Table Contents Partially Filled Data Block List Index Block Structure Data Block Structure File Size Considerations MSAM Record Placement MSAM Programming Considerations Section 9. SFS Error Processing 9.1. Error Processing in Basic Mode Programming Environment C2SFSERR Error Word Format for DSDF Files C2SFSERR Status Codes for DSDF Files PIM Error Code Processing Status Information for MSAM Files Compiled in Basic Mode Programming Environment MSAM Error Codes in Basic Mode Programming Environment Program Error Processing for UCS Programs Status/Area Format UCS DSDF Error Messages UCS MSAM Error Messages MSAM and DSDF Status Codes Returned by LDM 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 A.4.2. Example 2: MSAM Record and Audit Sizing... A 2 A.5. Using DFP to Override Computed ACOB Block Size... A 4 Appendix B. Restrictions and Operational Considerations Glossary... 1 Index... 1 vi

7 Figures 3 1. Simplified Processing Sequence for Program Compiled in Basic Mode Programming Environment Processing of Program Compiled in Basic Mode Programming Environment SFS Processing of Program Compiled in Extended Mode Programming Environment Recovery Model Storage Control Table Storage Control Table Format Save Area Record Format Operation Control Block File Control Table File Control Block Buffer Control Block for DSDF File File Control Block for MSAM Buffer Control Block for MSAM MSAM Indexed Key Table, Fixed Portion Variable-Length Portion of IKT Data Definition Packet Data Definition Table Environment (ENV) Table MSAM Index Table MSAM Index Table Key Packet Value Table ENAME Table Status Table Data Access Packet DSDF File Layout DSDF Label Record Format Data Record Control Word Format Special Record Control Word Format EOF Record Control Word Format MSAM Information Block Format MSAM Label Area Format MSAM Index Block Format MSAM Data Block Format Error Word Format vii

8 Figures viii

9 Tables 3 1. SFS I-Banks Permissible DSDF Input/Output Commands Permissible MSAM Input/Output Commands File Usage Mode Compatibility Lock Duration File Usage and Locking Strategy HDR1 Format Statistics Table Contents Contents of Partially Filled Data Block List C2SFSERR Status Codes Status Field 1 Conditions for Basic Mode Programming Environment Status Field 2 Conditions for Basic Mode Programming Environment MSAM Error Codes in Basic Mode Programming Environment Status Field 1 Conditions Status Field 2 General Conditions Conditions for Status Fields 1 and UCS DSDF Status Conditions UCS MSAM Status Conditions MSAM and DSDF Status Codes ix

10 Tables x

11 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 Documentation Updates This document contains all the information that was available at the time of publication. Changes identified after release of this document are included in problem list entry (PLE) To obtain a copy of the PLE, contact your Unisys service representative or access the current PLE from the Unisys Product Support Web site: Note: If you are not logged into the Product Support site, you will be asked to do so

12 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

13 Section 2 Introducing SFS This section describes the Shared File System (SFS) and discusses the following topics: Benefits of SFS Attributes of shared files How to create a shared file

14 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 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. Implementation of the Relative I-O Module and Indexed I-O Module section from the American National Standard COBOL, X This standard dictates rules for features such as language syntax and error codes Who Should Use SFS? SFS benefits users wanting concurrent access to data files. Shared file usage increases processing throughput. If you access MSAM or DSDF files through ASCII COBOL, ASCII FORTRAN, IMS, UCS COBOL, UCS FORTRAN, UCS C, or UCS Pascal, you can take advantage of SFS filesharing features

15 Introducing SFS 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 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 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

16 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 statement to prevent data corruption if the cache disk subsystem should fail 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. If the file is defined with a domain of USER-UDS, it may be assigned (@ASG,A) to the run. If the file is defined with a domain of USER, the file must be assigned to the run. For example, assume that a COBOL program contains this SELECT statement: SELECT MASTERFILE ASSIGN TO A-SHARED-FILE PAYROLL

17 Introducing SFS Before you execute the program, you must do the 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 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

18 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 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 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 CREATE SCHEMA SFS. CREATE STORAGE-AREA D-FILE FOR SCHEMA SFS. ADD FILE-TYPE EXEC. ADD DATA-FORMAT DSDF. ADD AUDITED TRUE. ADD DOMAIN USER-UDS. ADD PAGE-SIZE ADD RECOVERED TRUE. PROCESS STORAGE-AREA D-FILE FOR SCHEMA SFS INSTALL. EXIT

19 Introducing SFS 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-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 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 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 ADD RECOVERED TRUE. PROCESS STORAGE-AREA M-FILE FOR SCHEMA SFS INSTALL. EXIT. Step 3 Use DFP to define file SFS*M-FILE as M-FILE.,DFP$. SHARE = YES END

20 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-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 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 FILENAME.,PROGRAM-FILE. BLOCK=896/////WORDS SHARE=YES END 2. Put a use name of DFP$ on the file containing the define file 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. SFS uses a one-track block size (1,792 words) for a DSDF file. This cannot be changed by using DFP or by specification in the user program

21 Introducing SFS 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 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 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 application-number TREG TIP$SFS*M-FILE1.,fix RES,G 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

22 Introducing SFS 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 TIP$SFS*M-FILE1.,F///999 Step 2 Now, define an FDT for the storage 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 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 commands

23 Introducing SFS 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 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 M-FILE1.,TIP$SFS*M-FILE1. Method 2 If you do not 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

24 Introducing SFS 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 method, make sure that file names used in SELECT clauses are unique across all programs. 5. Never use a TIP$SFS qualifier as the qualifier for an Exec file

25 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 Processor interface module (PIM) functions

26 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$ C2PICR$ C2SFSD$ C2SFSE$ C2SFSM$ This bank converts old table formats to new SFS formats. Intercept and connect routine (ICR) bank for SFS DSDF interface bank Bank containing C2ERR messages MSAM interface bank Language processors in both extended mode and basic mode programming environments can call SFS banks (see 3.3 and 3.4)

27 Using Banks, Programs, and Files 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

28 Using Banks, Programs, and Files Figure 3 1. Simplified Processing Sequence for Program Compiled in Basic Mode Programming Environment

29 Using Banks, Programs, and Files 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

30 Using Banks, Programs, and Files Figure 3 2. Processing of Program Compiled in Basic Mode Programming Environment

31 Using Banks, Programs, and Files 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

32 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

33 Using Banks, Programs, and Files Figure 3 3. SFS Processing of Program Compiled in Extended Mode Programming Environment

34 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

35 Using Banks, Programs, and Files 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 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

36 Using Banks, Programs, and Files This user program collection uses the default application ibank,m user-id,01000 lib cobol-library in.run dbank,dm user-id in.run end where: cobol-library run is the relocatable COBOL library. is the relocatable element produced by the COBOL compiler. The following example illustrates a user program collection to use an alternate application ibank,m user-id,01000 lib cobol-library in.run dbank,dm user-id in.run in abs$.cbep$$sfs end where: cobol-library run cbep$$sfs is the relocatable COBOL library. is the relocatable element produced by the COBOL compiler. is the SFS relocatable element produced by the generation of SFS for the application group. Accessing Alternate Application Groups through ASCII FORTRAN Programs You can access SFS in an alternate application group using Structured Query Language (SQL) commands in an ASCII FORTRAN program. SQL commands are described in detail in the RDMS SQL Programming Reference Manual and the RDMS Administration Guide. Each SQL command used in an ASCII FORTRAN program is placed in a CALL statement to the RDMS entry point. The format is as follows: CALL F$RDMR (SQL-command, error-status, auxiliary-information, program-variable-1, program-variable-2,...)

37 Using Banks, Programs, and Files 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

38 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 C (SFS file accesses)... CALL F$RDMR('END THREAD;', ERRCOD, COLPOS) IF (ERRCOD.NE. '0000') GO TO 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 lib ftn$(useri/$odd,userd/$even) ibank,md useri,01000 $odd in tpf$.ftn-rel in uds$$nnn*sfslib.cbep$$sfs in uds$$nnn*rsa.cbep$$rsa in uds$$nnn*rsa.rdmr-acobdat dbank,mcd userd $even in tpf$.ftn-rel in uds$$nnn*sfslib.cbep$$sfs in uds$$nnn*rsa.cbep$$rsa in uds$$nnn*rsa.rdmr-acobdat end

39 Using Banks, Programs, and Files 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 Reference Manual

40 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 statement to attach the name LINK$PF to a file. The following example illustrates static linking and 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 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, contains the following SSDEF$ element: Define Lsc ACTIVE$APP Search APP$7 You direct the Linking System to use this alternate definition for ACTIVE$APP by attaching the use name LINK$PF to the SYS$LIB$*APP$7, as l ink$pf,sys$lib$*app$7 For further information, see the Linking System Programming Reference Manual