CECI (Command Level Interpreter) and CECS (Syntax Checker)

To check the syntax of, interpret, and run EXEC CICS® commands.

Syntax

{CECI | CECS} [commandName]

Options

commandName: is the name of the CICS API command whose syntax you want to check, or that you want to interpret.

Examples

To read a record with key 009000 from file FILEA:

CECI READ FILE('FILEA') RIDFLD('009000')

Description

CECI allows you to check the syntax of, interpret, and run EXEC CICS commands. CECS allows you to check the syntax of EXEC CICS commands, but does not allow you to run them.

The CECI and CECS transactions perform a dual role in the operation of a CICS system.

When writing application programs, you can check the syntax of the whole CICS command level application programming interface. If you are using CECI, you can carry through most of the commands to invocation, and you can request to see the results of the invocation.
Using CECI provides a means of interaction with the system. For example, you can correct a file control record that has been overwritten with invalid data, create or delete a temporary storage queue, and so on. CECI provides a useful extension to the facilities that are provided by the runtime resource management transaction, CEMT.

Starting and ending CECI or CECS

Start the CECI or CECS transaction directly by entering the transaction identifier CECI or CECS, respectively and, optionally, a CICS command. End the transaction by pressing PF3.

Using the CECI and CECS screens

The command checker and interpreter divides the screen into four areas:

Command Input (the first line of the screen)
Status (the second line of the screen)
Information (21 lines on a 24 x 80 screen)
PF Key Values (the last line of the screen)

Command input

This is the first line of the screen. You use this line to enter the command whose syntax is to be checked, or that is to be performed, either in the normal format, or in an abbreviated or condensed form that reduces the number of keystrokes involved. The condensed form of the command is obtained because of the following reasons:

The keywords EXEC CICS are optional.
You can abbreviate the options of a command to the minimum number of characters that is needed to make each option unique. Valid abbreviations are shown in uppercase characters in the syntax displayed on screen.
The quotes around character strings are optional, and all strings of characters are handled as character-string constants unless they are preceded by an ampersand (&), when they are treated as variables.
Command options that receive a value from CICS at runtime are called “receivers”, and do not have to be specified. The value that is received from CICS is included in the syntax screen after CICS performs the command.

The following example shows the condensed form of a command. You can enter the file control command:

EXEC CICS READ FILE('FILEA') RIDFLD('009000') INTO(data area)

on the command input line, as:

READ FIL(FILEA) RID(009000)

or at a minimum, as:

READ F(FILEA) R(009000)

In this example, the INTO option is a receiver (as defined previously), and you can omit it.

Status

This is the second line of the screen. It contains one of the following messages:

COMMAND SYNTAX CHECK

ABOUT TO EXECUTE COMMAND

COMMAND EXECUTION COMPLETE (or COMMAND NOT EXECUTED)

EXEC INTERFACE BLOCK

VARIABLES

SYNTAX MESSAGES

EXPANSION OF

The status message describes the type of information that is in the information area of the screen.

The COMMAND SYNTAX CHECK status message indicates that CICS has checked the syntax of the entered command, but is not about to perform the command. This is always the status for CECS, and for CECI with a question mark before the command. It is also the status when the syntax check of the command gives severe error messages and for those commands that cannot be run (for example, HANDLE CONDITION and HANDLE AID).

The ABOUT TO EXECUTE COMMAND status message appears when none of the reasons for stopping at COMMAND SYNTAX CHECK applies.

The COMMAND EXECUTION COMPLETE status message appears in response to the ENTER key after an ABOUT TO EXECUTE COMMAND. CICS performs the command and displays the results on the screen.

The EXEC INTERFACE BLOCK status message appears when you press PF4.

The VARIABLES status message appears when you press PF5.

The SYNTAX MESSAGES status message appears when you press PF9.

The EXPANSION OF status message appears when you position the cursor at an option value or a variable, and press ENTER.

Information

This area consists of the remainder of the screen between the command input and status areas at the top, and PF key values at the bottom of the screen. CICS uses this area to display the syntax of the entered command, error message information, the response to the run, and any other information that can be obtained by using the PF keys or the cursor.

