CA Panvalet CMS Option

Transcription

1 CA Panvalet CMS Option Getting Started r14.6

2 This Documentation, which includes embedded help systems and electronically distributed materials, (hereinafter referred to as the Documentation ) is for your informational purposes only and is subject to change or withdrawal by CA at any time. This Documentation may not be copied, transferred, reproduced, disclosed, modified or duplicated, in whole or in part, without the prior written consent of CA. This Documentation is confidential and proprietary information of CA and may not be disclosed by you or used for any purpose other than as may be permitted in (i) a separate agreement between you and CA governing your use of the CA software to which the Documentation relates; or (ii) a separate confidentiality agreement between you and CA. Notwithstanding the foregoing, if you are a licensed user of the software product(s) addressed in the Documentation, you may print or otherwise make available a reasonable number of copies of the Documentation for internal use by you and your employees in connection with that software, provided that all CA copyright notices and legends are affixed to each reproduced copy. The right to print or otherwise make available copies of the Documentation is limited to the period during which the applicable license for such software remains in full force and effect. Should the license terminate for any reason, it is your responsibility to certify in writing to CA that all copies and partial copies of the Documentation have been returned to CA or 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 YOU OR ANY THIRD PARTY FOR ANY LOSS OR DAMAGE, DIRECT OR INDIRECT, FROM THE USE OF THIS DOCUMENTATION, INCLUDING WITHOUT LIMITATION, LOST PROFITS, LOST INVESTMENT, BUSINESS INTERRUPTION, GOODWILL, OR LOST DATA, EVEN IF CA IS EXPRESSLY ADVISED IN ADVANCE OF THE POSSIBILITY OF SUCH LOSS OR DAMAGE. The use of any software product referenced in the Documentation is governed by the applicable license agreement and such license agreement is not modified in any way by the terms of this notice. The manufacturer of this Documentation is CA. Provided with Restricted Rights. Use, duplication or disclosure by the United States Government is subject to the restrictions set forth in FAR Sections , , and (c)(1) - (2) and DFARS Section (b)(3), as applicable, or their successors. Copyright 2009 CA. All rights reserved. All trademarks, trade names, service marks, and logos referenced herein belong to their respective companies.

3 CA Technologies Product References This document references the following CA Technologies products: CA Panvalet Option for CMS (CA Panvalet Option for CMS) CA Panvalet for z/os (CA Panvalet) Contact CA Technologies Contact CA Support For your convenience, CA Technologies provides one site where you can access the information that you need for your Home Office, Small Business, and Enterprise CA Technologies products. At you can access the following resources: Online and telephone contact information for technical assistance and customer services Information about user communities and forums Product and documentation downloads CA Support policies and guidelines Other helpful resources appropriate for your product Providing Feedback About Product Documentation If you have comments or questions about CA Technologies product documentation, you can send a message to techpubs@ca.com. To provide feedback about CA Technologies product documentation, complete our short customer survey which is available on the CA Support website at

4

5 Contents Chapter 1: Welcome 7 Program Management and Security System... 7 CMS Option... 7 Getting Started... 8 Chapter 2: Installation 9 System Requirements... 9 Hardware... 9 Operating System... 9 Core Size... 9 Disk Space Installing the CMS Option Post-Installation Considerations Formatting Options for Retrieval and Command Suppression Input/Output Flow Diagram File Requirements Library File (PANDD1) Prepare z/os and VSE Libraries for Access User's Terminal Chapter 3: PAN Command Processor 15 PAN Subcommands DISPLAY LISTDS PRINT RETRIEVE CMS/Batch Processing Interface Special Formatting Option Special Processing Features with PAN# Special PAN Command Processor Features Special Character Support Execution Execution Under CMS Access to Multiple Libraries PAN Command Processor Syntax Contents 5

6 Chapter 4: PAN Subcommands 21 DISPLAY Syntax Parameters Examples LISTDS Syntax Parameters Examples PRINT Syntax Parameters Examples RETRIEVE Syntax Parameters Examples Keyword Summary Chapter 5: User Exits 33 Linkage Conventions Parameters Using the Exit PAN RETRIEVE/DISPLAY Output Mode Adding Records Before the Current Record Adding Records After the Current Record Skipping Current Records Linking User Exits Appendix A: Messages 41 Error and Informational Messages Other Return Codes Index 45 6 Getting Started

7 Chapter 1: Welcome This CA Panvalet Option for CMS Getting Started describes the functions and the management control features of the CA Panvalet Option for CMS Command Processor Library System. It also provides technical information necessary for its implementation in an IBM VM environment. Systems programming and operations personnel can use this guide to establish methods and procedures for the most effective use of the PAN CMS interface. They can also use it to implement control and security procedures in connection with their use of the CMS interface. This guide can be used with the System Management Guide for evaluation and installation planning for the CA Panvalet library system with the CMS Option. This section contains the following topics: Program Management and Security System (see page 7) CMS Option (see page 7) Getting Started (see page 8) Program Management and Security System CA Panvalet is a versatile and efficient program management and security system designed for an IBM environment. It is used to establish, maintain, and protect a control library of source programs, object programs, JCL, and card-image data files. Central library storage on a direct access device (DASD) allows immediate access for maintenance or processing, improved machine throughput, greater productivity of personnel, and effective control and protection against theft, disaster, or other loss. CMS Option CMS is a conversational, terminal-oriented system used on VM systems that lets programmers quickly and effectively develop, debug, and maintain computer programs. The CA Panvalet Option for CMS is the interface system between a z/os or VSE CA Panvalet library under a VM operating system. Chapter 1: Welcome 7

