Retro1.org codex

STATE                                                       CMS Nucleus command
STATEW

Use the STATE command to verify the existence of a CMS, OS, or DOS file on any
accessed disk; use the STATEW command to verify the existence of a CMS, OS, or
DOS file on any accessed read/write disk.  The formats of the STATE and STATEW
commands are:
+----------+------------------------------------------------------------------+
| STATE    | fn|* ft|* [fm|*]                                                 |
| STATEW   |                                                                  |
+----------+------------------------------------------------------------------+
where:

fn       if the filename of the file whose existence is to be verified.  If fn
         is specified as *, the first file found satisfying the rest of the
         fileid is used.

ft       is the filetype of the file whose existence is to be verified.  If ft
         is specified as *, the first file found satisfying the rest of the
         fileid is used.

fm       is the filemode of the file whose existence is to be verified.  If fm
         is specified, the parent disk and its read-only extensions will be
         searched.  If fm is omitted, or specified as *, all your disks (A-Z)
         are searched.


Usage notes:

1.  If you issue the STATEW command specifying a file that exists on a read-
    only disk, you receive error message DMSSTT002E.

2.  When you code an asterisk in the fn or ft fields, the search for the file
    is ended as soon as any file satisfies any of the other conditions.  For
    example, the command:
       state * file
    executes successfully if any file on any accessed disk (including the
    system disk) has a filetype of FILE.

3.  To verify the existence of an OS or VSE file when DOS is set OFF, you must
    issue the FILEDEF command to establish a CMS file identifier for the file.
    For example, to verify the existence of the OS file TEST.DATA on an OS
    C-disk you could enter:
       filedef check disk check list c dsn test data
       state check list
    where CHECK LIST is the CMS filename and filetype associated with the OS
    data set name.

4.  To verify the existence of an OS or DOS file when the CMS/DOS environment
    is active, you must issue the DLBL command to establish a CMS file
    identifier for the file.  For example, to verify the existence of the DOS
    file TEST.DATA on a DOS C-disk, you could enter:
       dlbl check c dsn test data
       state file check
    where FILE CHECK is the default CMS filename and filetype (FILE ddname)
    associated with the DOS file-id.

5.  You can invoke the STATE/STATEW command from the terminal, from an EXEC
    file, or as a function from a program.  If STATE/STATEW is invoked as a
    function or from an EXEC file that has the message output suppressed, the
    message DMSSTT002E File fn ft fm not found is not issued.

7.  If the STATE/STATEW command is invoked via SVC202 in an assembler program,
    the address of the STATEFST copy is returned at X'1C' into the STATE
    parameter list.

8.  The STATE command disregards the filemode number specified when both the
    filename and filetype are explicitly specified.  When the filename or
    filetype (or both) are specified as asterisk, the filemode number is used.

Responses:

The CMS ready message indicates that the specified file exists.

DMSSTT227I    Processing volume 'no' in data set 'data set name'
   The specified data set has multiple volumes; the volume being processed is
   shown in the message.  The STATE command treats end-of-volume as end-of-file
   and there is no end-of-volume switching.

DMSSTT228I    User labels bypassed on data set 'data set name'
   The specified data set has disk user labels; these labels are skipped.