A line at the bottom of this area is reserved for messages that describe errors in the conversation with you (for example, INVALID PACKED DECIMAL). CICS highlights these messages to attract attention.

The content of the information area varies, depending on which message is in the status area. The information area of the screen for COMMAND SYNTAX CHECK, ABOUT TO EXECUTE COMMAND, and COMMAND EXECUTION COMPLETE contains information that is common to all three screens.

Command syntax check

CICS displays the full syntax of the command and error information at the bottom of the screen. CICS intensifies options in the syntax panel to show those that are specified on the command input line, those that are assumed by default, and any receivers.

You can modify the command on the command input line at any time by overtyping and pressing the ENTER key.

When an argument is to be displayed in character format, some of the characters might not be displayable. CECI replaces each nondisplayable character by a period (.). You must be aware that periods can indicate either a valid period character, or storage that contains data other than a period. You cannot overtype characters with a period in character format. To overtype a character with a period, you must use PF2 to switch the screen to hexadecimal format and type hexadecimal 2E.

If the command has more options than can be held in one screen, a plus sign (+) appears to the left side of the last option on the current screen to indicate that more exist. You can view these by using one of the scrolling PF keys.

The syntax that is on screen differs slightly from the syntax notation that is used in this book in the following ways:

Square brackets ([ ]) are replaced by the less than (<) and greater than (>) symbols.
Braces { } are not used. If a mandatory option is left out, CICS displays an error message and does not continue performing the command until you specify the option.
Parentheses ( ) are used to indicate that an option requires a value or data field, but you have not specified one.

The error information consists either of a single error message, or an indication of the number and severity of the messages that are generated.

About to execute command

The information area of this screen is similar to that of COMMAND SYNTAX CHECK, but shows no error information. You can modify option values by overtyping them in the syntax information.

This modification is a temporary modification for the duration of the command and does not affect the command input line. It is similar to the modification of option values that is possible with the Execution Diagnostic Facility (EDF) when debugging an application program.

Command execution complete

The information area of this screen is similar to that of COMMAND SYNTAX CHECK, but it displays the results after CICS has performed the command. CICS displays any receivers as intensified, whether they were specified or not, together with their CICS-supplied values. If the value of an option is too long for the line, CICS displays characters only to the end of the line, followed by … to indicate that more information is available. To produce an expanded display of the whole option value, use the tab key to position the cursor at the start of the option value, then press the ENTER key.

CICS displays the appropriate response code (for example, NORMAL) together with the contents of the EIBRESP field of the Exec Interface Block (EIB) at the bottom of the information area.

Note: CECI returns exceptional conditions for some commands, even if the selected options are correct, because CECI checks every option of the command, whether or not you specified the options. You might not have specified an option because you did not need it. Alternatively, you might not have specified particular options because they are mutually exclusive. For example, the ASSIGN command always returns the exceptional condition INVREQ when you check it by using CECI.

Because CECI is an interactive transaction, CICS processes all commands that are running under its control as if the NOHANDLE option were active, thus forcing all responses back to CECI when the command has completed.

EXEC interface block

The information area shows, in response to pressing the PF4 key, the exec interface block. For further information, see EXEC interface block (EIB) fields.

Variables

The information area shows, in response to the PF5 key, all the variables that are associated with the current interpreter session. It shows the name, length, and value of each one.

Normally, the value that is supplied for an option in the command input area is taken as a character string constant. However, sometimes this value must be represented by a variable. The command interpreter recognizes a value as a variable only if it is preceded by an ampersand (&).

You can specify a variable when connecting two associated commands through the values that are supplied in their options; for example, READ INTO (data-area), UPDATE, and REWRITE FROM (data-area). You can use a variable to make the data area in the FROM option the same as that in the INTO option.

A variable is also useful when the values of options cause the command to exceed the line length of the command input area. The commands can be used by creating variables with the required values and specifying the variable names in the command.

You can also use variables to contain commands, and you can enter variable names in a command input line that contains complete or partial commands.