8 Getting Started The CA Panvalet Option for CMS provides read-only access to the CA Panvalet library and the ability to create a properly named CMS file on a CMS disk for editing, compiling, link-editing, and so on. Subsequent to CMS editing, programs are submitted to a batch machine for permanent CA Panvalet updating. To perform updates to the z/os or VSE CA Panvalet libraries, spool the update job stream to a z/os or VSE machine. This gives the CMS user the full capabilities of CA Panvalet without interfering with batch processing or with other CMS users. The functions of storage and retrieval of programs in the CA Panvalet library are performed by the PAN Command Processor in the CMS environment and by the PAN#1 program in an execution mode. Only the PAN Command Processor facilities are discussed in this guide. For all batch references, see the User Guide and the System Management Guide. Getting Started The rest of this guide is divided into several chapters to provide information about: System and installation requirements for the CA Panvalet Option for CMS Subcommands, operation, and execution of the PAN Command Processor All subcommands with syntax and parameters User exits and how they work with the PAN Command Processor Error and informational messages issued by the Option for CMS 8 Getting Started

9 Chapter 2: Installation This chapter describes hardware, operating system, core size, and disk space requirements for installing the CA Panvalet Option for CMS on your VM system. This chapter also describes how to install the CA Panvalet Option for CMS. This section contains the following topics: System Requirements (see page 9) Installing the CMS Option (see page 10) Post-Installation Considerations (see page 10) User's Terminal (see page 13) System Requirements Review the following system requirements before proceeding with the CA Panvalet Option for CMS installation. Hardware The PAN Command Processor supports the CA Panvalet library file on any DASD supported by z/os or VSE. The program is executable in any IBM environment running under VM. The Decimal Arithmetic feature is also required. Operating System The PAN Command Processor can be executed concurrently in multiple CMS virtual machines under VM and on shared DASD between multiple CPUs. The execution of the PAN Command Processor is accomplished by invoking commands entered at a user's terminal during a CMS session. It can be executed under Release 2 and above of CMS. Core Size As a general rule, the PAN Command Processor requires a minimum CMS machine of 320 KB. Chapter 2: Installation 9

10 Installing the CMS Option Disk Space You must have sufficient disk space to install the CA Panvalet Option for CMS. Use the following table to estimate space requirements for the CA Panvalet Option for CMS. Disk Type Blocking Test System Files Production System Files KB 1 cylinder 1 cylinder Installing the CMS Option The CA Panvalet Option for CMS consists of one cartridge of magnetic tape containing five z/os standard-labeled files that are blocked at 38 KB. To install the CA Panvalet Option for CMS: 1. Attach a tape drive to your CMS session. Retrieve the installation documentation from the tape with the following commands: TAPE REW TAPE FSF 7 TAPE LOAD INSTALL DOC You can unload the tape at this time, if necessary, with the command: TAPE RUN 2. Review the file just retrieved and follow the steps detailed in it to complete the installation. Post-Installation Considerations Any time the installation security code or any other PVOPT option is changed, FGPAN23 must be assembled for both batch and CMS. The PVLKCMS1 EXEC must also be executed to include the changes. 10 Getting Started

11 Post-Installation Considerations Formatting Options for Retrieval and Command Suppression An CA Panvalet data set can be retrieved with the usual CA Panvalet sequencing (sequence by ones) or with the CMS sequencing (sequence by tens). These parameters can be established as the installation default. You can override the default, if desired, by using the opposite parameter. If CMS is the default when retrieving a data set for which CMS sequencing is not supported, then normal CA Panvalet sequencing occurs and no error is reported. Retrievals can be performed with or without expansion of embedded ++INCLUDEs by using the EXPAND or NOEXPAND parameters. You can choose either of these parameters as an installation default, with an override possible by using the opposite parameter. Also, you can suppress functions in the PAN Command Processor. Suppressed commands require the entry of the correct control parameter. Entry of an invalid control code for a suppressed command causes the user to be disconnected from CMS. Information about resetting the default retrieval options and how to set suppressed commands can be found in the exec retrieved by installation, PVCOPTS EXEC. The PRINT command always requires the entry of the CONTROL parameter, regardless of what command suppression is used or what the value of the CONTROL code is. Input/Output Flow Diagram File Requirements The PAN Command Processor uses the file name/ddname PANDD1 for the input library. Messages are written to the user's terminal. Chapter 2: Installation 11

12 Post-Installation Considerations Library File (PANDD1) The CA Panvalet library resides on an z/os or VSE disk and contains programs, object programs, job control, or card image data files. It is logically segmented into library members referred to by name in CA Panvalet commands. Prepare z/os and VSE Libraries for Access CMS does not support BDAM as an access method for z/os or VSE disks. Therefore, the CA Panvalet library must appear to be a physical sequential file to CMS. You can do this by using one of the following methods: CA Panvalet for z/os libraries can be dumped, cleared, and restored according to the specification in the System Management Guide with one exception. The exception is to omit the DCB subparameter DSORG=DA in the PAN#4 clear execution. CA Panvalet VSE libraries are supported if they appear as z/os BSAM files to CMS. You must modify the Format 1 label contained in the VTOC of the device on which the CA Panvalet library resides to accomplish this. Modify the Format 1 label by using DITTO's DRL (disk record load) interactively through the console or ICCF. The following general steps describe how to modify the Format 1 label: 1. Run a DITTO DVT to find the location (beginning and ending cylinder-head (CKD) or relative block (FBA)) of the VTOC extent on the volume containing the CA Panvalet data set. 2. Use the VTOC location as input to a DITTO DDD to dump the VTOC. 3. Locate the record number (CKD) or block number (FBA) that contains the CA Panvalet data set name. This is required later for input to DITTO's DRL. 4. Find the eye-catcher "IBMDOSVS" immediately after the CA Panvalet data set namecompute the offset (relative to zero) in bytes of where to begin the modification for input to DITTO's DRL. For CKD devices, the offset is computed from the start of the DATA portion of the record. For FBA devices, the offset is computed from the start of the block. The modification must begin on the 13th byte after the last S in IBMDOSVS. You should find an X'20' there. For example: CHAR ZONE NUMR IBMDOSVS CCDCDEEE <---- This is where you begin to modify: ? 0 < XXYY XXYY00 where both XXXX and YYYY represent the CA Panvalet library block size in hexadecimal. 12 Getting Started

