Using the CICS command-level interface

CICS® TS provides a set of commands to access the CICS transaction server. The format of a CICS command is:

EXEC CICS function [option[(arg)]]...;

In the following CICS command, the function is SEND TEXT. This function has 4 options: FROM, LENGTH, RESP and RESP2. In this case, each of the options takes one argument.

EXEC CICS SEND TEXT FROM(mymsg)
                    LENGTH(mymsglen)
                    RESP(myresp)
                    RESP2(myresp2);

For further information on the EXEC CICS interface and a list of available CICS TS functions, refer to CICS Transaction Server for z/OS.

When you are designing and coding your CICS TS application, remember the following:

The EXEC CICS command and options should be in uppercase. The arguments follow general C or C++ conventions.
Before any EXEC CICS command is issued, the EXEC Interface Block (EIB) must be addressed by the EXEC CICS ADDRESS EIB command.
z/OS® XL C/C++ does not support the use of EXEC CICS commands in macros.

The example program in Figure 1 (CCNGCI1) shows the use of several EXEC CICS commands to perform various tasks.

1: Initialize the CICS interface
2: Access the storage passed from the caller
3: Handle unexpected abends
4 and 7: I/O to RRDS files
5 and 6: Requesting and formatting time

Figure 1. Example illustrating how to use EXEC CICS commands

/* program : GETSTAT            */

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

#define FILE_LEN 40

void check_4_down_status( char *status_record ) ;
void sendmsg( char* status_record ) ;
void unexpected_prob( char* desc, int rc) ;

struct com_struct {
   unsigned int quiet ;
} *commarea ;

 DFHEIBLK *dfheiptr ;

main ()
{
 long int  vsamrrn;
 signed short int  vsamlen;
 unsigned char status_record[41];
 signed long int myresp;
 signed long int myresp2;

                          /* get addressability to the EIB first */
 EXEC CICS ADDRESS EIB(dfheiptr);       1 

                          /* access common area sent from caller */
 EXEC CICS ADDRESS COMMAREA(commarea);      2 

                          /* call the CATCHIT prog. if it abends */
 EXEC CICS HANDLE ABEND PROGRAM("CATCHIT ");      3 

 vsamrrn = 1;
 vsamlen = FILE_LEN;
                          /* read the status record from the file*/
 EXEC CICS READ FILE("STATFILE")      4 
                UPDATE
                INTO(status_record)
                RIDFLD(vsamrrn)
                RRN
                LENGTH(vsamlen)
                RESP(myresp)
                RESP2(myresp2); 
                          /* check cics response                 */
                          /*      -- non 0 implies a problem     */
 if (myresp != DFHRESP(NORMAL))
    unexpected_prob("Unable to read from file",61);

 printf("The status_record from READ in GETSTAT = %s\n", status_record);

 if (memcmp(status_record,"DOWNTME ",8) == 0)
   check_4_down_status(status_record);

 if (commarea->quiet != 1)
   sendmsg(status_record);

 exit(11);
}

 void check_4_down_status( char *status_record )
{
   unsigned char uptime[9];
   unsigned char update[9];
   char curabs[8];
   unsigned char curtime[9];
   unsigned char curdate[9];

   long int  vsmrrn;
   signed short int  vsmlen;
   signed long int dnresp;
   signed long int dnresp2;

   strncpy((status_record+8),update,8);
   strncpy((status_record+16),uptime,8);
   update[8] ='\0';
   uptime[8] ='\0';

                          /* get the current time/date           */
   EXEC CICS ASKTIME ABSTIME(curabs)      5 
                     RESP(dnresp)
                     RESP2(dnresp2);

   if (dnresp != DFHRESP(NORMAL))
      unexpected_prob("Unexpected prob with ASKTIME",dnresp);

                          /* format current date to YYMMDD       */
                          /* format current time to HHMMSS       */
   EXEC CICS FORMATTIME ABSTIME(curabs)      6 
                        YYMMDD(curdate)
                        TIME(curtime)
                        TIMESEP
                        DATESEP; 

   if (dnresp != DFHRESP(NORMAL))
      unexpected_prob("Unexpected prob with FORMATTIME",dnresp);

   curdate[8] ='\0';
   curtime[8] ='\0';

   if ((atoi(curdate) > atoi(update)) ||
      (atoi(curdate) == atoi(update) && atoi(curtime) >= atoi(uptime)))
   {
     strcpy(status_record,"OK                                      ");

     vsmrrn = 1;
     vsmlen = FILE_LEN;

                          /* update the first record to OK       */

     EXEC CICS REWRITE FILE("STATFILE")      7 
                     FROM(status_record)
                     LENGTH(vsmlen)
                     RESP(dnresp)
                     RESP2(dnresp2);

     if (dnresp != DFHRESP(NORMAL))  {
        printf("The dnresp from REWRITE = %d\n", dnresp) ;
        printf("The dnresp2 from REWRITE = %d\n", dnresp2) ;
        unexpected_prob("Unexpected prob with WRITE",dnresp);
     }

     printf("%s %s Changed status from DOWNTME to OK\n",curdate,
             curtime);
   }
}

void sendmsg( char* status_record )
{
  long int msgresp, msgresp2;
  char outmsgÝ80¨;
  int outlen;

  if (memcmp(status_record,"OK ",3)==0)
     strcpy(outmsg,"The system is available.");
  else if (memcmp(status_record,"DOWNTME ",8)==0)
     strcpy(outmsg,"The system is down for regular backups.");
  else
     strcpy(outmsg,"SYSTEM PROBLEM -- call help line for details.");

  printf("%s\n",outmsg);
  outlen=strlen(outmsg); 

  EXEC CICS SEND TEXT FROM(outmsg)
                      LENGTH(outlen)
                      RESP(msgresp)
                      RESP2(msgresp2);

  if (msgresp != DFHRESP(NORMAL))
    unexpected_prob("Message output failed from sendmsg",71);

}

void unexpected_prob( char* desc, int rc)
{
  long int msgresp, msgresp2;
  int msglen;

  msglen = strlen(desc);

  EXEC CICS SEND TEXT FROM(desc)
                      LENGTH(msglen)
                      RESP(msgresp)
                      RESP2(msgresp2);

  fprintf(stderr,"%s\n",desc);

  if (msgresp != DFHRESP(NORMAL))
    exit(99);
  else
    exit(rc);}