AllFusion CA-Vollie. Systems Programmer Guide 5.0 VSE F E

Transcription

1 AllFusion CA-Vollie Systems Programmer Guide 5.0 VSE F E

2 This documentation and related computer software program (hereinafter referred to as the Documentation ) is for the end user's informational purposes only and is subject to change or withdrawal by Computer Associates International, Inc. ( CA ) at any time. This documentation may not be copied, transferred, reproduced, disclosed or duplicated, in whole or in part, without the prior written consent of CA. This documentation is proprietary information of CA and protected by the copyright laws of the United States and international treaties. Notwithstanding the foregoing, licensed users may print a reasonable number of copies of this documentation for their own internal use, provided that all CA copyright notices and legends are affixed to each reproduced copy. Only authorized employees, consultants, or agents of the user who are bound by the confidentiality provisions of the license for the software are permitted to have access to such copies. This right to print copies is limited to the period during which the license for the product remains in full force and effect. Should the license terminate for any reason, it shall be the user's responsibility to return to CA the reproduced copies or to certify to CA that same have been destroyed. To the extent permitted by applicable law, CA provides this documentation as is without warranty of any kind, including without limitation, any implied warranties of merchantability, fitness for a particular purpose or noninfringement. In no event will CA be liable to the end user or any third party for any loss or damage, direct or indirect, from the use of this documentation, including without limitation, lost profits, business interruption, goodwill, or lost data, even if CA is expressly advised of such loss or damage. The use of any product referenced in this documentation and this documentation is governed by the end user's applicable license agreement. The manufacturer of this documentation is Computer Associates International, Inc. Provided with Restricted Rights as set forth in 48 C.F.R. Section , 48 C.F.R. Sections (c)(1) and (2) or DFARS Section (c)(1)(ii) or applicable successor provisions. First Edition October Computer Associates International, Inc. All rights reserved. All trademarks, trade names, service marks, and logos referenced herein belong to their respective companies.

3 Contents Chapter 1. Introduction CA-Vollie Components Additional Information Documentation Overview Command Notation Chapter 2. Online Libraries (OLLs) Description of OLLs Maintenance of OLLs and Members Extend Your OLL File Chapter 3. System-Level Commands Set or Change the Status of an OLL File Set or Change the Status of OLL Members Dequeue a CA-LIBRARIAN Master File Chapter 4. The SYSTEM and USRSGNON Commands The SYSTEM Command CA-Vollie Customization File Table Customization VOICE Procedure Installation HELP File Installation CMS Interface Installation Optional CA-Vollie Interfaces Extended Command Table CA-Vollie Exits Create/Update Translate Table Member Sign On Information System Information The USRSGNON Command Chapter 5. Sign on Processing and Procedures Sign On Processing Sign On Procedures (OLLXSOP) Chapter 6. Printer Definition Chapter 7. User Exits The Command Exit The VSE LIBRARY UPDATE Command Exit The SUBMIT Command Exit The CA-LIBRARIAN UPDATE Command Exits Chapter 8. National Language Support Language Repositories Chapter 9. CA-LIBRARIAN Update Logging Facility Contents iii

4 9.1 Enable Update Logging Facility Extra-Partition Data Set(s) Use Chapter 10. CA-Vollie Interface Program (VIP) VIP Routines and Coding Conventions Link-Edit User-Written Programs Execute a User-Written Program Chapter 11. Dynamic Logon Facility Dynamic Logon Functions Dynamic Logon for Color Terminals Supported Terminal Types Chapter 12. The OLLXCEMT Program Invoking OLLXCEMT Chapter 13. Troubleshooting CA-TCC (CA-Total Client Care) CA-TLC: Total License Care Customer Service System (CSS) Calling Technical Support Generating a Problem Report Product Releases and Maintenance Requesting Enhancements Index X-1 iv AllFusion CA-Vollie Systems Programmer Guide

5 Chapter 1. Introduction AllFusion CA-Vollie is an online program development system that runs as an application task with IBM's CICS (Customer Information Control System) under VSE with VSE/POWER or as a bridge to the CMS operating environment. Note: Throughout this guide, any references to: AllFusion CA-Vollie, will simply be referred to as CA-VOLLIE. AllFusion CA-Panvalet, will simply be referred to as CA-Panvalet. AllFusion CA-Librarian, will simply be referred to as CA-Librarian. The Systems Programmer Guide describes the CA-Vollie system and how to operate it under CICS in VSE/SP and VM/CMS environments. It is intended for the individual(s) responsible for maintaining CA-Vollie. Chapter 1. Introduction 1-1

