Domain: File information
The IS-CATALOGED-FILE( ) function checks whether there is a catalog entry with the specified file name. The response when an error occurs (invalid file name, etc.) can be defined.
Format
IS-CATALOGED-FILE( ) IS-CAT-FILE( ) |
FILE = string_expression ,ERROR-REPORTING = *PROC-ERROR-MECHANISM / *RETURN-FALSE ,ERROR-VARIABLE = *NONE / string_expression |
Result type
BOOLEAN
Input parameters
FILE = string_expression
Designates a file and must therefore comply with the SDF data type <filename 1...54 without-gen-vers>.
A filename without catalog and/or user identification is completed according to common DMS rules:
If no user ID is given, the user ID of the current job (i.e. from the SET-LOGON-PARAMETERS command) is used.
If no catalog ID is given, the user's default pubset is used.
ERROR-REPORTING =
You can define if error handling is to be triggered when an error occurs or if the message code of the error message is to be stored in an S variable.
ERROR-REPORTING = *PROC-ERROR-MECHANISM
Error handling is to be triggered when an error occurs, see the section “Error handling”.
ERROR-REPORTING = *RETURN-FALSE
The result FALSE is to be output when an error occurs. No error message is output. The message code of the error message is written in the variable specified in ERROR-VARIABLE = ... .
ERROR-VARIABLE =
An S variable can be defined for the message code. The message code is only written in the variable when ERROR-REPORTING = *RETURN-FALSE was specified in the function call.
ERROR-VARIABLE = *NONE
No S variable is defined .
ERROR-VARIABLE = string_expression
Name of the S variable in which the message code of the error message is written. Note the following items:
If the variable name is specified directly, then it must be enclosed in quotes, otherwise the contents of the variable are interpreted as a variable name.
Data is only written in the S variable when an error occurs (result=FALSE) and ERROR-REPORTING=*RETURN-FALSE was specified. Examples of possible message codes: SDP0439, SDP0440 or DMSxxxx.
If an error occurs while writing to the S variable, then the corresponding error message is output to SYSOUT regardless of the value specified for ERROR-REPORTING, and the S variable does not contain a return value.
Result
TRUE
The file designated in the FILE parameter is cataloged.
FALSE
The file designated in the FILE parameter is not cataloged or an error occurred during a call with ERROR-REPORTING=*RETURN-FALSE.
Error message
SDP0439 LENGTH OF FILE NAME ZERO OR GREATER THAN 54
SDP0440 NAME '(&00)' NOT A FILE NAME OR NOT A SPECIFIC FILE NAME
SDP0441 DMS ERROR '(&00)' WHEN CALLING FSTAT MACRO. IN SYSTEM MODE: HELP-
MSG (&00)
Example 1
A tape file named TAPE.A is to be read. It is necessary to first check whether TAPE.A has already been cataloged or whether TAPE.A must be cataloged before it is imported.
/IF (NOT IS-CATALOGED-FILE(FILE = 'BAND.A')) /IMPORT-FILE SUPPORT=*TAPE(FILE-NAME=BAND.A,DEVICE-TYPE=...,VOLUME=...) /END-IF
Example 2
/DECLARE-VARIABLE NAME=(A(TYPE=*BOOL),B(TYPE=*STRING),C(TYPE=*BOOL))
/A = IS-CATALOGED-FILE(FILE=‘A_A',ERROR-REPORTING=*RETURN-FALSE,/
ERROR-VARIABLE='B')
/C = IS-CATALOGED-FILE(FILE='A_A')
/ . . .
/SET-JOB-STEP
/SHOW-VARIABLE SELECT=*BY-ATTRIBUTES(INITIALIZATION=*ANY)
Trace listing
% 1 1 /DECLARE-VARIABLE NAME=(A(TYPE=*BOOL), B(TYPE=*STRING), C(TYPE=*BOOL)) % 2 1 /A = IS-CATALOGED-FILE(FILE='A_A',ERROR-REPORTING=*RETURN-FALSE,ERROR- VARIABLE='B') % 3 1 /C = IS-CATALOGED-FILE(FILE='A_A') % SDP0440 NAME 'A_A' NOT A FILE NAME OR NOT A SPECIFIC FILE NAME % SDP0431 ERROR 'SDP0440' IN BUILTIN FUNCTION 'IS-CATALOGED-FILE' % SDP0239 ERROR DURING EVALUATION OF RIGHT SIDE OF ASSIGNMENT % SDP0004 ERROR DETECTED AT COMMAND LINE: 3 IN PROCEDURE ':R:$CSLTOM.PROC' % 5 1 /SET-JOB-STEP % 6 1 /SHOW-VARIABLE SELECT=*BY-ATTR(INIT=*ANY) A = FALSE B = SDP0440 C = *NO-INIT *END-OF-CMD