HP 3000 Computer Systems WA oatcand MPE Commands reference manualHP 3000 Computer Systems MPE Commands Reference Manual tf HEWLETT PACKARD 19447 PRUNERIDGE AVE,, CUPERTINO, CALIFORNIA, 95014 Part No. 30000-90009 Product No. 320028 Printed in U.S.A, 1/81NOTICE ‘The information contained in this document is subject to change without notice. HEWLETT-PACKARD MAKES NO WARRANTY OF ANY KIND WITH REGARD TO THIS MATER. IAL, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. Hewlett-Packard shall not be liable for errors contained herein or for incidental or consequential damages in connection with the furnishing, perfor- mance or use of this material Hewlett-Packard assumes no responsibility for the use or reliability ofits software on equipment that is not furnished by Hewlett-Packard ‘This document contains proprietary information which is protected by copyright. All rights are reserved, No part of this document may be photocopied, reproduced or translated to another program language without the prior written consent of Hewlett-Packard Company. Copyright © 1981 by HEWLETT-PACKARD COMPANY| PREFACE ‘This manual documents the commands which control the Multiprogramming Executive Operating System on the HP 3000. ‘This fourth edition specifies commands and describes the MPE Command Interpreter as compatible with the MPE IV operating system. Readers familiar with previous editions will notice that the ‘manual has undergone internal revisions which result in a more reference type document. Because of this, some of the information you may be used to finding in this manual has been deleted. It is assumed that you know how to log on to your terminal and have some familiarity with the system. If you need further help or information, refer to the ADDITIONAL DISCUSSION section of each command where additional references may be listed ‘As a general guideline, the following supportive documentation will provide any in-depth discussions you may require: © MPE INTRINSICS REFERENCE MANUAL (30000-90010) © USING FILES (30000-90102) © CONSOLE OPERATOR'S GUIDE (30000-90013 & 30070-0025) © SYSTEM MANAGERISYSTEM SUPERVISOR MANUAL (30000-90014)MANUAL PLAN eewevrany eewenrany concerts USAGE USAGE ‘ee sea = INTRODUCTORY | —iamaine ie vag LEVEL ‘an Po 30000-20008 03000-90121 a commano sate umury ununy Inoex "Commands Seamer System Ineo MPE ‘renee Raters vues telenae Mont ‘imal wana Docimens son nos some on sonn-snte som 0s STANDARD USER | LEVEL Y ’ Y Tiss Dupe Dome Ere ftrenee terme, esapes ane ant wna eave Manat | 30000-90010 ‘30000-90012 30000-90015 PROGRAMTATI mn TAGROSTIC USAGE yao SYSTEM SYSTEM WODIFICATION Y MONITORING ___y ACCOUNT MANAGING 7 See Sten apwesstRATVE role naar Soper oe Operas tn a1 somo. ‘SUMMARY LEVEL Sofware Pocket, Guide 30000 s0048 ‘SYNTAX AND ERROR MESSAGESCONVENTIONS USED IN THIS MANUAL NOTATION u italies underlining superscript C return linefeed DESCRIPTION ‘An element inside brackets is optional. Several elements stacked inside a pair of brackets means the user may select any one or none of these elements. xample[] user may selec or B or neither When several elements are stacked within braces the user must select one of these elements. A Example; 1B} user must select A or B or C. c Lowercase italies denote @ parameter which must be replaced by a user-supplied variable. Example; CALL name Dialogue: Where it is necessary to distinguish user input from computer output, the input is underlined, Example: NEW NAME? ALPHAL Control characters are indicated by a superscript C Example: Y° return in italies indicates a carriage return linefeed in italies indicates a linefeed ‘A horizontal ellipsis indicates that a previous bracketed element may be repeated, or that elements have been omitted,CONTENTS Section 1 INTRODUCTION TO COMMANDS How to Use This Manual How to Enter Commands. Command Elements Positional Parameters Keyword Parameters . Continuation Characters Command Errors ...... Sequence Numbers in MPE Commands Executing Command Log On : Executing Commands Programmatically Interrupting Command Execution Interrupting Non-Program Commands Interrupting Program Commands Aborting a Program Back Referencing : Reference Note for Command Definitions Section IL COMMAND SPECIFICATIONS «) COMMAND LOG ON ‘ABORT ALTLOG, ‘ALTSEC ‘APL. ASSOCIATE BASIC :BASICGO BASICOMP, BASICPREP BUILD ‘BYE :COBOL, COBOLGO ‘COBOLPREP COMMENT CONSOLE CONTINUE :DATA ‘DEBUG DISASSOCIATE DISMOUNT DS COPY . :DSLINE . DSTAT EDITOR ‘ELSE ‘ENDIF EOD EOF BOs FCOPY FILE. FORTGO ‘FORTPREP, FORTRAN -FREERIN GETLOG :GETRIN ‘HELLO. HELP IF IML JOB LISTF -LISTLOG... LISTVS ‘MOUNT :MRJE, ‘PREP PREPRUN PTAPE ‘PURGE RECALL REDO RELEASE, -RELLOG, ‘REMOTE REMOTE HELLO RENAME REPORT ‘RESET -RESETDUMP RESTORE, RESUME RIE RPG RPGGO. -RPGPREP RUN SAVE... SECURE ‘SEGMENTER ‘SETCATALOG ‘SETDUMP, ‘SETICW ‘SETMSG ‘SHOWALLOW ‘SHOWCATALOG ‘SHOWDEV ‘SHOWIN ‘SHOWJCW ‘SHOWJOB, ‘SHOWLOGSTATUS, ‘SHOWME, :SHOWOUT. ‘SHOWTIME ‘SPEED SPL... ‘SPLGO ‘SPLPREPCONTENTS (continued) ‘STORE Using the ‘SHOWCATALOG Command 12 STREAM Nesting User-Defined Commands 312 TELL Errors in User-Defined Commands. 343, ‘TELLOP VSUSER Appendix A Page ‘TERMINALS SUPPORTED BY MPE, At Section IIL USER DEFINED COMMAND ara 7 “ rage eee 31 SUBSYSTEM FORMAL FILE DESIGNATORS . B-1 Body 32 Using UBC's 32 APPENDIX C Page Options .. : 35 DETAILS OF PROGRAM EXECUTION cl Using the :SETCATALOG Command 39 Building and Modifying a UDC File INDEX i Using the Editor 310 Title Page Tide Page Code-sharing and Data Privacy Stack Operation : cee C9 Code Segment and Associated Registers Stack Operation Example C10 Data (Stack) Segment and Associated Registers TABLES Tite Non-Program Commands Program Commands (All breakable) Funetional Lists of Commands Page 18 22 Title Page End-ofFile Indicators 2.53 Data Areas in Stack Segment C6INTRODUCTION TO COMMANDS co MPE commands allow you to initiate, control, and terminate the processing of programs and to request various other system operations. You generally use them for functions external to the source-language programs that you write, although many of these functions may be necessary to support those programs, For example, you use commands to: ‘* Initiate an interactive session (:HELLO command) or batch job (:JOB command). '* Display status information about sessions and jobs in the system (‘SHOWJOB), * Create, save, and delete files (:BUILD, ‘SAVE, and :PURGE, respectively); specify and list their characteristics (:FILE and :LISTF); dump them offline and subsequently restore them to the system (‘STORE and :RESTORE); and specify security provisions for them (:ALTSEC, :RELEASE, and SECURE), ‘* Compile programs (:FORTRAN, :COBOL, :RPG, -SPL), prepare those programs (:PREP), and execute them (-RUN). © Determine the status of devices (SHOWDEV and :DSTAT). ‘© Determine the status of devicefiles, which are disc files originating on or destined for non-sharable deviees (‘SHOWIN and :SHOWOUT). © Communicate with other users (:TELL) and with the Console Operator (‘TELLOP). * Define your own commands (SETCATALOG). '* Access private dise volumes (:MOUNT and :DISMOUNT. ‘© Obtain assistance in using the Command Interpreter (:HELP). Many other commands and functions are available as well; complete specifications for all of the commands appear in Section Tl HOW TO USE THIS MANUAL ‘The reference specifications, appearing in Section 11, primarily cover the rules for entering each ‘command. Specifically, they show the command syntax and format; define the parameters and discuss constraints upon them and default values for them; provide an overview of the operation requested by the command; and present examples illustrating proper command entries, Parameter definitions common to more than one command are repeated for each applicable command, to reduce the amount of cross referencing you must do when looking up a definition. ENTERING COMMANDS ‘You can enter commands through any standard input device, typically a terminal (for sessions) or a card reader (for jobs). Each command is accepted by the MPE Command Interpreter, which passes it to the appropriate system procedure for execution, Following this execution, control returns to the Command Interpreter, which is now ready for another command, aCOMMAND ELEMENTS Each MPE command consists of: ‘* Accolon (required in all eases as an MPE command identifier) © Acommand name (required in all cases) © A parameter list (used in most cases) A typical command including all three elements appears as follows: Colon Parameter list X —— RUN PROGENTRYX Command ‘The colon identifies a statement as an MPE command. In an interactive session, MPE prints the colon ‘on the terminal whenever itis ready to accept a command; you respond by entering the remainder of the command after the colon. In a batch job, however, you must enter the colon, placing it in column 1 of the source card (or card image) on which the command is to appear. ‘The command name, which you enter immediately after the colon, requests a specific operation. MPE, prohibits embedded blanks within the name, and rejects the command if they appear. MPE interprets, the next non-alphanumeric character encountered as the end of the command name; typically this character is a blank. Blanks also may appear between the colon and the command name. ‘The parameter list contains one or more parameters that specify options for the command, It is re- ‘quired in some commands, but is optional or prohibited in others, Parameter lists can include position- al parameters and/or keyword parameter groups (defined below), separated from each other by delimiters such as commas, semicolons, equal signs, or other punctuation marks. Normally, you must separate the parameter list from the command name by one or more blanks. However, when you omit the first optional parameter in a positional list, you can begin the list, starting with a comma or other delimiter that normally follows the first parameter, immediately after the command name. The comma in place of blanks serves as a delimiter, as noted under Positional Parameters, below. Within the parameter list, any delimiter can be surrounded by any number of blanks, permitting a free and flexible command format. MPE permits both decimal and octal numbers as command parameters. You distinguish between the two by preceding the octal numbers with a percent sign (%). ‘The end of each command is indicated by the end of the record on which it appears — for example, a carriage return for terminal input or the end of the card containing the command for card input. But if the last non-blank character of the record is a continuation character, the command is continued onto the next record, NOTE Ifyou are running programs in batch job mode, bear in mind that MPE scans all 80 columns on each card image, and thus no characters are ignored, 12POSITIONAL PARAMETERS With positional parameters, the meaning of a parameter depends upon its position in the parameter list. For example, in the FORTRAN command, issued to compile a FORTRAN program, the pat eter list specifies the input file containing the source program, the output file to which the object program is written, and the output file to which the source listing is transmitted, always in that order. In the following :FORTRAN command, for instance, the variable names INP, OUT, and *LST indi- cate the source, object, and list files, respectively. :FORTRAN INP,OUT,*LST In the above example, the asterisk (+) in *LST is not a delimiter but a special character denoting a back reference to a previously defined file. (See BACK REFERENCE, this section). Positional parameters are separated (delimited) from one another by commas. When you omit an optional positional parameter from within a list, you must still include the delimiter that would nor- mally follow that parameter. Thus, on a listing, two adjacent delimiters indicate a missing optional parameter. When you omit a positional parameter that would otherwise immediately follow a com- mand name, indicate this by entering its delimiter as the first character in the parameter list. When ‘you omit positional parameters from the end of the list, however, you need not include delimiters to signify this — the terminating return or end-of-card is sufficient. The following examples demonstrate how to properly omit parameters from a command: ‘FORTRAN, USLFL,*LISTFL,MFL,NFL First parameter omitted. ‘FORTRAN *SOURCEFL,*LISTFL,MFL,NFL — Second parameter omitted. :FORTRAN *SOURCEFL,USLFL,*LISTFL Last two parameters omitted. :FORTRAN All parameters omitted. KEYWORD PARAMETERS When a parameter list is so long that use of positional parameters becomes difficult, MPE provides keyword parameter groups. The meaning of such a group is independent of its position in the list — thus, you can enter keyword groups in any order with respect to each other. A keyword group consists of a keyword that denotes the group’s meaning, sometimes followed by an equal sign and one or more sub-parameters. Kach keyword group is preceded by a semicolon. When more than one sub-parameter appears in a group, they are usually separated from each other by commas. All delimiters can be op- tionally preceded or followed by blanks.The following example shows a :PREP command containing both positional and keyword parameters. INPT and OUTP are the variable names of the positional parameters. DL and CAP are keywords that designate the keyword parameter groups. PH, DS, and ‘MR are sub-parameters of the keyword group designated by CAP. :PREP INPT,OUTP;DL=500,CAP=PH,DS,MR When both keyword groups and positional parameters form a list, the positional parameters always ‘occur before the keyword groups. When you omit trailing parameters from the positional group in this list, you need not include their delimiters since the occurrence of the first keyword indicates the omis- sion, When you omit optional sub-parameters from a keyword group, simply follow the same rules that apply to positional parameters. 13CONTINUATION CHARACTERS When the length of a command exceeds one record (for instance, one entry-line or source card), you may enter an ampersand (&) as the last non-blank character of the record and continue the command on the next record. This next record must begin with a colon (supplied automatically by MPE in interactive processing, but entered by yourself in batch processing). Optionally, you can embed blanks ‘between the colon that begins the continuation record and the first non-blank character in the continu- ation record. In the example below, the command contains a continuation character at the end of the first line and an embedded blank at the beginning of the second, sRUN PROGB;NOPRIV;LMAP;STACK=500;,PARM- : DL=600;L0 ‘You can continue commands up to 268 characters; prompting colons and continuation ampersands are not counted as part of this total. When continuing a command onto another line, you must not divide a command name, keyword, posi tional parameter, or keyword sub-parameter — MPE does not permit any such element to span more than one line. MPE does not begin interpretation of a command until the last record of the command is read. COMMAND ERRORS Ifyou make an error while entering a command in an interactive session, MPE suppresses execution of that command and attempts to determine the cause of the error. If the cause of the error is of a nature that can be pointed out to you easily, MPE prints a caret under the incorrect part of the command, along with an appropriate message. If the command entry is such that MPE cannot print the caret to signify a specific error point, an appropriate error is displayed. In either case, control returns to your terminal. If you enter an erroneous command in a batch file, and do not precede this command with a :CONTINUE command, MPE suppresses execution of the command. An error message is printed on your standard list device, all subsequent commands in this job are ignored and the job is aborted. Ifa command is continued over several lines, and an error is detected, the offending line will be echoed, receded by the line number on which the error has occurred, FILE ABC& 2S TAPES :NEW ()=TAPE. a UNEXPECTED CHARACTER IN FILE NAME; EXPECTED ",” OR“, IS THE DELIMITER BETWEEN PARAMETERS CORRECT? (CIERR 582)SEQUENCE NUMBER IN MPE COMMANDS “MPE commands in spooled jobs may have sequence numbers. The rule is that if the first card image the, the one containing the JOB command) has a postive integer value in the last 8 bytes, MPE tevumes that all MPE commands in the job have sequence numbers in the last eight bytes ‘The sequence field is checked for each command in such a job I the value is less than the preceding aan mand’s sequence number, @ warning is issued, The sequence field may also be all blanks, in whic ase the sequence field is ignored. If the sequence field is non-numeric and non-blank, a warning is EOD command is required after any data following the BASIC >RUN command, or after the >RUN command itself if there is no data. 244EXAMPLE ‘To enter commands and data from your standard input device, with program listing and output trans- mitted to the standard output device, enter: :BASIC ‘To submit BASIC interpreter commands and statements from the command file MYCOMDS, and data from the input file MYDATA, with program listing and output written to the list file MYLIST, enter: :BASIC MYCOMDS,MYDATA.MYLIST (All three files are disc files.) Note that input files created on the Editor must be kept with the UNN option of the Editor KEEP command. ADDITIONAL DISCUSSION Basie Interpreter ManualBASICGO Compiles, prepares, and executes a BASIC program. SYNTAX :BASICGO [commandfile||.listfile] PARAMETERS commandfile Actual designator of input file from which BASIC compiler commands are read. Can be any ASCII input file. Formal designator is BSCTEXT. Default is SSTDINX. listfile Actual designator of file on which program listing is written. Can be any ASCII output file. Formal designator is BSCLIST. Default is $STDLIST. NOTE The formal file designators used in this command (BSCTEXT,BSCLIST) cannot be back referenced as actual file designators in the command parameter list. See the OPERATION section the :FILE command for further information, USE [Available | In Session? YES | In Job? ‘YES In Break? NO. Programmatically? NO [ Breakable? YES (Suspends) OPERATION Compiles, prepares, and executes a program from a SAVE FAST file (created by BASIC interpreter). ‘This enables the program to run faster than it would if executed by the interpreter. After the program is written, it can be saved with the BASIC interpreter command SAVE filename, FAST. The program then can be compiled, prepared, and executed with the :BASICGO command. EXAMPLE To compile, prepare, and execute the BASIC program MYPROG, with the listing directed to the dise file LISTFL, enter: :BASICGO ,LISTFL Calls the BASIC compiler SCONTROL USLINIT,SOURCE Initializes USL and requests program listing $COMPILE MYPROG Compiles program MYPROG SEXIT Exits from compiler ADDITIONAL DISCUSSION Basic Compiler Reference Manual 2:16:BASICOMP Compiles a BASIC program. SYNTAX BASICOMP [commandfile][,(usifile]{.istfile]] PARAMETERS ‘commandfile usifile listfile USE ‘Actual designator of input file from which compiler commands are read. Can be ‘any ASCII input file. Formal designator is BSCTEXT. Default is SSTDINX. ‘Actual designator of user subprogram library (USL) file on which compiled object program is written. Can be any binary output file with filecode of USL. (or 1024). Formal designator is BSCUSL. This parameter, if entered, must specify a file created previously in one of four ways: 1. By saving a USL file (with the SAVE command) created by a previous com- pilation where the default value was used for the uslfile parameter. 2, By building the USL with the Segmenter command -BUILDUSL, (see the MPE Segmenter Reference Manual). 3. By creating a new USL file with the MPE :BUILD command and a filecode parameter of USL or 1024 4. By specifying a non-existent usifile parameter, thereby creating a permanent file of the correct size and type, Default is that $NEWPASS is assigned, ‘Actual designator of file on which program listing is written. Can be any ASCII output file. Formal designator is BSCLIST. Default is $STDLIST. NOTE ‘The formal file designators used in this command (BSCTEXT, BSCUSL, BSCLIST) cannot be back referenced fas actual file designators in the command parameter list. For farther information, see the OPERATION section of the FILE command. |" available In Session? YES In Job? YES In Break? NO Programmatically? NO. Breakable? | YES (Suspends) 247OPERATION Compiles a program from a SAVE FAST file (created by the BASIC interpreter) onto dise in USL format, This enables the program to run faster than it would if left in the form generated by the interpreter. After the program is written, it is stored in a SAVEFAST file with the BASIC interpreter command SAVE filename,PAST. The program can then be compiled with the compiler command COMPILE, prepared with the MPE :PREP command, and executed with the MPE :RUN command, EXAMPLE ‘To compile the BASIC program MYPROG onto the USL named OBJECT, enter: :BUILD OBJECT;CODE =USL Builds USL file ‘BASICOMP ,OBJECT Calls BASIC compiler, specifies USL named OBJECT $COMPILE MYPROG Compiles SAVE FAST program named MYPROG SEXIT Exits from compiler If you do not choose to build a USL file, the :BASICOMP command compiles your file to $OLDPASS (USL default): ‘BASICOMP Runs BASIC compiler, accepting commands from SSTDINX, and requesting $NEWPASS/SOLDPASS for RBM output and $STDLIST for listing output. SCOMPIL MYRUN Compiles from SAVE FAST file named MYRUN ‘onto USL named $OLDPASS. SeXIT Exits from BASIC compiler. If you now want to run your program, use the :PREPRUN command. ‘PREPRUN $OLDPASS Prepares and runs program. ADDITIONAL DISCUSSION Basic Compiler Reference Manual 2.18:BASICPREP Compiles and prepares a BASIC program. SYNTAX BASICPREP [commandfile]|,[progfile][istfile}} PARAMETERS ‘commandfile Progfile listfile USE ‘Actual designator of input file from which compiler commands are read. Can be any ASCII file. Formal designator is BSCTEXT. Default is $STDINX. ‘Actual designator of program file on which prepared program segments are writ- ten. Can be any binary output file with filecode of PROG (or 1028). This param- ter, if entered, must indicate a file created in one of two ways: 1. With the MPE -BUILD command using the filecode parameter PROG or 1029, and a numextents parameter value of 1 2, Byspecifying a non-existent file in the progfile parameter, in which case a job temporary file of the correct size and type is created. Default is that SNEWPASS is assigned, ‘Actual designator of file on which program listing is written. Can be any ASCIT ‘output file. Formal designator is BSCLIST. Default is $STDLIST. NOTE ‘The formal file designators used in this command (BSCTEXT, BSCPROG, BSCLIST) cannot be back refer- enced as actual file designators in the command parameter list. For further information, see the OPERATION section of the :FILE command. Available In Session? YES |_In Job? YES In Break? NO Programmatically? NO Breakable? YES (Suspends) 219OPERATION Compiles and prepares a program from a SAVE FAST file created by BASIC interpreter) into a pro- gram file on dise. This enables the program to run considerably faster than it would if executed by the interpreter. After the program is written, it can be stored in a SAVE FAST file with the BASIC interpreter command SAVE filename,FAST. It then can be compiled/prepared with the MPE :BASICPREP command and executed with the MPE :RUN command. EXAMPLE ‘To compile and prepare a program named MYPROG from the BASIC SAVE FAST file named MYCOMDS, with listing directed to the standard list device, enter: :BASICPREP ,MYCOMDS ‘The file MYCOMDS is an ASCII file that contains the following BASIC compiler commands: SCONTROL USLINIT,SOURCE Initializes USL and lists program SCOMPILE MYPROG Compiles SAVE FAST program SEXIT Exits from compiler ADDITIONAL DISCUSSION Basic Compiler Reference Manual. 2-20Creates and immediately allocates new empty file on dise. SYNTAX F BINARY :BUILD filereference[;REC=[recsize]{,[blockfactor] | {UI Wi Vv ASCIL :cCTL i 1 | ;NOCCTL [TEMP] [DEV=l[dsdevice]# device] [:CODE =/filecode}] | [DISC = [numrec | [, fnumextents }Linitatloe MI) [RIO] [NORIO] MSG] (CIR) PARAMETERS filereference ‘Actual name of file to be ereated, in the following format: filename [lockword } .groupname ] [.acctname) :BUILD Names may contain from 1 to 8alphanumerie characters, beginning with a letter. Ifacctname is specified, it must be that of your log-on account (you cannot create afile in another account). Default groupname and aectname are the log-on group and account. (REQUIRED PARAMETER) resize Record size. A positive number indicates words while negative indicates bytes. For fixed-length files, this is logical record size. For undefined length, this is the maximum record size, For variable length files this is the maximum logical record size if blockfactor is 1. If not, this is used to caleulate the maximum logical record size and physical record size. Records always begin on word boundaries, therefore the record size is rounded up to the nearest word boundary for block size calculations. For a binary file or a variable length ASCII file, odd byte lengths are rounded up and the extra byte is available for data. However, if an odd byte length record size is specified for a fixed or undefined length record file, the extra byte is not available for data. For example: a fixed length ASCII file with record size specified as 11 bytes will have only 11 bytes available for data in each logical record. However, to deter- mine actual blocksize, 12 bytes will be used for the record size (blocksize =12 bytes x blockfactor). Ifthe file was specified as a binary file, the 11 bytes would be rounded up to 12 bytes (6 words), all of which are available for each logical record. Default is determined as device configuration. 221blockfactor RU BINARY ASCII cor. NOCCTL TEMP device Number of logical records per physical block. Default is calculated by dividing the specified recsize into the configured blocksize; this value is rounded downward to ‘an integer that is never less than 1. For variable length record files, blockfactor is always set to 1 after using the original value along with reesize to calculate maximum logical record size and physical record size. Blockfactor is ignored for undefined length records, File contains fixed (F), undefined (U), or variable (V) length records, Default is F for dise files. File contains binary-coded records. Default. File contains ASCII-coded records. Default is BINARY. Indicates carriage-control characters will be supplied with write requests. De- fault is NOCCTL. Indicates carriage-control characters will not be supplied with write requests, Default. File will be created as a job temporary file and will be saved in the joblsession temporary file domain when closed, Default is permanent file Specifies the device on which the file is to reside, entered in one of the following forms: develass ldn **volname The develass form represents a device class name of up to eight alpha-numeric characters beginning with a letter, as for example, DISC or PVDISC1. Ifdevelass is specified, the file is allocated to any available device in that class. If you are opening a file which is to reside on a private volume, you must specify device class DISC; the file then is allocated to any of the home volume set's volumes that fall in that device class, Note that a file cannot span more than one volume set, but can reside on more than one volume within the set, ‘The logical device number (dn) consists ofa three-byte numeric string specifying ® particular device, If you are opening a file which is to reside on a private volume, you must specify a dise drive on which one of the volumes in the home volume set resides, ‘The forms *, *vename, and **volname are used only ifyou are opening a file which is to reside on a private volume. If is specified, the file is allocated to any of the volumes of the home volume set 2.22filecode If *vename (volume class name) is specified, uname must be a member of the home volume set, The file then is allocated to any of the volumes within the volume class. If**volname (volume name) is specified, volname must be a member of the home volume set. The file then is allocated to that volume. ‘Any of the forms may be used to reference files on a remote computer by preceding the device or volume specification with DSDEVICE #. Default is device class name DISC. Code indicating a specially-formatted file. This code is recorded in the file label ‘and is available to processes accessing the file through the FFILEINFO or FGETINFO intrinsic. For this parameter, any user can specify a positive integer ranging from 0 to 1023. Certain integerse have particular HP-defined meanings, as follows: Mnemonic Integer ‘Meaning 400 IMAGE root file. 401 IMAGE data set, 402 IMAGE file for DS information, USL 1024 USL file. BASD 1025 BASIC data file. BASP 1026 BASIC program file. BASFP 027 BASIC fast program file. RL 1028 RL file. PROG 1029 Program file. SL 1031 SL file FORM 1035 VIEW formsfile VFAST 1036 VIEW fast forms file. VREF 1037 VIEW reformat file. XLSAV 1040 Cross Loader ASCII file (SAVE). XLBIN 1041 Cross Loader relocated binary file. XLDSP 1042 Cross Loader ASCII file (DISPLAY). EDITQ 1050 Edit KEEP@ file (non-COBOL). EDTCQ 1051 Edit KEEP@ file (COBOL), EDICT 1052 Edit TEXT file (COBOL). ‘TDP 1058 'TDP/3000 work file. RJEPN 1060 JE punch file. QPROC 1070 QUERY procedure file, 1071 QUERY work fil. 1072 QUERY work file. KSAMK 1080 KSAM key file. GRAPH 1083 GRAPH specification file. sD 1084 Self-deseribing file. LOG 1090 User Logging logfile. OPTLF 1130 On-line performance Tool log file. Using LOG as your designated filecode may not yield the number of records you specify in the DISC= parameter. Most files use the number of records specified in the DISC= parameter as the maximum limit; user logging uses this specified number as @ minimum. Default is 0. 2.28numree numextents initialloc RIO NORIO USE Maximum number of logical records. For fixed and undefined length files the ‘maximum value allowed for this field is 2,147,483,647. However, the maximum. ‘Sectors per file is 2,097,120 based on the maximum of 65535 sectors per extent, 32 extents maximum, Thus the actual maximum number of records will be limited by blocksize (determined by record size and blockfactor. An approximate practical limit for numree is 2,097,119 for variable and undefined files, and 267,382,000 for fixed length files. Default is a value of 1023. NOTE The file system uses these values to compute other charac- teristics of the file as well. Therefore, the values (or default values) specified on the :FILE command may be valid within their respective fields, but may cause overflow errors in the computation of internally needed file specifications. See the Intrinsies Manual for a discussion on calculating file space. Maximum number of disc extents. This is a value from 1 to 32. Default is 8 Number of extents to be initially allocated to the file at the time it is opened. This is a value from 1 to 32, Default is 1. IFRIO is specified, a relative VO file is created. The record length parameter will implicitly be changed to fixed record length. RIO is a special file access method supported by COBOL IL. See the Intrinsics Reference Manual for a discussion of relative 10, A non-relative UO file is created. MSG — A message file is created allowing communication between any set of Processes. Acts like a FIFO (first in, first out) queue where records are read from the start of the file and logically deleted andior appended to the end of file. CIR — Acts as normal sequential file until full. When full, the first physical block will be deleted when the next record is written, and remaining blocks will be logically shifted to front of file. Cannot be simultaneously accessed by readers and writers. Available In Session? YES In Job? YES | In Break? ‘YES Programmatically? YES | Breakable? ue NO No 2.24OPERATION Builds a new file on disc and immediately allocates space for it, initialized to blanks (if an ASCII file) or zeros (if binary file). Unless the TEMP parameter is specified, the file is permanent. (Note that you must have SAVE access to the group to which the new file is to belong and that you can only build a file belonging to your log-on account.) If the home volume set is not mounted for the group in which the new file is to be built, this command will implicitly cause a volume set mount request to be generated. ‘The default characteristics of a file created with the :BUILD command are: standard binary dise file, fixed length records of 128 words, blocking factor of 1, 1 buffer, 1023 record limit, and a maximum of 8 extents with 1 extent initially allocated. EXAMPLE ‘To create a permanent disc file named WORKFILE, with fixed-length records each 80 bytes long, 3 records per block (blockfactor), and in ASCII code, enter: :BUILD WORKFILE;REC 80,8,F ,ASCI:DISC =2000,10,2 ‘The file can reside on any disc, has a maximum capacity of 2000 records divided into 10 extents, with 2 extents allocated immediately. ‘An example of using the :BUILD command to create a new file on a volume set/class is as follows: :BUILD VFILE;DISC =500,10,1;RE ~80;DEV=VCLASS1 Name of existing volume class ‘This file is confined to volumes which reside on devices of that device class. ‘The following example uses the CODE= parameter. In this particular case you wish to create a logging file called NEWDATA: BUILD NEWDATA;DISC =3000,1,1;CODE=LOG ADDITIONAL DISCUSSION Using Files Intrinsies Reference Manual 2.25‘BYE Ends an interactive session, SYNTAX ‘BYE PARAMETERS None USE Available In Session? YES In Job? NO In Break? YES Programmatically? NO Breakable? YES (Aborts log-off message) OPERATION ‘Terminates a session, and displays the cpu time used (in seconds), connect time (in minutes), and the date and time, as follows: CPU=48, CONNECT=35. WED, OCT 12, 197, 10:56 PM. ‘MPE also adds the central-processor time and connect-time, along with the permanent file space used by your session, to the resource-usage counters maintained for your log-on account and group. During your session, you can determine the account and group totals by entering the :REPORT command. If you hang up the receiver prior to logging off at a terminal with a telephone connection, MPE automatically terminates your session by implicitly issuing a :BYE command. If you enter a :HELLO command before logging off, MPE terminates your current session and immediately initiates a new one. If you are logged on at a terminal with a telephone connection, MPE does not disconnect the terminal. Instead, MPE maintains the connection, allowing the new session to begin immediately. EXAMPLE To terminate a session, enter: ‘BYE CPU=1, CONNECT=5, THU, OCT 13, 1977, 12.20 PM 2.26:COBOL Compiles a COBOL program. SYNTAX COBOL [textfile]|.luslfile][,{listfile][,{masterfile]{ newfile]]}} PARAMETERS textfile ‘Actual designator of input file from which source program is read. Can be any ASCII input file. Formal designator is COBTEXT. Default is $STDIN. usifile Actual designator of user subprogram library (USL) file on which object program. is written. Can be any binary output file with flecode of USL (or 1024). Formal designator is COBUSL. If entered, this parameter must indicate a file created in one of three ways: 1. By saving a USL file (with the :SAVE comand) created by a previous compla- tion where the default value was used for the usifile parameter. 2. By building the USL with the Segmenter command -BUILDUSL. (See the MPE Segmenter Reference Manual.) 3. By creating a new USL file with the MPE :BUILD command and a filecode parameter of USL or 1024 Default: $NEWPASS is assigned listfile ‘Actual designator of file on which program listing is written. Can be any ASCII output file, Formal designator is COBLIST. Default is $STDLIST. masterfile ‘Actual designator of master file which is merged against festfile to produce ‘composite source. Can be any ASCII input file. Formal designator is COBMAST. Default is that the master file is not read; input is read from ‘extfile newfile Actual designator of merged textfile and masterfile. Can be any ASCII output file Formal designator is COBNEW. Default is that no file is written. NOTE ‘The formal file designators used in this command (COB- TEXT, COBUSL, COBLIST, COBMAST, COBNEW) cannot bbe back referenced as actual file designators in the com- mand parameter list. For further information, see the OPERATION section of the :FILE command. 2.27USE [Available In Session? YES In Job? YES In Break? NO Programmatically? NO [Breakable YES (Suspends) OPERATION Compiles COBOL program onto a USL file on disc. If you do not specify a source text file, MPE expects input from your standard input device. If you create the USL prior to compilation, you must specify a filecode of USL or 1024. If you do not specify a listfile, MPE sends the program listing to the current list device. EXAMPLE ‘To compile a COBOL program that you enter from your current input device into an object program in the USL file SNEWPASS, and write the listing to your current list device, enter: :COBOL, IF the next command is one to prepare an object program, SNEWPASS can be passed to that command by specifying SOLDPASS for the uslfile parameter. A file can only be passed between commands or programs within the same job’session. ‘To compile a COBOL program residing on the disc file SOURCE into an object program on the USL file OBJECT, with the program listing to be sent to the disc file LISTFL, enter: :BUILD OBJECT;CODE=USL, :COBOL SOURCE,OBJECT,LISTFL ADDITIONAL DISCUSSION COBOL Reference Manual COBOL II Reference Manual 2.28:COBOLGO Compiles, prepares, and executes a COBOL program. SYNTAX COBOLGO [textfile][,{listfle}|,{masterfile][ newfile) PARAMETERS textfile listfile masterfile newfile USE ‘Actual designator of input file from which source program is read. Can be any ‘ASCII input file. Formal designator is COBTEXT. Default is $STDIN. ‘Actual designator of file on which program listing is written. Can be any ASCII output file, Formal designator is COBLIST. Default is $STDLIST. ‘Actual designator of master file which is merged against texffile to produce composite source. Can be any ASCII input file. Formal designator is COBMAST. Default is that the master file is not read; input is read from textfile. Actual designator of merged textfile and masterfile. Can be any ASCII output file. Formal designator is COBNEW. Default is that no file is written, NOTE ‘The formal file designators used in this command (COB- TEXT, COBLIST, COBMAST, COBNEW) cannot be back referenced as actual file designators in the command pa- rameter list. For further information see the OPERATION section of the :FILE command. Available In Session? YES In Job? ‘YES In Break? NO Programmatically? NO. Breakable? ‘YES (Suspends) OPERATION Compiles, prepares, and allocates/executes a COBOL program. If you do not specify textfile, MPE ‘expects your input from your current input device. If you do not specify listfile, MPE writes the listing to your current list device. This command creates a temporary USL file ($NEWPASS) that cannot be accessed, and a temporary program file that can be accessed under the name $OLDPASS. 2.29EXAMPLE ‘To compile, prepare, and execute a COBOL program entered from your current input device, with the Program listing sent to your current list device, enter: COBOLGO. To compile, prepare, and execute a COBOL program from the dise file TEXTEL and send the program listing to the disc file LISTFL, enter: COBOLGO TEXTFL,LISTFL Text filé List file ‘The :COBOLGO command is equivalent to: Text file USL file List file me COBOL TEXTFL,SNEWPASS,LISTFL ‘PREP $0LDPASS,SNEWPASS ‘RUN $OLDPASS ~ Program USL file Program file file ADDITIONAL DISCUSSION Using the HP 3000 COBOL II Reference Manual 2-30