6 1.1 CA-Vollie Components 1.1 CA-Vollie Components The major components of CA-Vollie include: an online library (OLL) system. CA-Vollie's library system consists of one or more online library (OLL) files. This permanent, restorable file system can be accessed by all CA-Vollie users. While you have the option of allowing users to access and work with more than one OLL, each user is automatically associated with a specific OLL at signon. All of the data the users enters is stored in a compressed format as a member in that OLL. Each member can contain a maximum of 65,000 data lines. Note that this space is not pre-allocated; a member occupies no space until it is created. When a member is deleted, the space it occupied is immediately freed and available for use. Each OLL consists of: private libraries. The members that a user creates are stored in his or her own private library. Each member is internally qualified with the user's unique operator identification (opident) provided by the CICS signon table. This unique opident guarantees that members are distinguishable from members created by other CA-Vollie users. a shareable library. The 'shareable' library contains members that can be accessed by any CA-Vollie users but can only be created, modified, and deleted by certain designated users. (To distinguish shareable members, they are stored with opident &&&.) Shareable members might include, for example, common JCL procedures. a VOICE procedure library. VOICE procedures are stored in the VOICE library under opident %%%. Any individual authorized to use VOICE can execute these procedures. However, only specifically authorized individuals can add, view, copy, modify, and delete procedures from this library. Note: Authorization to place members in the shareable library and to execute and/or manage VOICE procedures is established via SAFE, described in the CA-Vollie Security Guide. online editing facilities. Members created in an OLL can contain any type of data. Data can be displayed in either a modifiable or non-modifiable form. When the data is modifiable, users can use the editing facilities and CA-Vollie commands and line editing commands to manipulate data. a high-level, interactive programming language: VOICE. 1-2 AllFusion CA-Vollie Systems Programmer Guide

