The SAS/C CICS Command Translator

CICS Command Coding Conventions

The translator accepts any command or command option that can be used in CICS Transaction Server V1R3. However, the translator does not check to see if a particular command is valid for any given release of CICS. Therefore, if you are programming for an earlier version of CICS, you should be careful to use only those commands that are defined in the version of CICS under which you plan to run your program.

Command Format

The general format of a CICS command is EXEC CICS (or EXECUTE CICS), followed by the name of the function (which may be one, two, or three words), and possibly one or more command options. The entire command must be in uppercase letters. Options may require arguments, or may accept optional arguments. For C applications, CICS commands are terminated by a semicolon.

For example, the original CICS command syntax for the CICS READ command is as follows:

EXEC CICS READ

DATASET(name)

FILE(name)

INTO(data-area)

SET(prt-ref)

[LENGTH(data-area)]

RIDFLD(data-area )

[KEYLENGTH(data-value) [GENERIC]]

[SYSID(name)]

[RBA | RRN]

[GTEQ | EQUAL]
.
.
.

[UPDATE]

In your C program, this command can be coded as follows:

EXEC CICS READ
   DATASET("MASTER")
   INTO(record) LENGTH((short) sizeof(struct INPUT))
   RIDFLD(key) KEYLENGTH(keylen);

If you are unfamiliar with the parameters for the CICS READ command, you may want to consult the IBM CICS application programmer's reference appropriate for your site.

Coding Conventions

Observe the following conventions as you write your SAS/C CICS code:

CICS commands can appear anywhere a left brace can appear.
The words EXEC CICS (or EXECUTE CICS) must be coded on the same line. There can be no tokens between EXEC and CICS.
A command can be continued on subsequent lines; however, an option or function name cannot be split across lines (even with a backslash).
Option arguments can be separated from the option by white space, comments, or new-line characters.
Option arguments can contain any C expression of the correct type, and may contain C comments. The arguments may be continued on subsequent lines.
C comments can be used within CICS commands any place white space can appear.
Note: The translator will not recognize a CICS command in a comment, string literal, or character literal. You should also refrain from coding other constructs the translator would try to translate, such as the following statement:
```
   typedef EXEC CICS READ ... ;
```

Commonly Used Data Types

Most often, you will use one of these data types, which can follow the options in CICS commands: data-value, data-area (and CICS-value data area), pointer-value, and pointer-ref. In the context of the C language, these types are used as follows:

data-value

is an expression. Data-value arguments provide input only to the command, so they can be constants, expressions, or variables. The expression must have the expected type; that is, if CICS expects a halfword data-value, then the expression must be of signed or unsigned short type.

data-area

is an lvalue (specifically, a modifiable lvalue, as specified by the ANSI Standard). Data-area arguments may be updated by the CICS command. Therefore, these arguments must be valid objects, for example, variables or storage allocated by the malloc function.

pointer-value

is any expression of pointer type.

pointer-ref

is a pointer-type lvalue where CICS can store an address. The translator prefixes pointer-ref arguments with an ampersand (&). Only pointer-ref arguments are modified by the translator.

Pointer-ref

is coded as shown in the following example:

EXEC CICS ADDRESS CSA(csa_ptr);

The argument csa_ptr should be declared as a pointer variable, for example:

struct CSA *csa_ptr;

In this example, the translator will pass &csa_ptr to CICS. On return from the ADDRESS command, csa_ptr points to the CSA.

Less Common Data Types

Some less commonly used data types are name, label, hhmmss, and cvda:

name: is either a string literal or a pointer (presumably to a string).
label: is always the name of a function (in SAS/C CICS applications).
hhmmss: is an argument for which CICS expects a packed decimal value.
cvda: is a fullword ( int or long int ) value always used in the SET and INQUIRE commands.

name

Usually a CICS name is required to be of some prescribed length (such as BMS map names, which must be seven characters long). If the name is too short, it must be padded on the right with blanks. If you pass a string literal as a name argument, the translator will compute the length of the string and add padding as necessary, as in the following example:

EXEC CICS SEND MAP("ABC") ... ;

The translator will pass the following string to the command:

"ABC""    "

By virtue of C string concatenation, this string is equivalent to "ABC". However, if you pass a pointer to the name, then you are responsible for seeing that the name is blank-padded correctly. Of course, CICS always ignores the trailing '\0' byte at the end. (Because it's past the seventh character, CICS doesn't recognize the trailing '\0'.)

label

The following example uses label as the name of a function:

EXEC CICS HANDLE CONDITION ERROR(err_func);

In this example, err_func defines an error handling routine in your C program. See Using C for CICS Application Programs for more details.

hhmmss

For hhmmss, the translator expects a pointer to an aggregate object, such as a character array or structure, because C has no equivalent to packed decimal data. (See the descriptions for pdset and pdval in SAS/C Library Reference, Volume 1.)

The cvda data type expects a fullword argument; therefore, you can use an int or a long , signed or unsigned . In the SET command, you can use a constant integer or the result of the DFHVALUE function, although using one of the command options is a more likely choice. In the INQUIRE command, use an lvalue.

Doubleword, Fullword, and Halfword Arguments

CICS sometimes describes arguments as doubleword, fullword or halfword. In C terms, a doubleword is a signed or unsigned long long. A fullword is a signed or unsigned int , or a signed or unsigned long . A halfword is a signed short . You can use unsigned shorts , but the compiler will copy it to a temporary and pass the address of the temporary to CICS. This could cause a problem if the variable in question is passed to CICS and then assigned a value (for example, record length). In such a case, CICS will update the temporary, which is probably not what the program is expecting.

Also, if a CICS argument accepts a string literal (names, output lines, and so on), the translator accepts the same string literals that the compiler does. This means that you can use concatenated string literals (for example, "ABC" "DEF") and strings with escape sequences (for example, "\xc1 \xc2 \xc3").

Character Arguments

When a CICS command option expects a single character as an argument, you must use a char pointer argument rather than a character variable. If the argument is a data value, you can also use a string literal. For example, the DATESEP option of the FORMATTIME command expects a character to be used to separate the parts of a formatted date. The methods used in either of the following examples can be used to code this correctly:


Example 1


char *separator = ":";
EXEC CICS FORMATTIME ... DATESEP(separator);


Example 2


EXEC CICS FORMATTIME ... DATESEP(":");

When you use the PROTO translator option (the default) with a char variable or char literal, a prototype mismatch message results.

Prototype Generation

By default, the translator generates a prototype for each CICS command. If the translator expects a C pointer argument, it uses void* in that argument's place in the function prototype. Since void* is the generic pointer type, you can use any pointer type you want for the argument. For instance, a character pointer and a structure pointer are equally acceptable when writing to transient data queues with the WRITEQ TD command using the FROM option, as in the following example:

char *output_buffer;
struct FORMATTED_LINE *line;

EXEC CICS WRITEQ TD FROM(output_buffer) ... ;
EXEC CICS WRITEQ TD FROM(line) ... ;

Chapter Contents
Previous
Next
Top of Page