IBM PROGRAMS
Many IBM programs require only one command statement or two OCl statements (lOAD and RUN OCl statements).
The following two examples show the statements needed to load and run two IBM programs, one requiring a command statement and the other requiring two OCl statements .
• The CREATE command statement (see index entry: CREA TE procedure) evokes the $MGBlD utility program:
CREATE MSG1234
• The following two DCl statements load and run the $STATS utility program (see index entry: $STA TS utility program):
II lOAD $STATS II RUN
OBJECT PROGRAMS USING ONE DISK FilE
To load and run an object program that uses one disk file, a FilE OCl statement is required in addition to the lOAD and RUN statements. The NAME parameter is always required in the FilE statement, and the RECORDS or BLOCKS parameter is required for a disk output file. (See index entry: II FILE statement for a com-plete description of FilE statements.)
For example, to load and run the object program PROG1, which uses the disk file NAMEADD, the following OCl statements are required:
I I lOAD PROG 1
II FilE NAME-NAMEADD II RUN
OBJECT PROGRAMS USING MORE THAN ONE DISK FILE
One FilE statement is required for each file used by a program (see index entry:
II FILE statement for a complete description of FilE statements).
Two disk files are named in the following sequence of OCl statements, an input file (lNPUTF) and an output file (OUTPUTF):
II lOAD PROG1 II Fi lE NAME-INPUTF
II FilE NAME-OUTPUTF,BlOCKS-10,RETAIN-P II RUN
Loading and Running Programs 125
The first FilE statement contains information needed to refer to the data in the disk file INPUTF. The second FilE statement contains information needed to create the disk output file OUTPUTF.
OBJECT PROGRAMS USING ONE DISK FILE AND EXTERNAL INDICATORS The SWITCH OCl statement (see index entry: II SWITCH statement) is used to set external indicators (Ul-U8 on RPG 1\ specification sheets) on or off. External indi-cators are used to regulate processing.
In the following example, a program (PROG2) is being run using one existing disk file (lNVMSTR), an inventory master file.
I I lOAD PROG2
II FilE NAME-INVMSTR
II FilE NAME-NEWMSTR,BlOCKS-50 II SWITCH 1XXXXXXX
II RUN
In the example, the SWITCH statement specifies that the first external indicator (U 1) must be turned on before the program (PROG2) creates the file (NEWMSTR). Only one external indicator is used: U 1.
oel
and Procedure ExampleThis section illustrates some of the uses of OCl and command statements through an example of a series of jobs.
The main program is INVUPD (inventory update). INVUPD reads the file named INVTRANS (inventory transactions), updates the file named INVMSTR (inventory master), and prints a report. If INVTRANS is not on the disk, the COPYTRAN procedure is evoked to copy the transactions from a diskette to the disk. After the I NVUPD program is run, SWITCH 1 is checked by an I F expression to determine whether or not the user wants the COPYINV procedure run. The COPYINV procedure copies the updated I NVMSTR to diskette.
The OCl and commCind statements for these jobs are shown in Figure 5. The sets of statements are numbered to correspond to the explanations fol!owing.
oeL and Procedure Example 127
(
II * 'INSERT DISKETTE 888888 *INVTRANS*' II PAUSE
II FILE NAME-COPYIN,UNIT-11,LABEL-INVTRANS,PACK-888888 II FI LE NAME-COPYO,UNIT-F1 ,LABEL-INVTRANS
II RUN
r::i'\
II COpy NAME-INVUPDAT,LlBRARY-P,FROM-READER,TO-F1f4' 0(;;-/1
IFF DATAF1-?1? COPYTRANFigure 5. Oel and Command Statement Example
1. The procedure INVUPD (10) is cataloged in the library as a procedure member.
Note: The sets of statements, 1-4, show II CEND and II END utility control statements. The II CEND utility control statement identifies the end of a source or a procedure member being put into the library. A source or a procedure member statement is preceded by a II COPY utility control state-ment and followed by a II CEND utility control statement. The II END utility control statement indicates the end of utility control statements for a utility program. The II END statement must be the last utility control state-ment entered for that utility program.
2. The procedure COPYTRAN (8) is cataloged in the library as a procedure
6. INVUPDAT INVT~ANS is entered on the keyboard. The procedure INVUPDAT is evoked.
7. The first statement of the INVUPDAT procedure is the IFF (if false) statement.
This statement checks to see if the file identified by the first parameter (I NVTRAN§) in the cOl11mand statement entered on the keyboard exists on the disk. In this example, assume that there is no existing INVTRANS disk file.
Therefore, the' COPYTRAN procedure is evoked in order to copy the INVTRANS diskette file to disk. (If INVTRANS was already on the disk, the statement would not have been false and COPYTRAN would not have been evoked.) 8. The COPYTRAN procedure evokes the $COPY utility program. It also tells the
operator to insert the diskette: 'INSERT DISKETTE 888888 *INVTRANS*'.
After the operator has inserted diskette 888888 and replied to the PAUSE, the
$COPY utility copies the INVTRANS file to the disk.
9. The I NVUPD procedure is evoked.
10. The I NVUPD procedure loads and runs the inventory update program (I NVUPD).
11. After the I NVUPD program has been run, SWITCH1 is checked by an I F state-ment in order to determine if the procedure COPYINV should be evoked. In this example, SWITCH 1 was set to 1. Therefore, the I F statement is satisfied and the COPYINV procedure is evoked. (If SWITCH1 had not been 1, COPYI NV would not have been evoked.)
12. The COPYINV procedure evokes the $COPY utility program. It also tells the operator to insert the diskette: 'INSERT DISKETTE 666666 *INVMSTR*'.
After the operator has inserted diskette 666666 and replied to the PAUSE, the
$COPY utility copies the INVMSTR to diskette.
oel and Procedure Example 129
After the last procedure (COPYINV) is run, the system returns to a ready status (awaits keyboard entry).
Once the procedures are cataloged (steps 1 through 4 in the example), the entire job can be evoked anytime by two statements (steps 5 and 6).
Part 4
System Utility Programs
System Util ity Programs 131
132
Introduction to the System Utility Programs
IBM System/32 system control programming includes a group of utility programs that reside on the disk. These programs do a variety of jobs, from preparing the disk and diskettes for use to maintaining the system library.
WRITING UTILITY CONTROL STATEMENTS
Most of the utility programs require utility control statements. You must provide them. Utility control statements give the utilities information about the output you want and the way in which you want a utility to perform its function. The utilities read these statements from procedures and from the keyboard. Utility control statements must be the first input read by a utility if the utility requires control statements. A II END utility control statement must be the last control statement entered for a utility if control statements are used.
Every control statement is made up of an identifier and parameters. The identifier is a word that identifies the control statement. It is always the first word of the state-ment. Parameters are information you are supplying to the utility. Parameters are either positional or keyword.
A positional parameter, whenever it appears in a statement, must appear in the same position in relation to other parameters. For example:
II INCLUDE PROCEDUR FILEA,YES,NO
FILEA is the first parameter, YES is the second parameter, and NO is the third para-meter. If you omit the second parameter (a valid positional parameter), a comma must indicate the position reserved for the omitted parameter. For example:
II INCLUDE PROCEDUR FILEA"NO
A keyword parameter contains a keyword that distinguishes the parameter from other parameters. For example:
II FILE NAME-COPYIN,UNIT-F1,LABEL-PAYROLL
NAM E-COPYIN, UNIT-F1, and LABEL-PAYROLL are keyword parameters in the preceding statement. COPYIN, F1, and PAYROLL are the values supplied by the parameters to the uti lity.
RULES FOR CODING UTILITY CONTROL STATEMENTS The rules for coding utility control statements are:
1. Statement identifier. II in positions 1 and 2, followed by a blank, must precede the statement identifier. Do not use blanks within the identifier.
2. Blanks. Use one or more blanks between the identifier and the first parameter.
I ntroduction to the System Util ity Programs 133
3. Statement parameters. Keyword parameters can be in any order; but positional parameters muSt be in the same order. Use a comma to separate one parameter from another. Use a hyphen (-) within each keyword parameter to separate the keyword from the inforrnation you supply. Do not use blanks betvveen paiam-eters; do not use blanks within a parameter unless the parameter contains a value enclosed by single quotation marks (for example, 'CONSTANT VALUE').
The following is an example of a utility control statement:
II COPYI1 NAME-JOE,PACK-123456
The statement identifier is COPYI1. The parameter keywords are NAME and PACK.
The information supplied by the parameters is JOE and 123456.
4. II END control statement. This utility control statement indicates the end of utility control statements for a utility. An end control statement must be the last control statement entered for a utility if utility control statements are used. A II END control statement cannot contain other statement in-formation such as a comment or a sequence number. Only II END is valid.
5. Continuation. Some utility control statements can be expressed in two or more records. A record can consist of a maximum of 120 characters, includ-ing blanks and commas, when expressinclud-ing a utility control statement. A utility control statement can be continued if statement parameters are entered.
Rules for using continuation are:
• Place a comma after the last parameter in every record except the last. The comma, followed by a blank, tells the system that the statement is contin-ued in the next record.
• Begin each new record with I I in positions 1 and 2.
• Leave one or more blanks between the II and the first parameter in the record.
The following is an example of a continued utility control statement:
II TRANSFER ADD-NO, I I KEYLEN-5,
II KEYLOC-3
Page of GC21-7593-3 Issued 22 November 1978 By TNL: GN21-7993