The INPUT parameter defines the general characteristics of each input file to be read.
The INPUT parameter defines the general characteristics of each input file to be read.
The input file can be a sequential tape or disk file, indexed sequential disk file, card file, or VSAM file. The file can also be defined to IDD. One INPUT (IN) parameter is required for each file read. CA Culprit can read and process up to 32 files per run.
During processing, CA Culprit places input data in a contiguous area that is called the
input buffer. If a single input file is read, the buffer contains a single occurrence of the input record; when multiple input files are read, the buffer contains one record from each file.
In a match-file run, CA Culprit establishes a status byte for each input file (a file-specific status byte) and a composite indicator (M*ID) that reflects the status of any or all input files. The file-specific status byte appears in the input buffer following each input record; the composite indicator appears in the last byte position of the input buffer. For more information on match-file runs, see Using CA Culprit for CA IDMS.
This article describes the following information:
Col 2 ▼ ►►─── INput ─┬────────────────────────────────────────────┬───────────────────► └─record-size─┬─ F ◄──┬───┬──────────────┬─┘ ├─ V ───┤ └─block-size─┘ └─ U ───┘ ►─┬──PS ◄──┬───────────────────┬───┬───┬─────────────────────┬───────────────►◄ │ └─ (device-type) ─┘ │ │ ┌─────────────────┐ │ ├─ IS ───┬───────────────────┬───┤ └─▼─input-options─┴─┘ │ └─ (device-type) ─┘ │ ├─ CARD ─────────────────────────┤ ├─ VS ─┬──────────────────┬──────┤ │ └─ ( ─┬─ KS ─┬─ ) ─┘ │ │ ├─ ES ─┤ │ │ └─ RS ─┘ │ └─ UM (module-name) ───────────┘
Expansion of Input-options
►►─┬────────────────────────────────────┬──┬────────────────────────────────┬─► └ DD = ─┬┬─ SYS010 ◄────────────────┬┤ └─ DD2 =file-name logical-unit─┘ │└─ddname─────────────────┘│ ├┬─ SYS010,010 ◄ ───────────┬┤ │└─file-name logical-unit─┘│ └┬─ SYS010 ◄ ───────────────┬┘ └─linkname───────────────┘ ►─┬───────────────────┬──┬─────────────────┬─────────────────────────────────► └─ MB = ─┬─ Keep ──┬┘ └─ PW =password─┘ └─ Dummy ─┘ ►─┬───────────────────────────────────────────────────────────────┬──────────► └─ LT = ─┬─ S ◄──┬─┬──────────────────────────────────────────┬─┘ ├─ N ───┤ └─skip-file-count─┬────────────────────┬─┘ └─ A ───┘ └─skip-block-count─┘ ►─┬──────────────────────────┬──┬────────────────────────────────┬───────────►◄ │ ┌───────────────┐ │ └─ FN =file-name─┬───────────┬─┘ └─ MK = ─▼─field-name──┴─┘ └─version─┘
- INputSpecifies the parameter type. It must be coded starting in column 2.
- record-sizeSpecifies the size of the input record.Record-sizemust be a number in the range 1 through 32767; this value is coded in any column after IN or INPUT. This value is required for all file types (see the following) except CARD.For variable-length records,record-sizeis the length of the longest record in the file; this value must include the 4-byte record descriptor word.
- FSpecifies that the input file contains fixed-length records. F is the default.
- VSpecifies that the input file contains variable-length records.
- USpecifies that the length of the records in the input file is undefined.
- block-sizeSpecifies the size of a physical block of records. This value must be a number in the range 1 through 32767. The following considerations apply toblock-size:
- Under z/VSE,block-sizeis required when the file type is PS or IS (see the following).
- Under z/OS and z/VM,block-sizeis optional. If coded it is for documentation and not used. The block size is taken from the input file.
- Under z/OS LBI - Large Block Interface is supported.
- The INPUT card should use the block size that is associated with the input file (SYS010 by default).
- For fixed-length records,block-sizemust be an even multiple ofrecord-size.
- For variable-length records,block-sizemust equal the longest physical block in the input file and must include the 4-byte block control prefix.
- For records of undefined length,block-sizemust be the same asrecord-size.
- PS (device-type)Specifies sequential file organization. This is the default.Device-typeis an optional qualifier that must be enclosed in parentheses. Possible values fordevice-typeare TAPE, 2311, 2314, 3310, 3330, 3340, 3350, 3370, 3375, 3380, and FBA.
- IS (device-type)Specifies indexed sequential file organization.Device-typeis an optional qualifier that must be enclosed in parentheses. Possible values fordevice-typeare 2311, 2314, 3310, 3330, 3340, 3350, 3370, 3375, 3380, and FBA.Under z/OS and z/VM, users can specifydevice-typefor documentation purposes. Under z/VSE, CA Culprit determines the device type if the file is assigned to a particular device in execution JCL.Device-typemust be specified on the INPUT parameter or assigned in execution JCL. This rule applies even for a tape or disk management system (for example, TFAST, DFAST) that ignores the assignment.
- CARDSpecifies an input card file. If CARD is specified, all other INPUT parameter specifications can be omitted.
- VS(z/OS, z/VSE, and z/VM only) Indicates a virtual storage (VSAM) file organization and can be qualified in one of three ways.If one of the qualifiers is specified, it must be enclosed in parentheses; for example, VS(RS).
- KSIndicates a key-sequenced VSAM file. This is the default.
- ESIndicates an entry-sequenced VSAM file.
- RSIndicates a relative-record VSAM file.
- UM (module-name)Specifies a user input module. The module name must be enclosed in parentheses, and is specified as follows:
- Under z/VSE,module-namemust be the same as the name used on the linkage editor PHASE card when the module was link edited.
- Under z/OS,module-namemust be the name or alias of the load module.
- See the expanded syntax that follows.
- DD =Specifies the ddname (z/OS and z/VM) or filename (z/VSE) for the input file.In a match-file run, the second and subsequent input files default to SYS011, SYS012, and so forth. If DD= is specified, it must appear on the INPUT parameters for each file in the run. These files must be defined in the execution JCL.Ddname,file-nameandlogical-unit, orlinkname-aspecifications must not conflict with CA Culprit system file assignments. These assignments can be changed, as described in the installation instructions for your operating system.
- SYS010/ddname(z/OS and z/VM only) Specifies the name that is assigned to the DD statement that defines the input file; the default is SYS010.
- SYS010,010/file-name logical-unit(z/VSE only) Specifies the name that is assigned to the input file in execution JCL and the number of the device on which the appropriate file resides; the default filename is SYS010.Logical-unitmust be a number in the range 0 through 255. When DD=file-nameis specified,logical-unitmust also be specified. The default logical unit number is SYS010.z/VSE users can use system standard label information as an alternative to inserting input file TLBL or DLBL and EXTENT JCL statements in the CA Culprit job stream. If filenames and logical unit numbers that are used in the standard label information area differ from CA Culprit input file requirements, then a DD= specification can be used to modify CA Culprit requirements, as shown in the following table.
- SYS010/linkname(BS2000/OSD only) Specifies the name that is associated with the input file by the /ADD-FILE-LINK command; the default is SYS010.
System Standard Label Information
// TLBL SYS010,'TAPE-DATA'
// ASSGN SYS010,X'282'
The label information agrees with the CA Culprit input file default, so no specification is required.
// TLBL SYS025,'TAPE-DATA'
// ASSGN SYS010,X'282'
The specification uses the same filename as in the standard label information (SYS025) and specifies the default logical unit number (010). SYS010 must be assigned to the appropriate tape device.
// TLBL TAPEIN,'TAPE-DATA'
// ASSGN SYS015,X'282'
The specification uses the same filename as in the standard label information (TAPEIN) and indicates a logical unit number of 015. SYS015 is assigned to the appropriate tape device.
// DLBL MASTER,'DISK-FILE',0
// EXTENT SYS020,111111,,,19,380
// ASSGN SYS020,DISK,
The specification uses the same filename as on the DLBL statement and the same logical unit number as on the EXTENT statement. SYS020 is assigned to the appropriate disk device.
The first three table entries are tape label examples; the fourth entry is a disk label example. Assignments can be either permanent or made at run time.
- DD2 =file-name logical-unit(z/VSE only) Specifies an alternating assignment for sequential tape or disk files. At run time, CA Culprit treats an end of file condition as if it were an end of volume condition; CA Culprit can therefore read multiple files of the same format as though they were part of a single file. The file type for these files must be PS.File-nameis the name of the alternating file.Logical-unitis a number in the range 0 through 255 that specifies the logical unit number.More considerations for tape and disk files follow:
Under z/OS and z/VM, CA Culprit performs alternate file processing (concatenation) through execution JCL.
- For tape files,file-nameandlogical-unitalternate between the primary file (that is, the file that is defined in the DD= specification or the default) and the file that is identified in the DD2= keyword expression.
- For disk files, CA Culprit reads the first file from the file that is defined in the DD= specification or the default; it reads the second file from thefile-nameandlogical-unitthat is defined in the DD2= specification. File information for any subsequent files is obtained by adding 1 to both thefile-nameand thelogical-unitthat is defined in the DD2= specification;file-namemust be specified in the form SYSnnnwherennnis a 3-digit number in the range 000 through 999.
- MBSpecifies input buffer options as follows:
- KeepApplies to match-file runs. When MB=KEEP is specified, CA Culprit retains a record in the buffer until a new record from the same file replaces it.Dummy
- Specifies that a portion of the input buffer is to be reserved for special handling. The value ofrecord-sizeon this INPUT parameter determines the size of the dummy area. Subsequent REC parameters define specific areas within the dummy area, as required by the CA Culprit program. Space is reserved in the input buffer according to where the MB=DUMMY request is encountered in the input stream.Dummy buffer areas can be used by user procedure modules (see the section "CA Culprit User Modules") or to establish a storage area that is available to all reports in a CA Culprit run.
- PW =passwordA unique 1- to 8-character password that can be inspected by a user input module.If special characters are used (that is, characters other than letters, numbers, or hyphens), the password must be enclosed in single quotation marks. Hexadecimal literals must appear in the form X'password-string'.
- LT =Specifies label type information for PS (sequential) files:
- S(Default) Indicates standard labels.
- NIndicates that labels are omitted on a tape file. Under z/VSE, users can optionally specify a number of files and blocks of data to be skipped over when reading the tape.
- skip-file-countIndicates the number of files (tape marks) to be skipped;
- skip-block-countIndicates the number of blocks of data at the beginning of the file that are to be skipped. Both numbers must be in the range 0 through 32767.
- AIndicates standard and user-defined labels. This specification is invalid for match-file runs.
- MK =field-nameSpecifies from one to four match keys for match-file processing.Field-nameis discussed under REC Parameter.FN =
- Identifies a nondatabase file that is defined to IDD:If this keyword expression is specified and appropriate values are stored in the Integrated Data Dictionary (IDD), IDD automatically supplies the file record size, record type, block size, file type, device type, or user module name and label type. IDD also automatically generates a REC parameter for every field that is referenced on other CA Culprit parameters if the field is in a record in the file.If other specifications appear on an INPUT parameter that specifies FN=file-name, these specifications override values that are stored in IDD unless CA Culprit security is in effect.
- file-nameThe 1- to 32-character name of a file whose field definitions are to be used in subsequent CA Culprit parameters. If the file name contains anything other than letters, numbers, or hyphens, it must be enclosed in quotation marks.
- versionIdentifies the file version being accessed; the default is the highest existing version number for the named file.
Sample INPUT parameters are shown and described in the examples that follow:
INPUT 80 DD=INPUT1
In a z/OS environment, input is a sequential file that contains 80-byte records. The file is identified in the execution JCL on the DD statement named INPUT1.
To define the same input file in a z/VSE environment, the block size (400) and logical unit (20) must also be specified as follows:
INPUT 80 400 DD=INPUT1,20
IN 324 V 328 PS(3350) DD=SYS015,231 LT=N,22
In a z/VSE environment, input is an unlabeled sequential file that is identified on DD statement SYS015. This file contains variable-length records; the size of the longest record is 324 bytes, including the 4-byte record descriptor word. The longest physical block is 328 bytes; this value includes the block control prefix. The file is stored on logical unit SYS231, a 3350 disk volume. The first 22 tape marks are bypassed as specified by the LT= keyword expression.
INPUT 500 5000 PS DD2=SYS016,16
Input is obtained from two sequential files in the z/VSE environment. CA Culprit reads file SYS010 on default logical unit SYS010 and then reads file SYS016 on logical unit SYS016. CA Culprit continues to alternate between these files until the operator requests end of file conditions by responding with an N to a CA Culprit prompt. With disk files, the first file is read from SYS010, the second from SYS016, the third from SYS017, and so forth. At the end of each file, CA Culprit prompts the operator to specify another read operation, as appropriate.
IN 120 UM(INTPROG) PW=LETMEIN *$THIS USER INPUT MODULE SUPPLIES ALL INPUT TO THIS RUN
User-written module INTPROG is a sequential input file that is composed of 120-byte fixed-length records; password verification is required to access INTPROG. To accommodate a comment, the user specified a continuation line by coding an asterisk (*) in column 1; a dollar sign ($) indicates a comment.
PAYROLL-MASTER is the name of a file that is defined to IDD. IDD automatically supplies the information CA Culprit requires to read the file (for example, record size, record type, and file type).