Chapter Contents

Previous

Next
CMS Low-Level I/O Functions

CMS Low-Level I/O Functions



Descriptions of each CMS low-level I/O function follow.

Portability SAS/C extension


SYNOPSIS
DESCRIPTION
RETURN VALUE
IMPLEMENTATION
EXAMPLE


SYNOPSIS

#include <cmsio.h>

int cmsstate(struct CMSFSCB *fscbp, struct CMSFST *fstp);
int cmsopen(struct CMSFSCB *fscbp);
int cmsread(struct CMSFSCB *fscbp);
int cmswrite(struct CMSFSCB *fscbp);
int cmspoint(struct CMSFSCB *fscbp);
int cmsclose(struct CMSFSCB *fscbp);
int cmserase(struct CMSFSCB *fscbp);


DESCRIPTION

The cmsstate function states or verifies the existence of a CMS disk file. The first argument to cmsstate is a pointer to a CMS File System Control Block ( CMSFSCB ) structure, and the second is a pointer to a CMS File Status Table ( CMSFST ) structure.

The remaining functions are as follows:
cmsopen opens a CMS disk file.
cmsread reads a record from a CMS disk file.
cmswrite writes a record to a CMS disk file.
cmspoint changes the current record pointer of a CMS disk file.
cmsclose closes a CMS disk file.
cmserase erases a CMS disk file.

The header file <cmsio.h> defines two structures for the CMS and XEDIT low-level I/O functions. The first structure maps a CMS FSCB and is defined as follows. (Note that extended FSCBs (FORM=E) are included.)

struct CMSFSCB {   /* CMSFSCB definition            */
   char comm[8];   /* file system command           */
   char fn[8];     /* filename                      */
   char ft[8];     /* filetype                      */
   char fm[2];     /* filemode                      */
   short itno;     /* relative record number        */
   char *buff;     /* address of r/w buffer         */
   int size;       /* length of buffer              */
   char fv;        /* recfm - C'F' or C'V'          */

   char flg;       /* flag byte                     */
   short noit;     /* number of records             */
   int nord;       /* number of bytes actually read */
   int aitn;       /* extended record number        */
   int anit;       /* extended number of records    */
   int wptr;       /* extended write pointer        */
   int rptr;       /* extended read pointer         */
};  

The second structure maps a CMS FST and is defined as follows. (Again, note that the FORM=E fields are included.)

struct CMSFST {
   char fname[8];  /* filename                      */
   char ftype[8];  /* filetype                      */
   short datew;    /* date last written - MMDD      */
   short timew;    /* time last written - HHMM      */
   short wrpnt;    /* write pointer - item number   */
   short rdpnt;    /* read pointer - item number    */
   char fmode[2];  /* filemode - letter and number  */
   short recct;    /* number of logical records     */
   short fclpt;    /* first chain link pointer      */
   char recfm;     /* record format - F or V        */
   char flags;     /* fST flag byte (read/write)    */
   int lrecl;      /* logical record length         */
   short blkcnt;   /* number of 800 byte blocks     */
   short yearw;    /* year last written             */
   int fop;        /* alternate file origin pointer */
   int adbc;       /* alt number of data blocks     */
   int aic;        /* alternate item count          */
   char nlvl;      /* number of ptr block levels    */
   char ptrsz;     /* length of a pointer element   */
   char adati[6];  /* alt date/time (YYMMDDHHMMSS)  */
   int _;
};


RETURN VALUE

All of the functions return the return code from their associated CMS macro. If the return code from FSSTATE is 0, cmsstate copies the information from the CMS FST to the CMSFST structure pointed to by fstp .


IMPLEMENTATION

Each function invokes the associated CMS macro. All of the functions expect an extended format (FORM=E) FSCB. The following table lists each function and the CMS macro it executes:

Function CMS Macro
cmsstate FSSTATE
cmsopen FSOPEN
cmsread FSREAD
cmswrite FSWRITE
cmsclose FSCLOSE
cmspoint FSPOINT
cmserase FSERASE

Refer to the appropriate IBM documentation for information about the data associated with the FSCB and FST and for information about these CMS macros.


EXAMPLE

The following example illustrates an interesting, if none too useful, change from the CMS TYPE command. This program reads a file backward and types each record to stdout .

#include <cmsio.h>
#include <stdlib.h>
#include <stdio.h>
#include <string.h>

main(int argc, char **argv)
{
   struct CMSFSCB fscb;
   struct CMSFST fst;
   register int rc;
   register char *buffer;

      /* Perform error checking as necessary.                      */
   if (argc < 2) {
      puts("Missing fileid");
      exit(4);
   }

   if (argc > 2) {
      puts("Extraneous parameters");
      exit(4);
   }

      /* Call cmspid to tokenize the fileid.                       */
   memset((void *) &fscb,'\0',sizeof(fscb));
   rc = cmspid(argv[1],&fscb);
   if (rc != 0) {
      printf("Fileid "%s" is invalid",argv[1]);
      exit(4);
   }

      /* Call cmsstate to get the file characteristics.            */
   rc = cmsstate(&fscb,&fst);
   if (rc != 0) {
      if (rc == 28)
         printf("File "%s" not found.\n",argv[1]);
      else
         printf("Error occurred while issuing FSSTATE.  RC=%d\n",rc);
      exit(rc);
   }

   buffer = malloc(fst.lrecl + 1);
   if (!buffer)
      exit(8);
      /* Fill in the required FSCB fields.                         */
   fscb.buff = buffer;
   fscb.size = fst.lrecl;
   fscb.fv = fst.recfm;
   fscb.anit = 1;

      /* Set current record number to number of records in file.   */
   fscb.aitn = fst.aic;

      /* Read the file backward; type records to the terminal.   */
   while ((rc = cmsread(&fscb)) == 0 && fscb.aitn > 0) {
      buffer[fscb.nord]= '\0';
      puts(buffer);
      --fscb.aitn;    /* Decrement the current record number.    */
   }

      /* Check for error while reading.                          */
   if (rc > 0) {
      printf("Error occurred while reading "%s".
              RC=%d\n", argv[1],rc);
      exit(rc);
   }
   exit(0);
}


Chapter Contents

Previous

Next

Top of Page

Copyright © 2001 by SAS Institute Inc., Cary, NC, USA. All rights reserved.