Tutorial: Creating a Simple Transaction

The Example Program

The example program (SASCSAMP) is designed to produce a formatted report of the SAS/C transient programs used within CICS. The CICS INQUIRE command is used to identify all programs beginning with LSH (the default identifier for SAS/C transient programs). The CICS SEND TEXT command is used to output the report to the CICS terminal screen. Screen details and paging are processed automatically by the SEND command. Because the SEND TEXT command is used, no mapping steps are needed. An error-handling routine is also coded to illustrate how C employs the CICS HANDLE CONDITION command.

The example program follows:

/*- - - - - - - - - - - - - - - - - - - - - - +
|                                             |
|           S A S / C  S A M P L E            |
|                                             |
|          NAME: SASCSAMP                     |
|       PURPOSE: Sample program used in CICS  |
|                Tutorial chapter             |
|  INSTALLATION: Follow the instructions in   |
|                the Tutorial chapter of the  |
|                SAS/C CICS User's Guide.     |
|       COMPILE:                              |
|       EXECUTE:                              |
|         USAGE:                              |
| SYSTAEM NOTES:                              |
|                                             |
+ - - - - - - - - - - - - - - - - - - - - -  */

  /*- - - - - - - - - - - - - - - - - - - */
  /* This sample program produces a list  */
  /* of all the CICS programs that begin  */
  /* with the string "lsh".             */

#pragma options xopts(xref)

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

main()
{
   int  next_resp = 0;
   char header [ ] = "This is a list of SAS/C 
    transient programs\n";
   short hdrlen = sizeof(header) - 1;
   char pgmname [8];
   extern char msg [80];
   extern short msglen;
   void errhndlr();

   EXEC CICS HANDLE CONDITION ERROR(errhndlr);

   EXEC CICS SEND TEXT FROM(header) 
     LENGTH(hdrlen) ACCUM PAGING;

   EXEC CICS INQUIRE PROGRAM START;

   while(next_resp == 0){
    EXEC CICS INQUIRE PROGRAM(pgmname) 
     NEXT RESP(next_resp);
      if (memcmp(pgmname, "LSH", 3))
      continue;
      msglen = sprintf(msg, "   %.8s\n", pgmname);
      EXEC CICS SEND TEXT FROM(msg) 
       LENGTH(msglen) ACCUM PAGING;
   }

   EXEC CICS INQUIRE PROGRAM END;
   EXEC CICS SEND PAGE;
}

   /* Something has gone wrong.*/
   /* Send a message to give a clue why. */
void errhndlr(int errcode)
{
   char savefn [2]; /* area for saving EIBFN */
   memcpy(savefn, _eibptr->EIBFN, 2);

      /* Make sure there's no recursion. */
   EXEC CICS HANDLE CONDITION ERROR;
    /* Purge any partial messages. */
    EXEC CICS PURGE MESSAGE;         

   msglen = sprintf(msg, 
    "CICS Function %02x%02x received 
     error code %d",
        savefn[0], savefn[1], errcode);

   EXEC CICS SEND TEXT FROM(msg) 
    LENGTH(msglen) ERASE;
   exit(-1);
}

If you are familiar with other application languages under CICS, you'll notice after looking over this code that C function names are given as arguments to EXEC command options instead of as program labels. For example, in the following code, errhndlr refers to a SAS/C error-handling function:

EXEC CICS HANDLE CONDITION ERROR(errhndlr);

For more details on this and other SAS/C coding conventions see CICS Command Coding Conventions. The program also provides an example of including options by using #pragma options .

The main function defines variables for the output heading, program name, and message, as well as a prototype for the error-handling routine.

CICS commands are then used to do the following:

handle attention identifiers (HANDLE CONDITION ...)
send data without mapping (SEND TEXT ...)
begin query of CICS system's data (INQUIRE PROGRAM START ...).

As long as there are transient programs to be listed, the program continues, requesting CICS to display the results on the terminal. The program terminates by ending the query process (INQUIRE PROGRAM END ...) and sending the last page of data (SEND PAGE ...).

The error-handling function errhndlr() is used to catch processing errors and print a message instead of relying on default CICS processing. See Using C for CICS Application Programs for more details on handling error conditions.

Chapter Contents
Previous
Next
Top of Page