SAS/C Library Reference, Vol. 1

cmsstat -- Fill in a Structure with Information about a File

SYNOPSIS

 #include <cmsstat.h>

 int cmsstat(const char *path, struct cmsstat *buf);

DESCRIPTION

The cmsstat function fills in a cmsstat structure with system-dependent information about a file. For example, information is returned about the number of records in the file and the date the file was last modified. The file can be specified by any filename in the cms, xed, ddn, sf, or sfd style, except that VSAM files are not supported.

buf points to a cmsstat structure as defined in <cmsstat.h>. The cmsstat structure is defined as follows:

 struct cmsstat {
    time_t st_mtime;         /* date last written               */
    unsigned st_type;        /* device type flags               */
    char st_flags;           /* access flags                    */
    char st_recfm;           /* RECFM                           */
    unsigned short st_lrecl; /* LRECL or terminal linesize      */
    int st_norecs;           /* number of logical records       */
                             /*  or number of terminal lines    */
    unsigned short st_bksiz; /* BLKSIZE                         */
    unsigned short st_vaddr; /* device virtual addr. in hex     */
    int st_dblks;            /* number of disk data blocks      */
    short st_dbksz;          /* minidisk blocksize              */
    char st_dlabl[7];        /* null-terminated disk label      */
    union  {
       struct  {             /* CMS fileid (if not S_OS)        */
          char name[9];      /* null-terminated CMS             */
                             /* filename or device name         */
          char type[9];      /* null-terminated CMS filetype    */
          char mode[3];      /* null-terminated CMS filemode    */
       } file;
       char dsn[45]; /* null-terminated MVS DSN (if S_OS)       */
    }  st_fid;       /* file data set name                      */
    char st_mem[9];  /* null-terminated member name (if S_ LIB) */
    char _ [5];      /* unused, a padding element               */
 };

The st_type flag can have one of the following values or a combination of the following values (such as S_OS and S_LIB):

S_DUM: indicates a dummy file.
S_DISK: indicates a CMS disk file.
S_TERM: indicates a terminal.
S_TAPE: indicates a tape file.
S_UR: indicates a unit record device.
S_XED: indicates a file is in XEDIT storage.
S_OS: indicates a file is on an MVS disk.
S_3270: indicates a 3270-type terminal.
S_OSFORMAT: indicates a file is in MVS format.
S_LIB: indicates a MACLIB, TXTLIB, or MVS PDS member.
S_SFS: indicates a Shared File System (SFS) file.
S_SFSDIR: indicates a (SFS) directory.

The st_flags access flag has the following values:

S_RW: indicates a file is read and write.
S_WO: indicates a file is write only.
S_RWX: indicates an extension of a read/write disk.
S_RO: indicates a file is read only.
S_ROX: indicates an extension of a read-only disk.
S_EP: indicates a file or directory is externally protected.
S_NO: indicates no authority on an SFS file or directory.

The following constant is defined for MVS disk files with spanned records:

 S_LRECLX  0x8000

RETURN VALUES

If the file exists, cmsstat returns 0 and fills in the appropriate fields of the cmsstat structure. If the file does not exist or the filename is invalid, cmsstat returns - 1.

CAUTION

You cannot use the cmsstat function to retrieve information about VSAM files.

Fileid or data set name information is always available after a successful call to cmsstat. However, the other fields in the cmsstat structure may not be useful for all types of files. For some files, some of the fields of the cmsstat structure are not meaningful. The values returned for each such field are as follows:

 cmsstat.st_dlabl               ""
 cmsstat.st_vaddr               0xffff
 cmsstat.st_fid.file.name       ""
 cmsstat.st_fid.file.type       ""
 cmsstat.st_fid.file.mode       ""
 cmsstat.st_mtime               (time_t) -1
 cmsstat.st_lrecl               0xffff
 cmsstat.st_bksiz               0xffff
 cmsstat.st_norecs              -1
 cmsstat.st_dblks               -1
 cmsstat.st_dbksz               -1
 cmsstat.st_mem                 ""
 cmsstat.st_recfm               0xffff

If you specify the file with the style prefix xed and XEDIT is not active or the file is not found in XEDIT, the file is searched for on disk.

Fields in the cmsstat structure may have been modified, even if the function returns - 1.

IMPLEMENTATION

For files on a CMS disk, the CMS FSSTATE macro is issued. For CMS (SFS) files and directories, the callable services library routine DMSEXIST is invoked.

EXAMPLE

  #include <cmsstat.h>
  #include <stdio.h>
  #include <string.h>

  #define UNDEF1 0xFFFF

  main()
  {
     struct cmsstat fileinfo;
     int rc;
     rc = cmsstat("cms:user maclib * (member memname)", &fileinfo);
     if (rc != 0)
        return rc;

        /* Check file type.                                      */
     if (fileinfo.st_type & S_LIB)
        puts("File is a member in a MACLIB. ");

        /* Print device's virtual address.                       */
     if (fileinfo.st_vaddr != UNDEF1)
        printf("Minidisk vaddr %x n", fileinfo.st_vaddr);

        /* member name                                           */
     if (strlen(fileinfo.st_mem) == 0)
        puts("Member name not meaningful. ");
     else
        printf("Member name  %s n", fileinfo.st_mem);
     return rc;
  }

RELATED FUNCTIONS

stat, osddinfo, osdsinfo, sfsstat