EXEC CICS WRITEQ TS FROM(abc)
QUEUE(qname)
RESP(xxx); switch (xxx) {
case DFHRESP(NOSPACE) : Nospace_Cond();
break;
}
In ILE C programs you must have issued an EXEC CICS ADDRESS EIB command to obtain addressability to the EIB prior to using the RESP option.
As the use of RESP implies NOHANDLE, you must be careful when using
RESP with the RECEIVE command in COBOL programs. See “NOHANDLE option” on page 312 for further information.
RESP2(yyy)
“yyy” is a user-defined fullword binary data-area. On return from the command, it contains a value that further qualifies the response to certain commands. Unlike the RESP values, RESP2 values have no associated symbolic names and there is no translator built-in function corresponding to DFHRESP, so you must test the fullword binary value itself.
System programming commands
The system programming commands provide a command-level equivalent to most of the functions of the master terminal (CEMT). (See the
CICS for iSeries
Administration and Operations Guide
.) CICS command-level applications can be written and invoked as CICS transactions to administer the running of the CICS system. This could, for example, provide a subset of the master terminal function, for example, for a particular person or group of people.
The system programming commands have all the advantages of the other EXEC
CICS commands. In particular, they are supported by the CICS command interpreter (CECI), the CICS execution diagnostic facility (CEDF), and the CICS translator.
Note:
There is a difference between the system programming commands and basic application programming commands in that none of the system programming commands can be function shipped. If a CICS resource is defined as remote, its remote definition cannot be retrieved or updated. An exception to this rule is when a CICS TCT is available in a remote system in either model or surrogate form. A change can then be made to the remote definition. The change is not shipped back to the terminal owning region
(TOR). This allows the CICS user to make a change that applies only to the remote TCT.
The system programming commands are:
INQUIRE and SET commands the PERFORM command the DISCARD command
314
CICS for iSeries Application Programming Guide V5
INQUIRE and SET commands
The EXEC CICS INQUIRE and EXEC CICS SET commands allow user-written system programs to look at the information that defines a named CICS resource
(including the installed definition and runtime values) and to change some of the values.
On CICS, these commands give access to the definitions of the following CICS resources: v
Autoinstall terminal models v CICS/400 control region parameters v
Connections v
Files v
Journals v
Programs v
Tasks v
Terminals v
Trace facilities v
Transactions v Transient data queues
Changes to the resource attributes apply only for the duration of the current CICS session and are supported only within the local CICS system.
Although the INQUIRE and SET commands have functions that can be used in application programs, they are intended primarily for user-written system programs and not for general application programs.
The INQUIRE command also has special forms that enable you to browse all of the
runtime definitions for a particular resource. For more information, see “Browsing resource definitions.”
The following general points should be noted: v You do not have to issue an INQUIRE command before issuing a SET command. v
In almost all cases, the items that you can change with a SET command are a subset of those that you can retrieve with an INQUIRE command. If a CICS resource is defined as remote, normally you cannot retrieve or alter its remote definition. This rule applies to the definitions of CICS files, transient data queues, and transactions. v
CICS does not maintain exclusive control of the information that is returned on an INQUIRE command. This means that it can be changed at any time, for example, by issuing a SET command. v If a condition occurs on an INQUIRE command, the command did not execute correctly and the validity of the returned values cannot be guaranteed. v
If a condition occurs on a SET command, as few as possible of the requested changes have been made on return. To establish which, if any, of the changes have been made, you can issue an INQUIRE command.
Browsing resource definitions
The INQUIRE command allows you to retrieve information about a single named resource. The command also has special forms that allow you to browse all of the runtime definitions for a particular resource.
Chapter 31. Programming reference
315
You can browse the definitions for the following resources: v
Autoinstall terminal models v
Connections v
Files v
Journals v
Programs v Terminals v
Transactions v Transient data queues
There is no locking of the retrieved information, which means that a definition can be changed at any time during the browse.
Note that there is no facility for selective browsing; that is, for returning entries only if they meet certain conditions.
The general command format of a browse operation has the following standard pattern, where
resource
represents the resource type (for example, PROGRAM):
INQUIRE
resource
START
Condition:
ILLOGIC
resource
(
data-area
)
Other options as for INQUIRE
resource
Conditions:
END, ILLOGIC
INQUIRE
resource
END
Condition:
ILLOGIC
Descriptions follow of each of the command forms. The information given applies to all browse operations.
INQUIRE
resource
START
This command positions an internal pointer at the first definition in the relevant CICS resource definitions. It does not retrieve any information, nor does it allow you to specify a start point.
Only one browse of a particular resource type is allowed at any one time in a given task. The ILLOGIC condition occurs if a browse is already in progress when an INQUIRE START command for the same resource type is issued.
INQUIRE
resource
(
data-area
) NEXT
The first time this command is issued, it retrieves the name and any requested attributes of the first resource definition. On each successive occasion, it retrieves the name and attributes of the next resource definition, if there is one.
316
CICS for iSeries Application Programming Guide V5
The END condition occurs when you have already retrieved all the entries in the relevant CICS resource definitions. All data-areas specified on the command are left unchanged. Note that the default action for the END condition is to terminate the task abnormally, so you need to detect its occurrence.
You cannot request a selective browse of the resource definitions, and you can only browse forward. All optional attributes that you specify are output fields only and are ignored on input.
CICS maintains a pointer to the current browse position at transaction level, and does not reset it when LINK or XCTL commands are issued.
The ILLOGIC condition occurs if an INQUIRE NEXT command is issued for a resource type that has had no previous INQUIRE START command successfully issued.
INQUIRE
resource
END
This command ends the browse and frees any held resources. You can end a browse at any time after issuing the INQUIRE START command. If you do not issue an INQUIRE END command, the browse terminates at the end of the transaction. A browse operation is not terminated by user syncpoints.
The ILLOGIC condition occurs if an INQUIRE END command is issued for a resource type that has had no previous INQUIRE START command successfully issued.
The following example shows a browse of the processing program table (PPT) that retrieves the name and status of each program defined in the PPT. The entire table is being browsed, so the application issues the INQUIRE PROGRAM NEXT command until the END condition arises, and then issues the INQUIRE
PROGRAM END command.
Null values
If you issue an INQUIRE command to find out the value of an attribute that is not applicable to the named resource, a “null” value is returned in the data-area that you have defined. You also get a null value if the information you have requested is not available at the time of the inquiry.
Null values depend on the format of the user-defined data-area, and are defined as follows: v
Character fields are blanks.
Chapter 31. Programming reference
317
v
Binary fields are −1. v
Pointer fields are X'FF000000'. v
CVDA fields are DFHVALUE(NOTAPPLIC). For further information about the
use of CVDAs, see “CICS-value data areas (CVDAs)” on page 309.
If you issue a SET command that includes one or more null argument values, the corresponding attributes are ignored. This allows the possibility of coding general
SET commands in which some attributes may be left as they are, without having to issue an INQUIRE command first to establish what the current values are. You are most likely to want to do this when the field is defined as a CVDA. However, in all cases, if you simply omit an optional attribute from a SET command, its value remains unchanged.
For CVDAs on SET commands, the null value can be coded as
DFHVALUE(IGNORE), where IGNORE is equivalent to (and has the same numeric value as) NOTAPPLIC on INQUIRE commands.
The SET command is coded as in the following COBOL example:
MOVE DFHVALUE(IGNORE) TO AREA-A.
EXEC CICS SET TDQUEUE(queue_name)
END-EXEC.
This causes the named transient data queue to be enabled, and its open status remains the same as it was before the SET TDQUEUE command was issued.
Simply omitting the OPENSTATUS option from the command would achieve the same effect, but this approach lacks flexibility for some coding situations.
For further information about the use of CVDAs, see “CICS-value data areas
(CVDAs)” on page 309.
PERFORM command
The EXEC CICS PERFORM SHUTDOWN command is used for shutting down the
CICS system.
DISCARD commands
The following CICS resource types can be discarded: v
Autoinstall terminal models v
Files v
Programs v
Transactions
The EXEC CICS DISCARD command removes installed CICS resource definitions from an active CICS/400 control region. The EXEC CICS DISCARD command does not affect the OS/400 user space used to define the CICS resource, therefore the resource can be reinstated using the CEDA Install group function. See
CICS for iSeries Administration and Operations Guide
for further information about using
CEDA to install resource definitions.
EXEC CICS DISCARD commands have the same security attached to them as
EXEC CICS SET commands. The EXEC CICS DISCARD command takes effect
318
CICS for iSeries Application Programming Guide V5