13 User's Terminal User's Terminal Informational, error, and termination messages from the PAN Command Processor are listed directly to the user's terminal. Input resulting from prompt messages is accepted directly from the user's terminal. Chapter 2: Installation 13

14

15 Chapter 3: PAN Command Processor This chapter discusses the subcommands, operation, features, and execution of the PAN Command Processor. The PAN Command Processor is structured to serve both programmers and programming management in processing CA Panvalet library members. This section contains the following topics: PAN Subcommands (see page 15) CMS/Batch Processing Interface (see page 16) Execution (see page 19) PAN Subcommands All subcommands are combined in the PAN Command Processor, but execution of the management features is automatically protected. A description of the subcommands of the PAN Command Processor follows. DISPLAY By using the DISPLAY subcommand, an CA Panvalet library member is displayed at the user's terminal. The requested member can be displayed in its entirety or in various selected portions. LISTDS You can inspect an CA Panvalet library member's attributes with the LISTDS subcommand. The CA Panvalet member name is required. Information for the requested member is listed to the user's terminal and includes level number, user code, status, language, blocks used, number of statements, dates of last maintenance and last access, percent of utilization, and logical record length. Chapter 3: PAN Command Processor 15

16 CMS/Batch Processing Interface PRINT A selective directory list in abbreviated form (72 characters per line) can be printed at the user's terminal with the PRINT subcommand. You can select name key, status, user code, or language type. Regardless of the selection, the listing appears in name sequence. Other CMS or batch users can access the CA Panvalet library while this subcommand is being performed. Subtotals or summaries are not produced. Note: The proper control code must be supplied, as in PAN#2, for this subcommand to be successfully executed. RETRIEVE You can copy an CA Panvalet library member from the library to a CMS sequential data set. The retrieved data set is read by the CMS EDIT of the interactive compilers. Note: Unless overridden, the data set is created with the default shown with the description of the DATASET parameter (see the chapter "PAN Subcommands"). CMS/Batch Processing Interface Several considerations exist for the CMS user who wants to reference CMS formatted data sets on the CA Panvalet library in batch mode (for example, submitting a job that executes PAN#1). Special Formatting Option The special formatting option is part of the ++ADD command. The ++ADD command in the PAN-CMS environment supports the optional parameter (CMS), which can be supplied in place of the NOFORMAT parameter. This parameter requests special CMS internal storage and processing for the data set being ADDed to the system. This operand is ignored for formats other than: ANSCOBOL BAL (or ALC) COBOL FORTRAN JCL PL/1 (or PL/I) ZTYPEs that mimic the above 16 Getting Started

17 CMS/Batch Processing Interface Special Processing Features with PAN#1 The special processing features for a CMS library member with PAN#1 are shown below. The program, when added to the library in a batch PAN#1 run, is resequenced by tens (10s). These sequence numbers are stored on the library. When PAN#1 or PAN retrieves the data set, a special comment record is developed to inform the user of the CA Panvalet name, the LEVEL number of the data set, and the date of last maintenance. When this comment is a separate card, its sequence number is all zeros. For the COBOL format with the CA Panvalet CMS Option, the ID portion of the statement is blank after the first three cards. A batch mode update of a program stored with CMS format can be made using PAN#1. The popular ++C update technique is used. For example: ++C 4090,5010 Deletes all statements starting with 4090 and including C statements to be inserted. Inserts after the statement numbered 6050, the cards that follow. ++C 7020, statements to replace. Deletes all the statements starting with 7020 and including 7040, and inserts the cards that follow in place of the deleted statements. The updated program would be renumbered by tens. A compile of the updated data set would show the new sequence numbers. Special PAN Command Processor Features Special processing features for a CMS library member with PAN make it possible for the PAN Command Processor to retrieve and display the data set in a variety of ways as follows: A PAN R or PAN D with "PANVALET,NOEXPAND" parameters or defaults performs the retrieval and display exactly as PAN#1 ++WRITE¼PRINT except for PL/I data sets. A PAN R or PAN D with "PANVALET,EXPAND" parameters or defaults performs the retrieval and display exactly as a PAN#1 WRITE¼WORK. Chapter 3: PAN Command Processor 17