7 1.1 CA-Vollie Components VOICE (the CA-Vollie Online Interactive Command Executor is a high-level, interactive language. It supports full arithmetic capability, built-in functions and a variety of variable types. It also has facilities that allow you to create, display and retrieve a formatted panel, read from and write to the terminal and/or an OLL member. Finally, all CA-Vollie commands can be included in VOICE procedures. This means that by executing a single VOICE procedure, you can perform virtually any task that you can perform during a CA-Vollie session. See the VOICE Language Guide for additional information. access to data from other sources. CA-Vollie allows you to access data from: IBM libraries With CA-Vollie, users can access IBM libraries. They can display a member at their terminal, copy a member to an OLL member, modify the contents of that member with CA-Vollie commands and then return it to the same or a different library. CA-LIBRARIAN master files CA-Vollie lets users manipulate CA-LIBRARIAN modules in a variety of ways. They can display, copy and modify CA-LIBRARIAN modules and then update the module on the master file. CA-DATADICTIONARY - With CA-Vollie, users can copy a record, key or element from CA-DATADICTIONARY to an OLL member. They can also include CA-DATADICTIONARY data as all or part of a job that you submit for execution. CA-PANVALET - CA-Vollie can be used to display, copy and modify CA-PANVALET members. job entry and output facilities. CA-Vollie provides a variety of syntax checkers that allow users to verify their JCL and/or programming language source code before submitting it for execution. Once a job is submitted, CA-Vollie allows users to manipulate VSE/POWER input and output queues. They can: display or delete job input directly from the READER, PUNCH, TRANSMISSION, or LIST queues. retrieve the output of any job directed to a predefined output class from the VSE/POWER data file and display it. copy output to an OLL member. Chapter 1. Introduction 1-3

8 1.2 Additional Information 1.2 Additional Information In addtion to component information, this guide also describes: the Online Libraries (OLLs) and the Batch Utility program used to maintain those libraries. (See Chapter 2 for additional information.) system-level commands that can be used by the systems programmers maintaining CA-Vollie. (See Chapter 3 for additional information.) how to use the SYSTEM command to perform online customization, maintenance, and installation. And, how users can issue the USRSGNON command to remove their own Sign On records. (See Chapter 4 for additional information.) CA-Vollie signon processing and both global and user signon procedures. (See Chapter 5 for additional information.) how to define system line printers and CICS terminal printers to CA-Vollie using a printer definition table. (See Chapter 6 for additional information.) user exits and how you can write exit routines to control the use of specific CA-Vollie commands and facilities. (See Chapter 7 for additional information.) how to customize CA-Vollie to display its messages, titles, headers, and more, in different languages. (See Chapter 8 for additional information.) the CA-LIBRARIAN Update Logging Facility that enables log files to be created for all input and/or output of an immediate CA-LIBRARIAN update. (See Chapter 9 for additional information.) the CA-Vollie Interface Program (VIP) which allows you to write programs to retrieve data from an OLL. (See Chapter 10 for additional information.) the Dynamic Logon Facility which provides a dynamic logon facility for users not defined in the TCT, and support for color video terminals. (See Chapter 11 for additional information.) the OLLXCMT program that is used to call CEMT from a VOICE procedure. (See Chapter 12 for additional information.) steps to follow if you encounter any problems with CA-Vollie. (See Chapter 13 for additional information.) 1-4 AllFusion CA-Vollie Systems Programmer Guide

9 1.3 Documentation Overview 1.3 Documentation Overview This manual is part of a comprehensive documentation set that fully describes the features and functions of CA-Vollie and explains how to perform everyday tasks. For a complete list of CA-Vollie manuals see the PDF Table of Contents file in the PDF directory, or the Bookmanager Bookshelf file in the Books directory. Chapter 1. Introduction 1-5

10 1.4 Command Notation 1.4 Command Notation The statement syntax described in this manual uses the following notation conventions: Syntax UPPERCASE MIXed Cases underline lowercase Description Identifies statement, operand or keyword values which must be coded exactly as shown. Identifies statement, operand or keyword abbreviations. The uppercase letters are the minimum abbreviation; lowercase letters are optional. Indicates a default value that you need not supply. Indicates a variable for which a value must be supplied. [ ] Indicates optional keywords, operands or parameters from which you may select one. { } Indicates required keywords, operands or parameters from which you must select one. 1-6 AllFusion CA-Vollie Systems Programmer Guide

11 Chapter 2. Online Libraries (OLLs) This chapter describes the: CA-VOLLIE online libraries (OLLs). This includes: Information about OLL space requirements How to change space allocations Cross-partition protection techniques. Information on expanding the size of an OLL file. Batch Utility which can be used to maintain OLLs and individual OLL members. Chapter 2. Online Libraries (OLLs) 2-1

12 2.1 Description of OLLs 2.1 Description of OLLs An OLL is a direct access file or a VSAM file with a fixed block size of 960 bytes. CA-VOLLIE directly accesses an OLL on both CKD and FBA devices. The first OLL that must be formatted (using the CA-VOLLIE Batch Utility) is the SYSTEM OLL. The SYSTEM OLL contains the definitions for all OLLs defined to CA-VOLLIE and the customization information from the SYSTEM command. The SYSTEM OLL must be formatted before anyone can sign on to CA-VOLLIE. There can be only one SYSTEM OLL; however, there may be any number of other OLLs. Any OLL that has been formatted can be the SYSTEM OLL. CA-VOLLIE locates the SYSTEM OLL by searching for a // DLBL VSYSOLL (and EXTENT) statement in the CICS JCL or standard label area Relocating the System OLL To relocate the System OLL, perform the following steps: 1. Shut down all CICSs in all partitions and systems that use the System OLL to be relocated. 2. Run a CLOSE /ALL/ job in each partition where a CICS was running. Use CAVLCALL.Z from the CA-VOLLIE install library as a model. 3. Backup the System OLL, you may use job CAVLBSO.Z from the CA-VOLLIE Install library as a model. 4. Format and Restore the System OLL at the new location, you may use job CAVLRSO.Z from the CA-VOLLIE Install library as a model. This job will also reload the file table. 5. Update the standard labels or all CA-VOLLIE batch jobs and CICS JCL to include the new location of the System OLL. The System OLL is identified using // DLBL VSYSOLL. See the CA-VOLLIE Installation Guide for more information on the JCL requirements of the System OLL. 6. Submit the CICS startup job(s) to restart CICS Relocating other OLLs (non-system OLL) To relocate a non-system OLL, perform the following steps: 1. Issue the following CA-VOLLIE commands to close the OLL in each CICS partition: SET CLOSE OLL=oll SET OFFLINE OLL=oll 2-2 AllFusion CA-Vollie Systems Programmer Guide

13 2.1 Description of OLLs If some members are in use, the SET CLOSE command will fail. Use SET CLOSE MCB to close individual members or shut down all CICSes and run a CLOSE /ALL/ job in each partition where a CICS was running. 2. Backup the OLL, you may use job CAVLBUO.Z from the CA-VOLLIE Install library as a model. 3. Format and Restore the OLL at the new location, you may use job CAVLRUO.Z from the CA-VOLLIE Install library as a model. 4. Submit the CICS startup job(s) to start CICS. If the OLL is a VSAM file, the standard labels or the CICS JCL has to be updated to include the new datasetname or VSAM catalog name. 5. Specify the information of the relocated OLL in the CA-VOLLIE table, use the CA-VOLLIE System command, option 2. File Table Customization. 6. Use the SET command to delete the OLL from the filetable loaded in memory, and add it with the new VOLSER. SET DELETE OLL=oll SET ADD OLL=oll DSN=datasetname VOL=volser SHA=Y TYPE=type SET ONLINE OLL=oll SET OPEN OLL=oll DEFINE OLL=oll OLL Protection With this commands, the relocated OLL may be used immediately. CA-VOLLIE allows you to update an OLL simultaneously from one or more batch or online partitions in the same or different CPU. CA-VOLLIE provides cross-partition protection for simultaneous updates in the same library. CA-VOLLIE uses the LOCK macro to protect the online library. The resource name is the OLL name; FAIL=RETURN is issued to avoid placing the partition into a wait state. If the OLL is defined as shared between CPUs, SCOPE=EXT is specified in the LOCK macro to protect the OLL during access by multiple CPUs and/or VM machines. In all other cases, SCOPE=INT is specified. Note: CA-VOLLIE does not automatically provide cross-partition protection on an OLL for either a backup run or a full restore run. You must prevent access to an OLL by using the SET OFFLINE command in all the CPUs and/or VM machines. Chapter 2. Online Libraries (OLLs) 2-3

14 2.2 Maintenance of OLLs and Members 2.2 Maintenance of OLLs and Members This section describes how you can use the CA-VOLLIE Batch Utility program to access and maintain the OLL files at your site. The Batch Utility program operates in any batch partition and is not under the control of CICS. Specifically, this section contains: a summary of the maintenance operations you can perform using the Batch Utility. descriptions of the operations you can perform. Each operation is initiated by a control statement, which are described in subsequent sections. Note that while each section begins with a list of the related control statements, the descriptions are presented in alphabetical order by the operation being performed. the information needed to execute the Batch Utility Summary of Maintenance Operations The following tables introduce the types of operations you can performed via the Batch Utility program. The descriptions of these operations are presented in subsequent sections in the alphabetical order of their operations Control Area - Backup and Restore Statement BACKUP BKUPLIB BKUPLST BKUPPCH RESTORE RESTREN SELBKUP SELREST Operation Creates a backup file containing all of the members on an OLL. Writes library directory information about a backup file to an auxiliary list file. Writes the contents of members on a backup file to an auxiliary list file. Writes the contents of members on a backup file to a punch file. Restores all of the members from a backup file. Restores a member from a backup file and renames it on the OLL. Creates a backup file containing one or more OLL members or all of the members associated with an opident. Restores one or more members or all of the members associated with an opident from a backup file to an OLL. 2-4 AllFusion CA-Vollie Systems Programmer Guide

15 2.2 Maintenance of OLLs and Members Control Area - File Statement CHGNAME CLOSE EXTEND FORMAT OPEN SPACE Operation Changes the name of an OLL. Closes OLLs after an abnormal termination. Expand the size of your OLL file. Formats an OLL. (Described in Installation Guide.) Opens an OLL for processing. Writes the number of total blocks on the file and/or the number of unused blocks on a specific OLL Control Area - Member Statement ADD DELETE LIBRARY LIST PUNCH SCAN Operation Adds a member to an OLL. Deletes one or more members, or all member for an opident, from an OLL. Writes library directory information to an auxiliary list file. Writes all or part of a member, or all members associated with an opident, to an auxiliary list file. Writes all or part of a member to the punch file. Searches all members of one or more opidents for a character string Other Control Areas Statement ALTINP LMINDEX RECOVER RELOAD RESET SAFEID Operation Allows the Batch Utility to read data from a tape, disk or FBA device. Writes an index listing of modules residing on a specific CA-LIBRARIAN master file to an OLL. Restores SAFE profiles. (Described in the Security Guide.) Reloads the CA-VOLLIE File Table into the SVA without requiring an IPL. Resets CA-VOLLIE definitions changed via the SYSTEM command to their default values. Assigns password. (Described in the Security Guide.) Chapter 2. Online Libraries (OLLs) 2-5

16 2.2 Maintenance of OLLs and Members Statement USERID Operation Specifies the opident to be used by all subsequent member names specified without an opident Executing the Batch Utility You may execute the Batch Utility while the CICS Monitor is running and an OLL is open under the Monitor Control Statement Requirements All CA-VOLLIE Batch Utility control statements have the following general format: statement operand(s) A control statement can begin in any column and must be separated from its operand(s) by one or more blanks. Operands cannot extend beyond column 72 and must be separated from each other by either blanks or commas. No continuations are permitted. The Batch Utility can process an unlimited number of control statements in a single execution. Statements can appear in any order unless otherwise noted. Specifying the Opident Each member on an OLL has a three-character operation identifier (opident) associated with it. You can specify the opident by: Placing it in front of a member name and separating it from the name by a period, as in ABC.TESTMEM Placing it in a USERID control statement. This opident is then used with all member names that do not explicitly include an opident. sk To change the opident specified in a USERID statement, place a new USERID statement in the input stream where the change should occur. Note: If you do not use a USERID control statement, you must specify an opident in front of any member name or the request is rejected. Referring to Members in the Shareable and VOICE Libraries All shareable members are stored under the opident &&&. All members in the VOICE library are stored under the opident %%%. You can specify the &&& or %%% opidents in the same manner as any other opident (i.e., by specifying an ampersand (&) or percent sign (%) via a USER control 2-6 AllFusion CA-Vollie Systems Programmer Guide

17 2.2 Maintenance of OLLs and Members statement or in front of a member name). For example, you could specify the control statements: USER ABC ADD &MASTDEF... DELETE %TEST LIST OLDMEM JCL Requirements In this example, the opident ABC will be used with any member name that does not include an opident (e.g., OLDMEM). &MASTDEF identifies the shareable member MASTDEF; %TEST identifies the VOICE library member TEST. Note: &MASTDEF is equivalent to &&&.MASTDEF and %TEST is equivalent to %%%.TEST. The Batch Utility has the following JCL requirements: Invoke the Batch Utility under VSE with the following statement: // EXEC OLLX61,SIZE=(AUTO,48K) If you changed the phase name prefix of the CA-VOLLIE phases, you must change the letters OLLX on the EXEC statement accordingly. Input is read from SYSIPT or from an unlabeled tape. Punched output consists of 81-byte records and is written to SYSPCH using DTFDI. Two separate listings are produced by the CA-VOLLIE Batch Utility: 1. the main listing, which consists of control statements and related messages, and is written to SYSLST; and 2. the auxiliary listing, which contains output produced from the LIST and LIBRARY commands, and is written to logical unit SYS005. The two listings should be assigned to different printers, if two printers are available. Note: If you do not assign the output to be written to logical unit SYS005, all listings are written to SYSLST using DTFDI and have a maximum line length of 120 characters. You must provide assign, label, and extent information for the OLL you want to access. For a CKD device, the DLBL statement must contain the operand DA. For an FBA device, the DLBL statement must contain SD. The logical unit must Chapter 2. Online Libraries (OLLs) 2-7

18 2.2 Maintenance of OLLs and Members be SYS004, and the file name must match the File Table entry. For a VSAM OLL, change the DLBL statement as follows: // DLBL ollname,'library name',,vsam,cat=catname DLBL and EXTENT information is required for VSYSOLL to define the SYSTEM OLL in case a File Table load must be performed. If a selective restore/backup is to be performed, you must provide assign and label information for the backup file. The logical unit must be SYS010 and the file name must be OLLBKUP. It is your responsibility to determine the identity of the latest backup file. A sample input stream for an execution of the CA-VOLLIE Batch Utility is: // ASSGN SYS5,X'CUU' // DLBL VSYSOLL,'vollie.system.oll',99/365,DA // EXTENT,volser // ASSGN SYS4,DISK,VOL=volser,SHR // DLBL ollname,'library name',99/365,da // EXTENT SYS4,volser // EXEC OLLX61,SIZE=(AUTO,48K) SAFEID opident... Utility Control Statements... / Return Codes Note: Review the description of SAFE in the Security Guide for further JCL and control statement information. The Batch Utility issues a return code of 8 if errors are detected Running Batch Utility from the Console The following considerations should be noted if you execute the Batch Utility from the console: All messages (previously designated only for SYSLST) are returned to the console. 2-8 AllFusion CA-Vollie Systems Programmer Guide

19 2.2 Maintenance of OLLs and Members The console operator has three chances to submit a valid SAFEID. (SAFEID is described in the Security Guide.) When the console operator cancels the run, the program ends without issuing any further messages or requiring any additional operator action Backup and Restore Operations In order to protect against accidental OLL loss, it is critical that you periodically create backup copies of the library. Then, if an OLL is damaged, you can use the latest backup copy to restore the library and minimize data loss. Before you perform a RESTORE or FORMAT operation, you must set the OLL offline in all CPUs and/or virtual VSE machines so that no one is accessing the OLL from the terminals or another partition. (You can do this with CA-VOLLIE, using the SET OFFLINE command, or with the Batch Utility, using the SET OFFLINE control statement.) If you do not set the OLL offline, the job is cancelled. You can perform library backups in either of two ways: 1. Use the Batch Utility program provided by CA-VOLLIE. 2. Use a service routine (IBM or other) to dump the library (or the entire pack) to a tape or disk volume. Recommendation You should use a combination of both Batch Utility and a non-ca-vollie service routine. Do not be solely dependent on a non-ca-vollie service routine. This is because: The CA-VOLLIE backup lets you easily restore individual members by name rather than having to restore the entire library. This is valuable if someone accidentally deletes an OLL member and needs it recovered. If internal damage to the index structure of the library occurs, the damage may remain unnoticed for several days. Backup copies of such a library, created by a non-ca-vollie service routine, contain the damaged index structure. The CA-VOLLIE backup file, however, does not contain any index information. The Batch Utility RESTORE function recreates all indexes during the restore run. Thus, a Batch Utility RESTORE run always creates a usable OLL, while using a backup copy from another source may not. Similarly, being solely dependent on the Batch Utility backup/restore facility is also not advisable since there is the possibility of errors in it. When using both methods, you should: Each evening, create a backup file using the Batch Utility program. You should retain the tapes in the cycle for at least one week before reusing or destroying them. This provides the primary mechanism for recovery in the event of damage to a file; it also permits individual members to be easily recovered by name. Chapter 2. Online Libraries (OLLs) 2-9

20 2.2 Maintenance of OLLs and Members At least once a week, create a backup copy of the library (or the entire pack) using any convenient service routine. This provides the secondary recovery procedure in the unlikely event that the Batch Utility backup/restore process functions improperly. The control statements that you may use to perform backup and restore functions are: Statement BACKUP BKUPLIB BKUPLST BKUPPCH RESTORE RESTREN SELBKUP SELREST Operation create a backup file containing all members on an OLL. write library directory information about a full or selective backup file to a list file. write the contents of members on a backup file to a list file write the contents of members on a backup file to a punch file. restore all members from a backup file. restore a member from a backup file and rename it on the OLL. create a backup file containing one or more OLL members or all members associated with an opident. restore one or more members, or all members associated with an opident, from a backup file to an OLL Backup an OLL Function: Backups up the entire contents of an OLL. Syntax BACKUP [BLKSIZE=num] BLKSIZE=num is a value between 4100 and The default is This value is used if you are assigning the backup file to a tape. Notes: Additional information about performing this operation: Use the following JCL to create a backup file using the Batch Utility program: 2-10 AllFusion CA-Vollie Systems Programmer Guide

21 2.2 Maintenance of OLLs and Members // DLBL VSYSOLL,'vollie.system.oll',99/365,DA } 1 // EXTENT,volser } // ASSGN SYS4,DISK,VOL=volser,SHR } // DLBL ollname,'library name',99/365,da } 2 // EXTENT SYS4,volser } // ASSGN SYS1,X'cuu' } 3 // TLBL OLLBKUP,'file-id',99/365,volserno } // EXEC OLLX61,SIZE=(AUTO,48K)) } 4 SAFEID opident[, password] } 5 SET OFFLINE,FILE=ollname OPEN OLL=ollname BACKUP SET ONLINE,FILE=ollname / 1 DLBL and EXTENT information for VSYSOLL must be present to define the SYSTEM OLL in case a CA-VOLLIE File Table load must be performed. 2 The OLL must be assigned to logical unit SYS004 and have a file name that matches the CA-VOLLIE File Table entry. For a CKD device, the DLBL statement must contain the operand DA. For an FBA device, the DLBL statement must contain SD. For a VSAM OLL, change the DLBL statement as follows: // DLBL ollname,'library name',,vsam,cat=catname 3 The backup file must be assigned to a labeled tape or to a sequential disk file. The logical unit for the backup file must be SYS010; the file name must be OLLBKUP. 4 If you changed the phase name prefix of the CA-VOLLIE phases, you must change the letters OLLX on the EXEC statement accordingly. When creating a backup file, use one of the following UPSI statements to specify rewind options: // UPSI 1 Rewind // UPSI 1 No rewind // UPSI Rewind, unload (default) The BACKUP control statement is read from SYSIPT and tells the Batch Utility program that a backup file is to be created. The word BACKUP may start in any column. Chapter 2. Online Libraries (OLLs) 2-11

22 2.2 Maintenance of OLLs and Members You cannot mix the BACKUP control statement with the SELBKUP, SELREST or RESTORE control statements in a single execution of the Batch Utility. Check the output listing, which is written to SYSLST, for any messages regarding unusual conditions found during the run. As the program writes each member to the backup file, it makes certain logic checks on the member structure to identify any damaged members. Any members flagged as being damaged should be selectively restored to the OLL from an earlier backup file in order to avoid potential problems when accessing the damaged members online. 5 A SAFEID card, with an authorized opident (and, if required, a batch access password) must be the first card. Please refer to the CA-VOLLIE Security Guide for detailed information Backup Specific Members/Opidents Function: Backs up one or more specific OLL member or all of the members associated with a specific opident. Syntax SELBKUP [mem,... ] [USERID=opident] mem is the (opident and) name of the member to be copied to a backup file. USERID=opident is the opident whose members are to be backed up. Notes: Additional information about performing this operation: You can specify any number of SELBKUP control statements in a single execution of the Batch Utility. You: must use a separate SELBKUP control statement for each opident to be copied to the backup file. can specify multiple member names per control statement, as long as you do not exceed column 72. (Additional member names may be specified on one or more SELBKUP control statements.) Within each execution, you must specify all opident and, for each opident, all member names in ascending order. A backup file created by the SELBKUP control statement must not be used to perform a full RESTORE run. It can be used to perform a selective restore with the SELREST or RESTREN control statement. You cannot mix SELBKUP control statements with the SELREST, BACKUP or RESTORE control statements in a single execution of the Batch Utility AllFusion CA-Vollie Systems Programmer Guide

23 2.2 Maintenance of OLLs and Members Restore/Rename Backed Up Member/Opident Function: Restores and renames a specific OLL member or opident. Syntax RESTREN [opident.oldmem TO nopident.newmem] [USERID=opident TO NEWID=nopident ] Restore an OLL opident.oldmem is the opident and name of the member to be restored from a backup file. nopident.newmem is the new opident and/or name to be given to the member on the OLL. USERID=opident is the opident whose members are to be restored from the backup file. NEWID=nopident is the new opident to be associated with the restored members on the OLL. Notes: Additional information about performing this operation: You can specify any number of RESTREN control statements in a single execution of the Batch Utility. Within that execution, you must specify all opidents and all member names for each opident in ascending order. Each RESTREN control statement restores one member or opident from the backup file and renames it on the OLL. If the new member name matches the name of an existing member, the existing member is replaced by the restored member. You cannot mix RESTREN control statements with the BACKUP, RESTORE or SELBKUP control statement within a single execution of the Batch Utility. Function: Restores the entire contents of an OLL from the backup file. Syntax RESTORE [NOCLEAR [(R)] ] Chapter 2. Online Libraries (OLLs) 2-13

24 2.2 Maintenance of OLLs and Members NOCLEAR specifies that this restore run is to preserve the existing contents of the OLL. This keyword may be qualified with: (R) specifies that if an existing member on the OLL has the same name and opident as a member on the backup file, the member from the backup file replaces the existing OLL member. If (R) is omitted, any member on the backup file that has the same name and opident as an existing OLL member is not added to the OLL; any such member name is noted with a appropriate message on the listing. Notes: Additional information about performing this operation: Restore an OLL: Use the following JCL to restore an OLL from a CA-VOLLIE backup file: // DLBL VSYSOLL,'vollie.system.oll',99/365,DA } 1 // EXTENT,volser } // ASSGN SYS4,DISK,VOL=volser,SHR } // DLBL ollname,'library name',99/365,da } 2 // EXTENT SYS4,volserno,1,,mmmm,nnnn } // ASSGN SYS1,X'cuu' } 3 // TLBL OLLBKUP,'file-id',,volserno } // EXEC OLLX61,SIZE=(AUTO,48K) } 4 SAFEID opident[, password] } 5 SET OFFLINE,FILE=ollname } FORMAT OLL=ollname or OPEN OLL=ollname } 6 RESTORE } SET ONLINE,FILE=ollname / 1 DLBL and EXTENT information for VSYSOLL must be present to define the SYSTEM OLL in case a CA-VOLLIE File Table load must be performed. 2 The OLL must be assigned to logical unit SYS004 and have a file name that matches the File Table entry. For a CKD device, the DLBL statement must contain the operand DA. For an FBA device, the DLBL statement must contain SD. For a VSAM OLL, change the DLBL statements follows: // DLBL filename,'library name',,vsam,cat=catname 2-14 AllFusion CA-Vollie Systems Programmer Guide

25 2.2 Maintenance of OLLs and Members 3 The backup file must be assigned to a labeled tape or to a sequential disk file. The logical unit for the backup file must be SYS010; the file name must be OLLBKUP. It is your responsibility to determine which is the latest backup tape in the cycle and to correctly assign it for this run. 4 If you changed the phase name prefix of the CA-VOLLIE phases, you must change the letters OLLX on the EXEC statement accordingly. 5 A SAFEID card, with an authorized opident (and, if required, a batch access password) must be the first card. Please refer to the CA-VOLLIE Security Guide for detailed information. 6 The control statements are read from SYSIPT and tell the Batch Utility program which functions are to be performed. Each control statement may start in any column, but they must be placed on separate statements. A RESTORE run always initializes the library indexes, regardless of whether a format run preceded it. In addition, you must also specify either the FORMAT or OPEN control statement, where: Using the FORMAT option causes the track format to be properly set up for the VSE I/O routines. Thus, the FORMAT control statement is only needed if the extent boundaries have changed. Omitting the FORMAT control statement saves a considerable amount of time, since the FORMAT operation usually takes as much or more time than the actual restore itself. The OPEN control statement must be used if you omit the FORMAT control statement. The OPEN or FORMAT control statement must precede the RESTORE control statement. You cannot mix the RESTORE control statement with the BACKUP, SELREST, or SELBKUP control statement in a single execution of the Batch Utility. Note: If you specify FORMAT and RESTORE and the job is cancelled for any reason during the restore operation, it is not necessary to reformat the file; just resubmit the job with the OPEN control statement. When restoring an OLL from a backup file, use one of the following UPSI statements to specify rewind options: // UPSI 1 Rewind // UPSI 1 No rewind // UPSI Rewind, unload (default) Combining Two OLLs: Chapter 2. Online Libraries (OLLs) 2-15

26 2.2 Maintenance of OLLs and Members You can combine the contents of two OLLs by adding members from a backup file to an OLL. Use the NOCLEAR operand to do this. This keyword preserves the existing integrity of the OLL. Because of the internal processing required, a RESTORE NOCLEAR run takes approximately twice as long as a normal restore run for the same input data. The system output listing (written to SYSLST) contains the name of each member restored to the OLL. It also contains the date and time that the backup tape being used was created. Reapply any changes made to the library after the backup tape was created Restore Specific Members/Opident Function: Restores one or more specific OLL members or all of the members associated with a specific opident. Syntax SELREST {mem,... } {USERID=opident} mem is the opident name of the member to be restored from a backup file. USERID=opident is the opident whose members are to be restored. Notes: Additional information about performing this operation: You can specify any number of SELREST control statements in a single execution of the Batch Utility: You must use a separate SELREST control statement for each opident to be restored from the backup file. You can specify multiple member names per control statement, as long as you do not exceed column 72. (Additional member names may be specified on one or more SELREST control statements.) Within each execution, you must specify all opident and, for each opident, all member names in ascending order. If a member to be restored has the same name and opident as an existing member, the member on the backup file replaces the existing member. You cannot mix SELREST control statements with the BACKUP, RESTORE or SELBKUP control statements in a single execution of the Batch Utility AllFusion CA-Vollie Systems Programmer Guide

27 2.2 Maintenance of OLLs and Members Write Backup File Library Directory Information Function: Writes library directory information to a list file. Syntax BKUPLIB {NEWPAGE } {opident,...} With no operand, provides library directory information for all members of all opidents on the current OLL. The information regarding each opident is separated by several blank lines. NEWPAGE opident causes all opidents to be listed and each opident listing to begin on a new page. is the opident whoses members are to be listed. Multiple opidents may be specified as long that the statement does not exceed column 72 in length. Each specified opident listing starts on a new page. Notes: Additional information about performing this operation: You can specify any number of BKUPLIB control statements in a single execution of the Batch Utility. Within an execution, you must specify all opidents in ascending order. The BKUPLIB control statement causes library directory information about all opidents or specific opidents on a full or selective backup file to be written to an auxiliary list file. The information is the same as that provided by the CA-VOLLIE LIBRARY command. The listing is written in ascending order by opident and by the member names within each opident. On a listing of all opidents, information is included for the shareable and VOICE libraries Write Backup Member to Auxiliary List File Function: Produces a listing of the member(s) from the backup file to an auxiliary list file. Syntax: BKUPLST {mem,... } {USERID=opident} mem is the opident and name of the member to be listed. Chapter 2. Online Libraries (OLLs) 2-17

28 2.2 Maintenance of OLLs and Members USERID=opident is the opident whose members are to be listed. Notes: Additional information about performing this operation: BKUPLST lets you print the contents of one or more members on a full or selective backup file without having to restore the member(s) to an OLL. You can specify any number of BKUPLST control statements in a single execution of the Batch Utility. You: must use a separate BKUPLST control statement for each opident to be listed from the backup file. can specify multiple member names per control statement, as long as you do not exceed column 72. (Additional member names may be specified on one or more BKUPLST control statements.) Within each execution, you must specify all opident and, for each opident, all member names in ascending order Write Backup Member to Punch File Function: Copies member(s) from the backup file to a punch file. Syntax BKUPPCH {mem,... } {USERID=opident} mem is the opident and name of the member to be punched. USERID=opident is the opident whose members are to be punched. Notes: Additional information about performing this operation: BKUPPCH produces punched card images on SYSPCH from a full or selective backup file without restoring the member(s) to an OLL. You can specify any number of BKUPPCH control statements in a single execution of the Batch Utility. You: must use a separate BKUPPCH control statement for each opident to be listed from the backup file. can specify multiple member names per control statement, as long as you do not exceed column 72. (Additional member names may be specified on one or more BKUPPCH control statements.) Within each execution, you must specify all opident and, for each opident, all member names in ascending order AllFusion CA-Vollie Systems Programmer Guide

29 2.2 Maintenance of OLLs and Members File-Related Operations This section describes the control statements that you can use to perform file-related utility operations. The control statements include: Statement CHGNAME CLOSE FORMAT OPEN SET SPACE Change an OLL Name Operation changes the name of an OLL without having to reformat the OLL. closes one or more OLLs to CA-VOLLIE after an abnormal termination. formats an OLL. Note: This control statement is described in the Installation Guide. opens one or more OLLs for processing Sets a specific OLL file online or offline, to protect the file from access by an online partition. Determines the number of total blocks on the file and/or the number of unused blocks on a specific OLL. You can also use the control statements described in this section to relocate a SYSTEM OLL. Function: Changes the name of an OLL. Syntax CHGNAME OLL=name OLL=name is the new name for an OLL. Notes: Additional information about performing this operation: CHGNAME allows you to change the name of an OLL without having to reformat the OLL. To change the OLL name, execute the Batch Utility with CHGNAME OLL=new name, where new name is the new OLL name. The OLL name in the DLBL statement and the CHGNAME statement must identify the new OLL name. The OLL whose name is changed is not accessible to online CA-VOLLIE until you update the CA-VOLLIE File Table entry (using the SYSTEM command) to match the new OLL name and the File Table is reloaded. Chapter 2. Online Libraries (OLLs) 2-19

30 2.2 Maintenance of OLLs and Members Close One or More OLLs Function: Closes one or more OLLs to CA-VOLLIE after an abnormal termination. Syntax CLOSE [OLL=name] [/ALL/ ] With no operand, causes the Batch Utility to perform a VSE close of the OLL identified by the most recently executed OPEN statement. The OLL is closed in the partition in which the CLOSE statement is issued. OLL=name is the name of the OLL for which the Batch Utility is to perform a CA-VOLLIE close. /ALL/ causes the Batch Utility to perform a CA-VOLLIE close of each OLL named in the CA-VOLLIE File Table currently loaded. Notes: Additional information about performing this operation: Formatting One or More OLLs CLOSE automatically closes OLLs to CA-VOLLIE after an abnormal termination of online processing. This control statement is not necessary during normal Batch Utility processing when an OLL is processed and closed at the end of the job. If this statement is included in a normal Batch Utility run, CA-VOLLIE performs VSE and CA-VOLLIE closes of the OLL opened for processing. When all OLLs are closed using CLOSE /ALL/, the SVA memory is freed and any hung members are released and the LOCK file is cleaned up. If, following the CICS run, the Batch Utility is run with the CLOSE control statement in each partition in which CA-VOLLIE executes, abnormal CICS terminations do not leave extraneous data behind, requiring additional housekeeping. Function: Formats an OLL for use by CA-VOLLIE. Syntax FORMAT [OLL=ollname][EXTEND] OLLname The name of the OLL to be formatted AllFusion CA-Vollie Systems Programmer Guide

31 2.2 Maintenance of OLLs and Members EXTEND Allows you to expand the size of an OLL file. For information on expanding the size of an OLL see,-- Heading 'EXTEND2' unknown --, laterin this chapter. Notes: Additional information about performing this operation: The job examples below show how to format an OLL for the first time as well as how to format subsequent OLLs. Examples are given for DA and VSAM OLLs. 1. Formatting a Direct access OLL for the first time // JOB CAVLDAO Format a Direct Access OLL // LIBDEF PHASE,SEARCH=vlib.vsublib CA-VOLLIE Library // DLBL daoll,'direct.access.oll',99/365,da OLL to be Formatted // EXTENT SYS4,dvolser,1,,dstart,dsize // ASSGN SYS4,DISK,VOL=dvolser,SHR // EXEC OLLX61,SIZE=(AUTO,48K) FORMAT OLL=daoll 2. Subsequent runs to Format a Direct access OLL // JOB CAVLDAO1 Format a Direct Access OLL // LIBDEF PHASE,SEARCH=vlib.vsublib CA-VOLLIE Library // DLBL daoll,'direct.access.oll',99/365,da OLL to be formatted // EXTENT SYS4,dvolser,1,,dstart,dsize // ASSGN SYS4,DISK,VOL=dvolser,SHR Notes. Change DA to VSAM in the DLBL below and remove the EXTENT card if the system OLL is a VSAM cluster. If necessary, add the parameter CAT= // DLBL VSYSOLL,'system.oll',99/365,DA System OLL // EXTENT,sysvol Notes. Change DA to VSAM in the DLBL below and remove the EXTENT and ASSGN cards if the SYSTEM OLL is a VSAM cluster. If necessary, add the parameter CAT= // DLBL sysoll,'system.oll',99/365,da System OLL // EXTENT SYS6,sysvol // ASSGN SYS6,DISK,VOL=sysvol,SHR // EXEC OLLX61,SIZE=(AUTO,48K) SAFEID opident SET OFFLINE FILE=daoll FORMAT OLL=daoll SET ONLINE FILE=daoll 3. Formatting a VSAM OLL for the first time Chapter 2. Online Libraries (OLLs) 2-21