CICS deletes variables at the end of a command interpreter session unless you take action to save them; for example, in temporary storage.

You can use one of the following methods to create variables, which can be of data type character, 32-bit binary, 16-bit binary, or packed decimal:

By naming the variable in a receiver. CICS creates the variable when performing the command. The data type is implied by the type of receiver.
By adding one or more new entries to the list of variables already defined. You request this list by pressing PF5. The screen shows all defined variables giving, for each, its name, length in bytes, and its value. CICS displays the value in character form, but you can use PF2 to switch from character to hexadecimal. You obtain an expanded display of each variable by positioning the cursor under the ampersand (&) of the name and pressing ENTER. To create a new character variable, enter its name and its length and press ENTER. CECI initializes the variable to blanks, which you can then overtype. Enter F (32-bit binary), H (16-bit binary) or P (packed decimal) in the length field. CECI initializes these fields to zero.
You can modify variable names, lengths, and their values, by overtyping. You can delete variables by positioning the cursor under the ampersand (&) of the name and pressing ERASE EOF. You can copy variables by obtaining the expanded display of the variable and overtyping the name field.
By associating a variable name with the value of an option. Using the tab key to position the cursor at the start of the line of the syntax display and pressing ENTER produces an expanded display of the whole option value. You can now assign a variable name to the displayed data.
By entering a name in the NAME= field of the syntax display on screen. This creates a variable containing the current command.

Note: When variables are displayed in hexadecimal, those character variables that contain numerical values are displayed in the byte sequence of the machine, whereas variables of type F, H, or P are displayed with the most significant byte to the left, irrespective of the byte sequence of the machine.

Three variables are provided initially:

&DFHC: A sample.
&DFHW: Contains a temporary storage EXEC CICS WRITEQ command.
&DFHR: Contains an EXEC CICS READQ command.

You can write a command to temporary storage by entering &DFHC in the NAME= field of the syntax display on the screen, entering &DFHW in the command input line, and performing the EXEC CICS WRITEQ command. In this way, you can request a list of commands to be written. The command list can be read and performed by alternately entering &DFHR and &DFHC in the command input line. For example:

CECI WRITEQ TS QUEUE(QUEUE1) FROM (&DFHC)

Syntax messages

The information area shows, in response to pressing the PF9 key, any syntax messages that are associated with the entered command. Each message has an associated severity, which is displayed as a single character and a colon preceding the error message. An example is an error message, which is preceded by “E:”.

If more than one message is generated for a command, the number of messages is also displayed.

Expansion of screen area

The whole of the information area of the screen is used to display an area that is selected by means of the cursor. You can position the cursor at the start of the value of an option on a syntax screen, or under the ampersand of a variable in a variables screen. Press ENTER to get the expanded area screen. You can use the scrolling keys to display all the information if it exceeds a full screen.

Program function (PF) key values

The single line at the bottom of the screen provides a menu that indicates the effect of the PF keys for the display. If your terminal has no PF keys, you can obtain the same effect by using the tab keys to position the cursor under the required item in the menu, and pressing ENTER.

The following PF keys are available:

PF1: Displays help about using the command interpreter or syntax checker and about the meanings of the PF keys.
PF2: Toggles between displaying data in character and hexadecimal forms. All further screens stay in the chosen mode until the next time you press the PF2 key.
PF3: Exits from CECI or CECS, so ends the current session of the interpreter or syntax checker.
PF4: Shows the contents of the EXEC interface block (EIB). This key is not available in the EIB display.
PF5: Shows all the variables that are associated with the current command interpreter session, giving for each its name, length, and value. This key is not available in the variables display.
PF6: Shows what you would see if the terminal had been running a transaction that contained the screen access commands that have been run by using the interpreter. This key is not available from CECS or when you are viewing the user display.
PF7: Scrolls half a page backward.
PF8: Scrolls half a page forward.
PF9: Shows all the messages that are generated during the syntax check of a command. This key is not available in the syntax messages display.
PF10: Scrolls a page backward.
PF11: Scrolls a page forward.
PF12: Undefined.

