Retrieves information about a file.

Sintaxe

For more information about the use of CICS-value data areas (CVDAs), see Appendix F, CVDAs recognized by the translator.

Descrição:

The EXEC CICS INQUIRE FILE command retrieves information about the named file from the file control table (FCT).
The values that are returned depend on whether the file is local (defined on the same CICS system as the task that is making the inquiry) or remote (defined on another CICS system).
Less information is available for remote files, and so defaults or nulls are returned for some options.

For further information about null values, see Null values.

Comentários:

You can also browse through all the files that are installed in your system by using the browse options (START, NEXT, and END) on INQUIRE FILE commands.
See Using the CICS API commands for general information about browsing, syntax, exception conditions, and examples.

Opções:

ACCESSMETHOD(cvda)
• Returns a CVDA value that identifies the access method for this file.
• The CVDA values are:
  • REMOTE
    • The file is defined as remote.
  • SFS
    • The access method is emulated VSAM that uses the SFS file manager.
  • DB2
    • The access method is emulated VSAM that uses the DB2 file manager.

ADD(cvda)
• Returns a CVDA value that identifies whether new records can be added to the file.
• The CVDA values are:
  • ADDABLE
    • New records can be added to the file.
  • NOTADDABLE
    • New records cannot be added to the file.

BASEDSNAME(data-area)
• Returns the 44-character name of the base file if this is an alternate index.
• If the object is other than an alternate index, this option returns the same value as the value of the DSNAME option.
• Nota:
  • For TXSeries for Multiplatforms, the value for BASEDSNAME is mapped to the BASENAME attribute.
  • When the BASENAME value is returned for the BASEDSNAME attribute, it is always padded with 12 extra characters because the length of BASENAME is only 32 characters.
  • The extra 12 characters cover the 44 character length that is used for the BASEDSNAME attribute.

BASENAME(data-area)
• Returns the 32-character name of the base file if this is a local file. No value is returned if it is a remote file.
• If part of the object is specified in FILESERVER and part in BASENAME, this field holds a part of the 64-character concatenation of the two fields.

BLOCKFORMAT(cvda)
• Returns a CVDA value that identifies whether records on the file are blocked or unblocked. The CVDA values are:
  • BLOCKED
    • The records on the file are blocked.
  • UNBLOCKED
    • The records on the file are unblocked.
• TXSeries for Multiplatforms always returns UNBLOCKED.

BLOCKKEYLEN(data-area)
• Returns a 32-bit binary field that indicates the physical block key length for the file.
• TXSeries for Multiplatforms always returns a null value.
  
• Because the actual null value that is returned depends on the format of the user-defined data area, see Null values for a full description of the different types of null values.

BLOCKSIZE(data-area)
• Returns a 32-bit binary field that indicates the length in bytes of a block.
• TXSeries for Multiplatforms always returns a null value.
• Because the actual null value that is returned depends on the format of the user-defined data area, see Null values for a full description of the different types of null values.

BROWSE(cvda)
• Returns a CVDA value that identifies whether you can browse the file.
• The CVDA values are:
  • BROWSABLE
    • You can browse the file.
  • NOTBROWSABLE
    • You cannot browse the file.

DELETE(cvda)
• Returns a CVDA value identifying whether you can delete records from the file.
• The CVDA values are:
  • DELETABLE
    • You can delete records from the file.
  • NOTDELETABLE
    • You cannot delete records from the file.

DISPOSITION(cvda)
• Returns a CVDA value that indicates whether the file is shared or non-shared.
• The CVDA values are:
  • OLD
    • The file is non-shared.
  • SHARE
    • The file is shared.

DSNAME(data-area)
• Returns the 44-character name of the file.
  • Note:
    • For TXSeries for Multiplatforms, the value for DSNAME is mapped to the BASENAME attribute.
    • When the BASENAME value is returned for the DSNAME attribute, it is always padded with 12 extra characters because the length of BASENAME is only 32 characters.
    • The extra 12 characters cover the 44 character length that is used for the BASEDSNAME attribute.

EMPTYSTATUS(cvda)
• Returns a CVDA value that indicates whether the file is to be set to empty when it is opened.
• The CVDA values are:
  • EMPTYREQ
    • The data set should be made empty.
  • NOEMPTYREQ
    • The data set should not be made empty.

ENABLESTATUS(cvda)
• Returns a CVDA value that identifies whether application programs can access the file.
• The CVDA values are:
  • DISABLED
    • The file is unavailable for access by application programs because it has been explicitly disabled.
    • It must be explicitly enabled by a SET FILE ENABLED command or its CEMT equivalent before it can be accessed by application programs.
  • DISABLING
    • A request to disable or close the file has been received, but tasks are executing that had previously accessed the file.
    • These tasks are allowed to complete their use of the file, but new tasks are not allowed access.
  • ENABLED
    • The file is available for access by application programs.
  • UNENABLED
    • The file is unavailable for access by application programs because it is closed.
    • It must be explicitly enabled by a SET FILE OPEN command or its CEMT equivalent before it can be accessed by application programs.

EXCLUSIVE(cvda)
• Returns a CVDA value that identifies whether records on this file are to be placed under exclusive control when a read for update is issued.
• The CVDA values are:
  • EXCTL
    • A record on this file is placed under exclusive control of the reading task when it is read for update.
  • NOEXCTL
    • A record on this file is not placed under exclusive control when it is read for update.
  • NOTAPPLIC
    • The file type is VSAM or REMOTE.
• TXSeries for Multiplatforms always returns NOTAPPLIC.

FILE(data-value)
• Specifies the 8-character name of the file about which you are inquiring.

