INPUT Parameter

The INPUT parameter defines the general characteristics of each input file to be read.
idmscu19
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:
2
2
Syntax
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
─┘
Parameters
  • INput
    Specifies the parameter type. It must be coded starting in column 2.
  • record-size
    Specifies the size of the input record.
    Record-size
    must 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-size
    is the length of the longest record in the file; this value must include the 4-byte record descriptor word.
  • F
    Specifies that the input file contains fixed-length records. F is the default.
  • V
    Specifies that the input file contains variable-length records.
  • U
    Specifies that the length of the records in the input file is undefined.
  • block-size
    Specifies the size of a physical block of records. This value must be a number in the range 1 through 32767. The following considerations apply to
    block-size
    :
    • Under z/VSE,
      block-size
      is required when the file type is PS or IS (see the following).
    • Under z/OS and z/VM,
      block-size
      is 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-size
      must be an even multiple of
      record-size
      .
    • For variable-length records,
      block-size
      must equal the longest physical block in the input file and must include the 4-byte block control prefix.
    • For records of undefined length,
      block-size
      must be the same as
      record-size
      .
  • PS (
    device-type
    )
    Specifies sequential file organization. This is the default.
    Device-type
    is an optional qualifier that must be enclosed in parentheses. Possible values for
    device-type
    are TAPE, 2311, 2314, 3310, 3330, 3340, 3350, 3370, 3375, 3380, and FBA.
  • IS (
    device-type
    )
    Specifies indexed sequential file organization.
    Device-type
    is an optional qualifier that must be enclosed in parentheses. Possible values for
    device-type
    are 2311, 2314, 3310, 3330, 3340, 3350, 3370, 3375, 3380, and FBA.
    Under z/OS and z/VM, users can specify
    device-type
    for documentation purposes. Under z/VSE, CA Culprit determines the device type if the file is assigned to a particular device in execution JCL.
    Device-type
    must 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.
  • CARD
    Specifies 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).
    • KS
      Indicates a key-sequenced VSAM file. This is the default.
    • ES
      Indicates an entry-sequenced VSAM file.
    • RS
      Indicates 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-name
      must be the same as the name used on the linkage editor PHASE card when the module was link edited.
    • Under z/OS,
      module-name
      must be the name or alias of the load module.
    input-options
  • 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-name
    and
    logical-unit
    , or
    linkname-a
    specifications 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-unit
    must be a number in the range 0 through 255. When DD=
    file-name
    is specified,
    logical-unit
    must 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
DD= Statement
Explanation
// TLBL SYS010,'TAPE-DATA'
// ASSGN SYS010,X'282'
None
required
The label information agrees with the CA Culprit input file default, so no specification is required.
// TLBL SYS025,'TAPE-DATA'
// ASSGN SYS010,X'282'
DD=SYS025,010
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'
DD=TAPEIN,15
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,
VOL=PRODISK,SHR
DD=MASTER,20
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-name
    is the name of the alternating file.
    Logical-unit
    is a number in the range 0 through 255 that specifies the logical unit number.
    More considerations for tape and disk files follow:
    • For tape files,
      file-name
      and
      logical-unit
      alternate 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 the
      file-name
      and
      logical-unit
      that is defined in the DD2= specification. File information for any subsequent files is obtained by adding 1 to both the
      file-name
      and the
      logical-unit
      that is defined in the DD2= specification;
      file-name
      must be specified in the form SYS
      nnn
      where
      nnn
      is a 3-digit number in the range 000 through 999.
    In response to a DD2= specification, CA Culprit prompts the operator for more input at end of file for each file. If the operator reply is N or n, normal end of file procedures apply; if the reply is Y or y, CA Culprit reads another file, as described previously. If these operations are requested, CA Culprit performs label processing and special positioning for each file.
    Under z/OS and z/VM, CA Culprit performs alternate file processing (concatenation) through execution JCL.
  • MB
    Specifies input buffer options as follows:
  • Keep
    Applies 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 of
    record-size
    on 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 =
    password
    A 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.
  • N
    Indicates 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-count
    Indicates the number of files (tape marks) to be skipped;
  • skip-block-count
    Indicates 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.
  • A
    Indicates standard and user-defined labels. This specification is invalid for match-file runs.
  • MK =
    field-name
    Specifies from one to four match keys for match-file processing.
    Field-name
    is 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-name
    The 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.
  • version
    Identifies the file version being accessed; the default is the highest existing version number for the named file.
Examples
Sample INPUT parameters are shown and described in the examples that follow:
Example 1
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
Example 2
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.
Example 3
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.
Example 4
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.
Example 5
INPUT FN=PAYROLL-MASTER
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).