CECI and CECS begin by generating the CECI or CECS screen area, which is shown in CECI or CECS screen. In this example, a user entered CECI READ FILE('FILEA') RIDFLD('009000').

 
     READ FILE('FILEA') RIDFLD('009000')
     STATUS:    ABOUT TO EXECUTE COMMAND        NAME=
      EXEC CICS  READ
       Dataset() | File(FILEA  )
       SEt() | Into()
       <Length()>
       RIdfld(009000)
       <Keylength() <GEneric> | RBa | RRn>
       <SYsid()>
       <GTeq | Equal>
       <Update>
 
PF 1 HELP 2 HEX 3 END 4 EIB 5 VAR 6 USER 7 SBH 8 SFH 9 MSG 10 SB 11 SF

Running CECI or CECS

To run the command interpreter and syntax checker, you must have a transaction security key (TSL) that matches the transaction security key that is defined in the Transaction Definitions (TD).

The TD entry for the CECI transaction specifies, by default, that resource level security checking is required for any resources that are referenced with the interpreter. This checking applies to files, transient data queues, temporary storage queues, programs, transaction identifiers of the EXEC CICS START command, and journal file identifiers.

If the resource security level (RSL) that is specified in the appropriate resource definition, such as the File Definitions (FD) for a file, is not matched by RSL keys of the user that is signed on, the resource security check fails, and the response to the command is the NOTAUTH condition. This response is given on the command execution complete screen.

The following example gives the screen that is shown in CECI screen after command syntax error.

CECI READ FILE('FILEA')

Note: CICS displays an error message (indicated by E:) near the bottom of the screen. If more than one error message exists, the screen displays a message to press PF9 to see them.

     READ FILE('FILEA')
     STATUS:    COMMAND SYNTAX CHECK           NAME=
      EXEC CICS  READ
       Dataset() | File(FILEA  )
       SEt() | Into()
       <Length( +00020)>
       RIdfld()
       <Keylength() <GEneric> | RBa | RRn>
       <SYsid()>
       <GTeq | Equal>
       <Update>
 
E:  Command requires the option:   'RIDFLD'
 
PF 1 HELP 2 HEX 3 END 4 EIB 5 VAR 6 USER 7 SBH 8 SFH 9 MSG 10 SB 11 SF

Modifying the command input to:

READ FILE('FILEA') RIDFLD('009000')

gives the screen that is shown in CECI screen after the correct command input. The error message has disappeared because you have supplied the requested record identification field.

     READ FILE('FILEA') RIDFLD('009000')
     STATUS:    ABOUT TO EXECUTE COMMAND        NAME=
      EXEC CICS  READ
       Dataset() | File(FILEA  )
       SEt() | Into()
       <Length()>
       RIdfld(009000)
       <Keylength() <GEneric> | RBa | RRn>
       <SYsid()>
       <GTeq | Equal>
       <Update>
 
PF 1 HELP 2 HEX 3 END 4 EIB 5 VAR 6 USER 7 SBH 8 SFH 9 MSG 10 SB 11 SF

The command is now ready to be run, and you do this by pressing the ENTER key. CICS displays the screen that is shown in CECI screen after command has been executed, showing the result of performing the command.

     READ FILE('FILEA') RIDFLD('009000')
     STATUS:  COMMAND EXECUTION COMPLETE
      EXEC CICS  READ
       Dataset() | File(FILEA  )
       SEt() | Into( 'HDGDJH KDFKSJDF KSDJ')
       <Length( +00020)>
       RIdfld(009000)
       <Keylength() <GEneric> | RBa | RRn>
       <SYsid()>
       <GTeq | Equal>
       <Update>
 
  RESPONSE:    NORMAL                        EIBRESP=+000000000
PF 1 HELP 2 HEX 3 END 4 EIB 5 VAR 6 USER 7 SBH 8 SFH 9 MSG 10 SB 11 SF

A question mark (?) before the command gives the command syntax check screen and prevents CICS from performing the command.

The use of CECS forces a question mark before the command. This gives the command syntax check screen and prevents CICS from performing the command. In a system where security is important, you can make CECS more widely available than CECI.