18 CMS/Batch Processing Interface A PAN R or PAN D with "CMS,NOEXPAND" parameters or defaults retrieves and displays the following format types with a generated sequence field, sequenced by tens, filling the entire sequence field: ASM, COBOL, FORTRAN, PLI, JCL. Members already stored as NOFORMAT are retrieved and displayed exactly as a PAN#1 ++WRITE¼PRINT. A PAN R or PAN D with "CMS,EXPAND" parameters or defaults retrieves and displays the following format types with a generated sequence field, sequenced by tens, filling the entire sequence field: ASM, COBOL, FORTRAN, PLI, JCL. Embedded ++INCLUDEs are expanded and sequenced inline with the original member. The expansion of the ++INCLUDEs is performed in the following manner. The first level INCLUDE (or outermost INCLUDE) is expanded with a special header and trailer comment to mark the beginning and end of the INCLUDEd member. Additional levels of INCLUDEs are expanded normally. The format of the header comment is shown as follows: type COBOL,RPG column * INCLUDE++ FORT C INCLUDE++ PLI / * INCLUDE++ * / JCL / / * INCLUDE++ ASM * INCLUDE++ and others including ZTYPEs The format of the trailer comment is the same, except for the "END INCLUDE++" key phrase, which starts in column 8 of the trailer record. Important! You must not alter the comments under CMS EDIT if the data set is to be properly stored back on the CA Panvalet library. Note: The special headers and trailers apply to the CMS EXPAND option only and are recognized by batch CA Panvalet. The expanded INCLUDEs are recompressed when the data set is spooled back to batch CA Panvalet. The LRECL of an INCLUDE member must match that of the main member. The resulting output data set is compatible, if CMS sequencing is applicable, with the CMS interactive compilers or with CMS EDIT. Special Character Support The PAN Command Processor supports special characters (@, #, $) in library member names. However, there is a conflict with CMS itself concerning the pound sign (#). As the default, this character is the end-of-line character and cannot be used when entering a name on the PAN command line. To use this character, you can alter your PROFILE EXEC to choose a different end-of-line character. 18 Getting Started

19 Execution Execution Invoking the command PAN and the desired subcommand with its operands directly from the user's terminal during a CMS session executes the PAN Command Processor. Execution Under CMS To use the PAN Command Processor during a terminal session, the ddname of PANDD1 must first be allocated. This can be accomplished in either of two ways: Modify the user's logon procedure (PROFILE EXEC) to include the following FILEDEF for the CA Panvalet library. FILEDEF PANDD1 DISK FILE PANDD1 fm DSN dsname Issue the above allocation command during the terminal session after the logon. The dsname can be a question mark (?) or qual1, qual2,¼qualn. If you use a question mark, you are prompted to enter the proper 44-byte z/os or VSE data set name for the file. If quals are used (preferred method), the 44-byte z/os and VSE data set name must follow z/os data set name rules. CMS strings the quals together, connected by periods, and the result must match the actual z/os and VSE data set name. For example: z/os and VSE Data Set Name X.Y.Z PANVALET PAN.LIBRARY PAN VALET (VSE only) CMS FILEDEF Data Set Name DSN X Y Z DSN PANVALET DSN PAN LIBRARY DSN? and reply PAN VALET to prompt. The first method is preferred because it is automatic with every logon and is transparent to the user. Access to Multiple Libraries For easy access to multiple CA Panvalet libraries during a single logon session, assign additional ddnames to the libraries during or after logon and use the ddname operand with each PAN request to indicate the ddname of the library you want to access. You can use any appropriate ddname, except PANDD2 and PANDD3. Chapter 3: PAN Command Processor 19

20 Execution PAN Command Processor Syntax This topic describes the PAN Command Processor syntax format. PAN subcommand name keywords/values PAN subcommand name The command is PAN, followed by a space and then the subcommand. The minimum abbreviation for a subcommand is variable, and it is followed by a space. A 1- to 21-character CA Panvalet member name that the subcommand processes. It is followed by a space. keywords/values Keywords are non-positional and delimited by a space or spaces from each other and from their values (if any). You can abbreviate each keyword as described in the keyword summary. You can specify keywords in any order. Keyword values assign meaning or quantity that directs or qualifies the action of the keyword; an operand. The value of a keyword must follow right after the keyword. Required keywords are enclosed in braces: {required} Mutually exclusive, required keywords are stacked in braces: { one of these } { keywords } { is required } Optional keywords are enclosed in brackets: [Optional] Mutually exclusive, optional keywords are stacked in brackets: [ one of these ] [ keywords ] [ can be used ] Variables (for example, an CA Panvalet member name or keyword value) are shown in lowercase. 20 Getting Started

21 Chapter 4: PAN Subcommands This chapter describes all the PAN Command Processor subcommands and keywords. For more information about subcommands, see the chapter PAN Command Processor. This section contains the following topics: DISPLAY (see page 21) LISTDS (see page 23) PRINT (see page 24) RETRIEVE (see page 26) Keyword Summary (see page 28) DISPLAY The PAN DISPLAY subcommand displays an CA Panvalet library member. Syntax PAN DISPLAY NAME ([DDNAME ddname] [EXPAND ] [NOEXPAND] [PANVALET] [CMS ] [ACCESS nn] [CONTROL nn] [FROM nn] [TO nn]) Parameters PAN DISPLAY Name The minimum abbreviation is PAN D. The member name is the 1- to 21-character CA Panvalet name you want to display. If the CA Panvalet name is greater than 8 characters, it must be broken into eight-byte increments, each separated by one space. SUPERSET.SUBSET displays are permitted. Chapter 4: PAN Subcommands 21

22 DISPLAY See the Keyword Summary section for additional information. DDNAME ddname Optional. Specifies an alternate ddname for the CA Panvalet library. This keyword allows access to multiple CA Panvalet libraries and allows specification of a particular library at execution time. The minimum abbreviation is D. EXPAND Optional. Expands embedded CA Panvalet ++INCLUDE statements during display. The minimum abbreviation is E. NOEXPAND Optional. Leaves embedded CA Panvalet ++INCLUDE statements unexpanded during display. The minimum abbreviation is N. Note: The installation default for display of ++INCLUDEs can be EXPAND or NOEXPAND. You can use the opposite parameter to override the default at execution time. PANVALET CMS Optional. Requests sequencing displayed data sets by CA Panvalet sequence numbers with unnumbered, generated comment records. The minimum abbreviation is P. Optional. Requests sequencing of displayed data sets by CMS sequence numbers (sequenced by tens with generated comment records numbered zero). Note: The installation default for internal formatting can be PANVALET or CMS. You can use the opposite parameter to override the default at execution time. ACCESS nn Optional. Allows access to a user security-protected CA Panvalet library member. The minimum abbreviation is A. CONTROL nn Optional. Performs the display if the subcommand is suppressed. The minimum abbreviation is CON. FROM nn TO nn Optional. Starting statement number to be displayed. If omitted, the display starts with the first statement. The minimum abbreviation is F. Optional. Ending statement to be displayed. If omitted, the display ends with the last statement of the member. The minimum abbreviation is T. If CMS sequencing is in effect, the count is by tens and expanded INCLUDEs are counted. If CA Panvalet sequencing is in effect, the count is by ones and the expanded INCLUDEs are not counted. 22 Getting Started