FILESERVER(data-value)
• Returns the 32-character name of the base file if this is a local file.
• No value is returned if it is a remote file. If part of the object is specified in FILESERVER and part in BASENAME, this field holds a part of the 64-character concatenation of the two fields.

FWDRECSTATUS(cvda)
• Returns a CVDA value that identifies whether the file is forward-recoverable.
• The CVDA values are:
  • FWDRECOVABLE
    • The file is forward-recoverable.
  • NOTFWDRCVBLE
    • The file is not forward-recoverable.
• TXSeries for Multiplatforms always returns NOTFWDRCVBLE.

INDEXNAME(data-value)
• Returns the 32-character name of the index that is associated with this path to the file.

JOURNALNUM(data-area)
• Returns a 16-bit binary field that indicates the number of the journal on which CICS writes the information that is required for forward recovery of the file.
• If the file is not forward-recoverable, zero is returned.
• TXSeries for Multiplatforms always returns zero.

KEYLENGTH(data-area)
• Returns a 32-bit binary field that indicates the length of the key if the file is associated with a VSAM KSDS.
• If no key exists, zero is returned.

KEYPOSITION(data-area)
• Returns a 32-bit binary field that indicates the starting position of the key field in each record relative to the beginning of the record.
• The start is made at position 0.
• If no key exists, zero is returned.

LSRPOOLID(data-area)
• Returns a 32-bit binary field that indicates the number of the VSAM LSR pool that is associated with this file, in the range 1 through 8.
• If the file does not share buffers, this value is 0.
• TXSeries for Multiplatforms always returns zero.

MAXNUMRECS(data-area)
• Returns a 32-bit binary field that indicates the maximum number of records that the data table for this file can hold.
• A value of zero is returned if the file is not a data table.
• TXSeries for Multiplatforms always returns zero.

OBJECT(cvda)
• Returns a CVDA value that indicates whether the file is associated with a real data set that contains records (a VSAM KSDS, ESDS, or RRDS) or a VSAM path that links an alternate index to its base cluster.
• The CVDA values are:
  • BASE
    • The file is associated with a real data set that contains records.
  • PATH
    • The file is associated with a path.
• TXSeries for Multiplatforms always returns the value of BASE.

OPENSTATUS(cvda)
• Returns a CVDA value that identifies whether the file is open, closed, or in a transitional state.
• The OPENSTATUS value affects the ability of application tasks to access the file, but only indirectly; see the ENABLESTATUS option description for the rules.
• The CVDA values are:
  • CLOSED
    • The file is closed.
  • CLOSING
    • The file is in the process of being closed.
  • OPEN
    • The file is open.

READ(cvda)
• Returns a CVDA value that identifies whether you can read records from the file.
• The CVDA values are:
  • NOTREADABLE
    • You cannot read records from the file.
  • READABLE
    • You can read records from the file.

RECORDFORMAT(cvda)
• Returns a CVDA value that identifies the format of the records on the file. The CVDA values are:
  • FIXED
    • The records are of fixed length.
  • VARIABLE
    • The records are of variable length.

RECORDSIZE(data-area)
• Returns a 32-bit binary field that indicates the actual size of fixed-length records, or the maximum size of variable-length records.

RECOVSTATUS(cvda)
• Returns a CVDA value that identifies whether the file is recoverable.
• The CVDA values are:
  • NOTRECOVABLE
    • The file is not recoverable.
  • RECOVERABLE
    • The file is recoverable.

RELTYPE(cvda)
• Returns a CVDA value that indicates whether relative or absolute addressing is used to access the file.
• The CVDA values are:
  • BLK
    • Relative block addressing is being used.
  • DEC
    • The zoned decimal format is being used.
  • HEX
    • The hexadecimal relative track and record format is being used.
  • NOTAPPLIC
    • Absolute (MBBCCHHR) addressing is being used (or the file is a VSAM file).
• TXSeries for Multiplatforms always returns NOTAPPLIC.

REMOTENAME(data-area)
• Returns the 8-character name by which the file is known in the CICS region that is named in the System ID option of its FCT definition.
• A null value is returned if the file is not remote.

REMOTESYSTEM(data-area)
• Returns a 4-character name of the CICS region in which the file is defined (from the System ID value in the FCT definition).
• A null value is returned if the file is not remote.

STRINGS(data-area)
• Returns a 32-bit binary field that indicates the number of strings (concurrent operations) that are specified for the file in its FILE definition.
• TXSeries for Multiplatforms always returns 1.

TABLE(cvda)
• Returns a CVDA value that indicates whether the file represents a data table.
• The CVDA values are:
  • CICSTABLE
    • The file represents a CICS-maintained data table.
  • NOTTABLE
    • The file does not represent a data table.
  • USERTABLE
    • The file represents a user-maintained data table.
• TXSeries for Multiplatforms always returns NOTTABLE.

TYPE(cvda)
• Returns a CVDA value that identifies the type of data set that corresponds to this file.
• The CVDA values are:
  • ESDS
    • The data set is an entry-sequenced data set.
  • KEYED
    • The data set is addressed by physical keys.
  • KSDS
    • The data set is a key-sequenced data set.
  • RRDS
    • The data set is a relative record data set.

UPDATE(cvda)
• Returns a CVDA value that identifies whether the file can be updated.
• The CVDA values are:
  • NOTUPDATABLE
    • You cannot update records.
  • UPDATABLE
    • You can update records.

Condições:

END
• RESP2 values:
  • No more resource definitions of this type (RESP2=2) exist.

FILENOTFOUND
• RESP2 values:
  • The file cannot be found (RESP2=1).

ILLOGIC
• RESP2 values:
  • You have issued a START command when a browse of this resource type is already in progress, or you have issued a NEXT or an END command when a browse of this resource type is not in progress (RESP2=1).