23 LISTDS Examples PAN DISPLAY PAY57 Displays member PAY57 in its entirety. PAN D PAY58 (DDN PANVLT Displays member PAN58 in its entirety from alternate CA Panvalet library defined to DDNAME PANVLT. PAN D PAY59 (EXPAND Displays member PAY59 in its entirety and expands any embedded ++INCLUDE statements. PAN D SUPSET.S UB1 (F 5 T 10 CMS Displays SUPERSET.SUBSET member named SUPSET.SUB1 from statement 5 to statement 10 with CMS sequence numbers. LISTDS PAN LISTDS is a request to list the attributes of an CA Panvalet library member. Syntax PAN LISTDS NAME ([ACCESS nn] LD [CONTROL nn] [COMMENT]) [DDNAME ddname]) Parameters PAN LISTDS Name The minimum abbreviation is PAN L. The member name is the 1- to 21-character CA Panvalet name you want to list. If the CA Panvalet name is greater than 8 characters long, you must break it up into 8-byte increments, each separated by one space. You can specify a SUPERSET.SUBSET, but the attributes listed are those of the SUPERSET. Chapter 4: PAN Subcommands 23

24 PRINT See the Keyword Summary section for additional information. ACCESS nn Optional. Allows access to a user security protected CA Panvalet library member. The minimum abbreviation is A. CONTROL nn Optional. Performs the list if the subcommand is suppressed. The minimum abbreviation is CON. COMMENT Optional. Requests to also have the library member's user comment listed to the terminal. The minimum abbreviation is COM. DDNAME ddname Optional. Specifies an alternate ddname for the CA Panvalet library. This parameter allows access to multiple CA Panvalet libraries and specification of a particular library at execution time. The minimum abbreviation is DD. Examples PAN LD PAY57 (COM Lists one heading line to the user's terminal, one line of directory information for CA Panvalet member PAY57, and one line of user comment, if present. PAN L EMPSTAT (ACC 5 DD PANVLT Lists one heading line to the user's terminal and one line of directory information for CA Panvalet member EMPSTAT supplying the required user code 5 from the alternate CA Panvalet library defined to DDNAME PANVLT. PRINT PAN PRINT is a request for a selective directory list to be printed at the user's terminal. Syntax PAN PRINT ({CONTROL nn} {NAME namekey } {STATUS selection} {USER xxxx[yyyy] } {TYPE language } [COMMENT] [DDNAME ddname]) 24 Getting Started

25 PRINT Parameters PAN PRINT The minimum abbreviation is PAN P. See the Keyword Summary section for additional information. CONTROL nn Required. Specifies the library control code. You must specify one of the following parameters: NAME, STATUS, USER, TYPE. The minimum abbreviation is CON. NAME namekey Required. Indicates a selection on namekey (1 to 8 characters). The minimum abbreviation is N. STATUS selection Required. Indicates a selection on status (P, T, E, D, A, or I). The minimum abbreviation is S. USER xxxx[yyyy] Required. Indicates a selection on user code or range of user codes. The minimum abbreviation is U. TYPE language Required. Indicates a selection on language type. The minimum abbreviation is T. COMMENT Optional. Indicates that user comments are also listed, when present. The minimum abbreviation is COM. DDNAME ddname Optional. Specifies an alternate ddname for the CA Panvalet library. This parameter allows access to multiple CA Panvalet libraries and allows specification of a particular library at execution time. The minimum abbreviation is DD. Examples PAN PRINT (CON 64 S T COM Requests a directory listing to the user's terminal of all CA Panvalet library members in Test status and a listing of their user comments, if present. PAN P (CON 53 U Requests a directory listing to the user's terminal of all CA Panvalet library members with user codes between 20 and 30 inclusive. Chapter 4: PAN Subcommands 25

26 RETRIEVE RETRIEVE PAN RETRIEVE is a request to retrieve an CA Panvalet library member. Syntax PAN RETRIEVE NAME ([DATASET fn ft fm] [EXPAND ] [NOEXPAND] [PANVALET] [CMS ] [ACCESS nn] [CONTROL nn] [DDNAME ddname]) Parameters PAN RETRIEVE Name The minimum abbreviation is PAN R. The member name is the 1- to 21-character CA Panvalet name you want to retrieve. If the CA Panvalet name is greater than 8 characters long, you must break it into 8-byte increments, each separated by one space. SUPERSET.SUBSET retrievals are permitted. See the Keyword Summary section for additional information. DATASET fn ft fm Optional. Overrides the default file name, file type, and file mode of the data set being retrieved to a CMS disk from an z/os and VSE CA Panvalet library. The defaults are as follows: CMS file name positions 1 to 8 of the CA Panvalet data set name. CMS file type CA Panvalet type except: ASSEMBLE ASM, BAL, ALC TEXT OBJECT COBOL COBOL-72 UNSPC UNSPECIFIED COBOL ANSCOBOL AUTOC AUTOCODER PLI PL/1 or PL/I ZTYPEs that mimic the above CMS file mode A1 When used, the DATASET parameter requires three subparameters: filename, filetype, and filemode. You must specify the subparameters to change, while an equal sign (=) can indicate those for which the default is acceptable. The minimum abbreviation is DA. 26 Getting Started

27 RETRIEVE EXPAND Optional. Expands embedded CA Panvalet ++INCLUDE statements during retrieval. The minimum abbreviation is E. NOEXPAND Optional. Leaves embedded CA Panvalet ++INCLUDE statements unexpanded during retrieval. The minimum abbreviation is N. Note: The installation default for retrieval of ++INCLUDEs can be EXPAND or NOEXPAND. You can use the opposite parameter to override the default at execution time. PANVALET CMS Optional. Requests sequencing of retrieved data sets by CA Panvalet sequence numbers with unnumbered, generated comment records. The minimum abbreviation is P. Optional. Requests sequencing of retrieved data sets by CMS sequence numbers (sequenced by tens with generated comment records numbered zero). Note: The installation default for internal formatting can be PANVALET or CMS. You can use the opposite parameter to override the default at execution time. ACCESS nn Optional. Allows access to a user security protected CA Panvalet library member. The minimum abbreviation is A. CONTROL nn Optional. Performs the retrieve if the subcommand is suppressed. The minimum abbreviation is CON. DDNAME ddname Optional. Specifies an alternate ddname for the CA Panvalet library. This parameter allows access to multiple CA Panvalet libraries and specification of a particular library at execution time. If a PROCESS compiler control statement is the first statement in a PL/I format member, the CA Panvalet special comment record is not generated. If an ICTL assembler statement is the first statement in a BAL format member, the CA Panvalet special comment record is not generated. The minimum abbreviation is DD. Chapter 4: PAN Subcommands 27

28 Keyword Summary Examples PAN RETRIEVE PAYROLL4 01 Retrieves a member called PAYROLL401 and creates a CMS file on the user's A-disk named PAYROLL4 filetype A1. where filetype is the CA Panvalet format type. PAN R SORTEST (DA = CARDS = E Retrieves a member called SORTEST, expands any embedded ++INCLUDE statements, and creates a CMS file named SORTEST CARDS A1. Uses normal CA Panvalet sequencing. PAN R TDATE (DD PANVLT CMS DA TODAYS DATE = Retrieves a member called TDATE from the alternate CA Panvalet library defined to DDNAME PANVLT and creates a CMS file named TODAYS DATE A1. Uses CMS sequencing. Keyword Summary The following table is a summary of possible keyword usage with the CA Panvalet Option for CMS subcommands. The minimum abbreviations of the subcommands are shown in bold text. Keywords used with PAN subcommands must be enclosed as a group in a single set of parentheses. Keyword Where Used Action Value Format Access nn Optional for the R, L, and D subcommands. CMS COMment Optional for the R and D subcommands. Optional for the L and P subcommands. Allows access to a user security- protected CA Panvalet library members. Causes members with BAL, COBOL, ANSCOBOL, FORTRAN, PL/I, or JCL formats to be automatically sequenced in CMS format for retrieval. All other types and NOFORMAT are treated with CA Panvalet sequencing when applicable. ZTYPEs can mimic any of the above. Causes user comment record to be listed to user's terminal. Numeric value, one to five digits. Keyword alone. Keyword alone. 28 Getting Started

29 Keyword Summary Keyword Where Used Action Value Format CONtrol nn DAtaset fn ft fm DDname ddname Expand Name namekey Noexpand Panvalet Status selection Optional for R, L, and D subcommands. Required for P subcommands. Optional for R subcommands. Optional for R, L, P, and D subcommands. Required for P subcommands. Optional for R and D subcommands. Optional for R and P subcommands. Optional for R and D subcommands. Optional for R and D subcommands. Optional for P subcommands. Allows execution of suppressed or protected subcommands. Allows output data set naming other than standard default. Allows ddname other than PANDD1 (default) to be used for CA Panvalet library. (Cannot be PANDD2 or PANDD3.) Allows override if system installation option is not to expand INCLUDEs. Causes all CA Panvalet library members beginning with namekey to be selected for listing. Allows override if system installation option is to expand INCLUDEs. Causes retrieval with CA Panvalet formatting and sequence numbers. Overrides CMS. Causes all CA Panvalet library members with requested status to be listed. Numeric value, one to five digits. Specified filename, filetype, and filemode. One to eight position alphanumeric ddname allocated to an CA Panvalet library. (Must allocate before invoking PAN.) Keyword alone. One to eight alphanumeric characters. Keyword alone. Keyword alone. The STATUS parameters and allowable abbreviations are: DISABLE, ENABLE, INACTIVE, ACTIVE, PROD, TEST Chapter 4: PAN Subcommands 29

30 Keyword Summary Keyword Where Used Action Value Format Type language Optional for P subcommands. Causes all CA Panvalet library members with the requested language type to be listed. Allowable values are: ASSEMBLE (assembler) ANSCOBOL (Anscobol) COBOL-72 (Cobol-72) FORTRAN FORTRAN PLI (PL/I) TEXT (Object) AUTOC (Autocoder) ASMB (Assembler) COBOL (Cobol) ANSCB (Anscobol) COB72 (Cobol-72) FORT (FORTRAN) PL/1 (PL/1) RPG (RPG) OBJCT (Object) JCL (JCL) DATA (Data) OTHER (Other) UNSPC (Unspecified) Note: The CA Panvalet CMS Option supports user formats. If you have set up any ZTYPEs, no abbreviations are allowed. User xxxxyyyy Optional for P subcommands. Causes all CA Panvalet library members with the requested user code or range of user codes to be listed. One to four numeric characters for one code. Eight numeric characters for a range of codes. From nn Optional for D subcommands. Causes display to start with specified statement number. One to seven numeric characters. To nn Optional for D subcommands. Causes display to end with specified statement number. One to seven numeric characters. 30 Getting Started

31 Keyword Summary Chapter 4: PAN Subcommands 31

32

33 Chapter 5: User Exits An exit facility is provided to accommodate user-written routines in the PAN Command Processor. The design of the PAN exit facility is similar, though not identical to, the exit facility design for the batch CA Panvalet system. The following capabilities are available to you in the PAN exit structure: Inspect and modify the parameters passed from the user Inspect, modify, add, or delete records or messages to be displayed on the user s terminal Inspect, modify, add, or delete records being retrieved Receive control at end-of-job to complete any processing by the user exit This section contains the following topics: Linkage Conventions (see page 33) Using the Exit (see page 37) Linkage Conventions The PAN Command Processor calls a module named CMSPANEX for each of the following conditions: A first pass allows the user to examine the command. A separate pass for each error message, informational message, or display line created by PAN. The messages are passed before being sent to the user's terminal with the WRTERM macro. Messages created by CMS service routines are not passed to the exit. One pass is made before each record written on a PAN RETRIEVE subcommand; a second pass is possible after each write if the user exit so requests. An end-of-job pass makes PAN immediately return to the system after the return from the user exit. The CA Panvalet Option for CMS passes three arguments to the exit. The arguments are IOAREA, IOCODE, and DIRENTRY. The address of these arguments is in register one. All arguments are not present on all passes and contain varying information depending on the nature of the pass. Register 13 contains the address of an 18 fullword save area where the user must appropriately store the registers. Register 14 accomplishes the return. Chapter 5: User Exits 33

34 Linkage Conventions This register convention must be followed. It is the standard convention used in higher-level languages such as COBOL. The parameters passed generally cannot be altered except where specifically indicated. PAN sets the parameter referred to as IOCODE dependent on the operation being performed. You can change IOCODE to reflect your needs before returning to PAN. Parameters Upon entry to the user exit, register 1 contains the address of the parameter list. The parameter list is organized according to the request as follows: First Pass The first pass with command buffer occurs for all CA Panvalet Option for CMS subcommands. Register 1 points to a 2 fullword parameter list, each fullword containing an address: The first fullword is the address of the parameters passed from the user. The second fullword is the address of a 3-byte code field. Byte 1 is the IOCODE, byte 2 is the PROGRAM, and byte 3 is the RETURN request. These codes can have the following values: IOCODE going to the exit X'05' Before RETRIEVE output. X'06' User requested return. X'08' End-of-job. X'09' Initial pass. X'10' Message pass. IOCODE returning from the exit C'E' Insert a record. C'F' Skip current record. C'G' Go to the end-of-job. no change Process as normal. PROGRAM C'C' Constant value indicating PAN is executing. User cannot change. RETURN going to the exit C'N' A no return setting always set by PAN before going to he exit. 34 Getting Started

35 Linkage Conventions RETURN returning from the exit no change Process as normal. C'Y' Set by the user to indicate a return pass is desired after an output record is written or skipped. This value is ignored unless processing an output file or message pass. For the first pass, the IOCODE has a value of X'09', the PROGRAM always has a value of C'C', and RETURN is not used. Message Pass Any pass for PAN messages/lines occurs with all PAN subcommands, and includes the print lines created during PAN LISTDS, PRINT, or DISPLAY. Register 1 points to a 3 fullword parameter list, each fullword containing an address: The first fullword is the address of a 2 fullword list containing the location and length of the message about to be written to the user's terminal (see the following diagram). Note: The message length can be altered to a maximum of 133 bytes. The second fullword is the address of a 3-byte code field. The first byte (IOCODE) has a value of X'10' for this pass, the second byte (PROGRAM) always has a value of C'C', and the third byte (RETURN) has a value determined by the actions of the user. Chapter 5: User Exits 35

36 Linkage Conventions The third fullword is the address of the directory entry (DIRENTRY). The DIRENTRY currently used by PAN is presented in a 0-up format. If the name (positions 1-10) is blank, no entry is available. Retrieve Pass This pass can be the writing of data (RETRIEVEs only) or an end-of-job pass (last pass, occurs for all subcommands). Register 1 points to a three fullword parameter list, each fullword containing an address: The first fullword contains the address of the record to be written (IOAREA). The second fullword is the address of the 3-byte code field. The values assigned to the three bytes are dependent on the user's use of the pass. 36 Getting Started

37 Using the Exit The third fullword is the address of the directory entry (DIRENTRY). The DIRENTRY currently used by PAN is presented in a 0-up format. If the name (positions 1-10) is blank, no entry is available (see the following diagram). Using the Exit Checks should be made during the first pass (IOCODE=X'09') to determine the PAN subcommand being requested. Only RETRIEVEs will be processing output files. If you want to read or write using your own output data files, you must allocate (by pre-allocation or using FSOPEN) and open your own files. The IOCODE of X'05' indicates that an output file is being processed. PAN passes the EOJ IOCODE (X'08') immediately preceding the return to the operating system. If control is returned to PAN, it goes to the end-of-job regardless of the IOCODE returned to the user. To create a log of all terminal I/O, you can trap the COMMAND buffer in the first pass (IOCODE=X'09') and any PAN terminal output with succeeding IOCODE=X'10' passes. The following types of messages are passed to the exit: All PAN ERROR messages All headers and directory lines created by the PAN LISTD and PAN PRINT subcommands All data provided by the PAN DISPLAY subcommand The remainder of this chapter, on how to use the exit, discusses using the RETRIEVE and DISPLAY subcommands. Chapter 5: User Exits 37

38 Using the Exit PAN RETRIEVE/DISPLAY Output Mode PAN passes an IOCODE of X'05' or X'10', and optionally X'06', when in the output mode. The first fullword in the exit parameter list contains the address of IOAREA, which is 80 bytes in length. An IOCODE of X'05' or X'10' is passed before each write of an output record. You can inspect and modify the input area as desired. This requires no change to IOCODE and a simple return to PAN processes the record as normal. You can place additional records on any output file before or after the current record. You can also skip the current record. Note: Records up to 4096 bytes in length can be passed in output mode. The length of a long record is passed in a fullword, which is at IOAREA minus 4 bytes. When you set the LEXIT option of FGPAN23 to Y, the exit is only called for output members whose logical record length exceeds 80 bytes. Adding Records Before the Current Record The procedure for adding records before the current record follows: 1. Move the current record from the output area to a save area in CMSPANEX. 2. Move the additional record to the output area. 3. Move a C'Y' (return request) to the RETURN code. 4. Return to PAN, which writes the records to the output file or terminal, then returns to the user exit with an IOCODE=X'06' (user requested return). 5. If you want to add more records, move a C'E' (insert a record) to IOCODE and repeat steps 2-4. If no more records are desired, move the original record from the save area to the output area, set the IOCODE to C'E' and return. Adding Records After the Current Record The procedure for adding a record after the current record follows: 1. Move a C'Y' (return request) to the RETURN code. 2. Return to PAN without changing the IOCODE. PAN writes the current record and returns to the exit with an IOCODE=X'06'. 3. Move the new record to the output area. 4. Move a C'E' to the IOCODE and a C'Y' to the RETURN code. 5. Repeat steps 3 and 4 until there are no more records to be added. Then return without changing the IOCODE. 38 Getting Started

39 Using the Exit Skipping Current Records Skip the current record (delete from output) by setting the IOCODE to C'F' and returning. Linking User Exits The procedure for linking the user exits to a system with the CA Panvalet Option for CMS follows: 1. Relink the CA Panvalet Option for CMS to the system from scratch by executing the installation link EXEC (PVLKCMS1). 2. Modify the PVLKCMS1 to specify the SYSTEM option on the GENMOD command, if the exit modifies the parameter list that is passed to the CA Panvalet Option for CMS from the user. 3. Store the text for the user exit as CMSPANEX TEXT. Chapter 5: User Exits 39

40

41 Appendix A: Messages This appendix contains the error messages issued by the CA Panvalet Option for CMS. This section contains the following topics: Error and Informational Messages (see page 41) Other Return Codes (see page 43) Error and Informational Messages REQUIRED SUBCOMMAND MISSING OR INVALID A required parameter for the PAN command has not been supplied or contains invalid characters. Return code = 8. INCORRECT PARAMETER LIST SUPPLIED No parameter list has been supplied where one is required, or necessary user information has been left out. Return code = 8. OPEN FAILURE ON DDNAME ddname FILEDEF for the CA Panvalet library is missing or incorrect. Return code = 16. RETRIEVE WILL WRITE OVER EXISTING FILE. SHOULD WE CONTINUE? ENTER Y OR N. A CMS file already exists with the same filename, filetype, and filemode as the requested retrieval file. A reply of Y results in the existing file being erased and the new file from the CA Panvalet library being created on the specified CMS disk with the return code = 0. A reply of N terminates the command. xxxxxxxxxx NOT FOUND The indicated data set referenced by an embedded ++INCLUDE statement is not present on the CA Panvalet library or the name is an invalid CA Panvalet data set name. This can only occur on a RETRIEVE or DISPLAY subcommand. Return code = 4. xxxxxxxxxx NOT PRODUCTION The indicated data set referenced by an embedded ++INCLUDE statement is in TEST status, while the data set named in the RETRIEVE or DISPLAY subcommand is in the PRODuction status. Return code = 4. Appendix A: Messages 41

42 Error and Informational Messages xxxxxxxxxx PRIVILEGED The indicated data set reference by an embedded ++INCLUDE statement is user security protected and the required access code was not provided. Return code = 4. xxxxxxxxxx INCLUDES SELF An embedded ++INCLUDE statement was found to contain the same name as the including member. Return code = 4. nnnn DATASET(S) SELECTED This informational message indicates that nnnn data sets satisfied the PRINT subcommand selection criteria. SUPPLY PANVALET DATA SET NAME The CA Panvalet data set name was not supplied on a PAN R (RETRIEVE), PAN D (DISPLAY), or PAN L (LISTDS). Enter name. THE PANVALET LIBRARY WAS NOT FULL UPGRADED -- CONTACT YOUR SYSTEMS PROGRAMMER A partial upgrade was performed on this library. The CA Panvalet Option for CMS does not function on this library until the UPGRADE is complete. Contact your systems programmer to resolve the problem. FILE VERSIONS: xxxxxx => nn.n xxxxxx is the file name of the library being accessed. nn.n is the version number of that library. ERROR OBTAINING OR RELEASING STORAGE A DMSFREE or DMSFRET of storage has failed. The return code is from the failing DMSFREE or DMSFRET. xxxxxxxxxx NEST ERROR The maximum number of nested INCLUDE commands as defined in the INCLVLS option of FGPAN23 has been exceeded. xxxxxxxxxx LRECL MISMATCH The LRECL of the INCLUDE member does not match that of the main member. 42 Getting Started