Menu principal                 [Fechar]


CICS Manual do Usuário - Command options


Volta a página anterior

Volta ao Menu Principal


Desenvolvido por DORNELLES Carlos Alberto - Analista de Sistemas - Brasília DF.

Command options

This section provides information about using the following options that appear on several commands:

INTO and SET

If an application is to receive data by issuing a RECEIVE command, you must specify either the INTO or the SET option.
These options specify the address of data that is received.
The guidelines for using either INTO or SET are as follows:

  • Use INTO if your application program provides a suitable buffer to which CICS should return data.
  • Use SET if you want CICS to obtain a suitably sized buffer.
    Note that CICS might, at a later time, reuse buffers that were generated with the SET option.
    The minimum life of a SET buffer varies from command to command and is documented with each command.

If an application issues a RECEIVE command simply to test whether a terminal user has pressed an attention identifier (AID) key, you can leave out both the INTO and the SET option.
If an application uses a RECEIVE to accept an AID, ensure that the application issues a HANDLE AID command before the RECEIVE.
See HANDLE AID for more information about the attention identifier keys.

KEYLENGTH and RIDFLD

Unless a GENERIC key is used, the KEYLENGTH must always be equal to the full key length of the file.
Also, the KEYLENGTH indicates the size of the RIDFLD data area.

LENGTH

In COBOL and PL/I, the translator can set the value of particular lengths.
This means that they are optional in programs that specify data areas.

In C, C++ , you must specify all LENGTH options, except on the SEND MAP, RECEIVE MAP, READ, READNEXT, READPREV, REWRITE, WRITE, DEQ, and ENQ commands.

If you use the ENQ command without a LENGTH option, CICS assumes that the command is applied to an address (for example the CWA).
If you use the ENQ command with a LENGTH option, CICS assumes that the command is applied to a name (which can be 1 through 255 bytes long).

When a CICS command includes the LENGTH option, you generally express this option as a signed 16-bit binary value (the command description tells you what the value should be).
This places a theoretical upper limit of 32767 bytes on LENGTH. In practice (depending on conventions of recoverability, function shipping, and so on) the achievable upper limit varies from command to command, but is somewhat less than this theoretical maximum.

The FLENGTH option, where available, allows you to specify any length value up to 2048 MB, but for application portability, it is recommended that you do not use more than 24 MB.
Some commands have limits that are significantly below this. For example, RECEIVE and SEND have a limited FLENGTH of 32767 bytes.

NOHANDLE

You can use the NOHANDLE option with any command to specify that you want CICS to take no action for any condition or attention identifier (AID) that results from the running of the command.

The NOHANDLE option covers all conditions that can occur for the commands on which you have specified NOHANDLE; the IGNORE CONDITION command covers specified conditions for all commands (until you change its effect by specifying a HANDLE CONDITION command that names one or more of these conditions).

You must be careful when using NOHANDLE with the RECEIVE command, because NOHANDLE overrides the HANDLE AID command in addition to the HANDLE CONDITION command, with the result that CICS ignores PF key responses.

Note that when using the C or C++ languages, every EXEC CICS command is handled as if it has the NOHANDLE option specified.
For more information, see the TXSeries for Multiplatforms Application Programming Guide .

RESP and RESP2

You can use the RESP option with any command to test whether CICS raised a condition when running the command.
For SET commands only, where the INVREQ condition might occur for more than one reason, you can use the RESP2 option to find out why the condition occurred.

RESP(xxx)
In this example, xxx is a user-defined 32-bit binary data area.
On return from the command, xxx contains a value that corresponds to a condition that CICS might have raised, or to a normal response; that is:
xxx=DFHRESP(NORMAL).

You can use the DFHRESP translator built-in function to test the returned status.

In COBOL you can test the returned RESP value as follows:

     EXEC CICS WRITEQ TS FROM('abc')
          QUEUE(qname)
          RESP(xxx)
     END-EXEC.

IF xxx = DFHRESP(NOSPACE) THEN ...

In PL/I you can test the returned RESP value as follows:

     EXEC CICS WRITEQ TS FROM('abc')
          QUEUE(qname)
          RESP(xxx);
     EBD-EXEC

IF xxx = DFHRESP(NOSPACE) THEN ...

In C or C++ a similar test is:

     EXEC CICS WRITEQ TS FROM("abc")  
          LENGTH(3)  
          QUEUE(qname)
          RESP(xxx);
          switch(xxx) {
            case DFHRESP(NORMAL) : break;
            case DFHRESP(INVREQ) : Invreq_Cond(); break;
          default : Errors();
                      }
 	  END-EXEC

Because the use of RESP implies NOHANDLE, you must be careful when using RESP with the RECEIVE command, because NOHANDLE overrides the HANDLE AID command in addition to the HANDLE CONDITION command.
The result is that CICS ignores PF key responses.

RESP2(yyy)
In this example, yyy is a user-defined 32-bit binary data area.
On return from the command, yyy contains a value that further qualifies the response to particular commands.
RESP2 values are unique within a command.
For CICS, this applies to INQUIRE and SET commands only.

SYSID

The SYSID option appears on the ALLOCATE command and most file services, timer services, program execution, temporary storage, and transient data commands.
It is a four-character name. Each CICS region has a local SYSID. On CICS, it is configured in the LocalSysId attribute of the Region Definition (RD) entry. In addition, a CICS region can have entries in the Communications Definitions (CD), each of which defines a connection to a remote system.
The name of a CD entry is referred to as a remote SYSID or a connection name.
These remote SYSIDs are known only to the local region and do not have to match the name of the remote system at the other end of the connection.

The SYSID option on the ALLOCATE command allows an application to specify a remote SYSID only.
This is because ALLOCATE is starting a Distributed Transaction Processing (DTP) conversation with a program that is running on a remote system.

The SYSID option on other commands can be a local or a remote SYSID.
It is used to specify where the resource resides.

  • If the local SYSID is specified, the resource resides on the local CICS region.
    The resource must be defined in the local resource definition.
    In addition, the local definition for the resource must not have the RemoteSysId attribute set to a remote SYSID, otherwise CICS generates an AEY9 abnormal termination.
  • If a remote SYSID is specified, CICS uses an intersystem request to send the command on the connection that is defined for the SYSID.
    The system that receives the request must be a CICS region.

If the SYSID option is not specified on a file services, timer services, program execution, temporary storage, or transient data command, it defaults to the value that is in the RemoteSysId attribute of the resource's local definition.
If RemoteSysId="", or it is set to the local SYSID, the command runs locally.
If RemoteSysId is set to a remote SYSID, CICS uses an intersystem request to send the command on the connection that is defined for the SYSID.
Again, the receiving system must be CICS.

Any application that is using the SYSID option on file services, timer services, program execution, temporary storage, or transient data commands to request a remote SYSID, must have RSLCheck=none set in Transaction Definitions (TD) entry of the invoking transaction.
Otherwise, CICS raises the NOTAUTH condition.
This is because the SYSID option causes local security checking to be bypassed, so CICS allows its use only by transactions that do not require RSL checking.

See the TXSeries for Multiplatforms Intercommunication Guide for more information about DTP conversations and the use of intersystem requests to access resources on other CICS regions.

NOEDF

The NOEDF option enables you to prevent a command from being visible to Execution Diagnostic Facility (CEDF).
You can code this option on any command.

STATE

The STATE option is available on advanced program-to-program communications (APPC) commands such as ALLOCATE and CONNECT PROCESS.
APPC commands allow a CICS program to send data to, and receive data from, another program that is running in a remote system.
The programs are linked together by using a conversation.
Only one program can send data at a time, although each program can have a chance to send while the conversation is active.
The rules that control when each program can send data are expressed in terms of a conversation state.

The conversation state is a local attribute of the conversation.
It changes its value depending on the APPC commands that the local program issues, and as a result of data and other status information that is received from the remote program.

A local program can query the conversation state by using either the STATE option on an APPC command, or the EXTRACT ATTRIBUTES command.
The conversation state is returned as one of the following CVDA values:

  • ALLOCATED
  • CONFFREE
  • CONFRECEIVE
  • CONFSEND
  • FREE
  • PENDFREE
  • PENDRECEIVE
  • RECEIVE
  • ROLLBACK
  • SEND
  • SYNCFREE
  • SYNCRECEIVE
  • SYNCSEND

The TXSeries for Multiplatforms Intercommunication Guide defines the conversation states and when they occur in the conversation.
It also defines which APPC commands are permitted in each conversation state.

CICS-value data areas (CVDA) describes how to use CVDA values.

Programming that uses APPC conversations is called Distributed Transaction Processing (DTP).
See the TXSeries for Multiplatforms Intercommunication Guide for guidance on using APPC conversations.

FILE

The FILE option appears on all file service commands.
The value of filename is an eight-character name by which a file is known to CICS.

For more information about attention identifiers (AIDs), see HANDLE AID.

For information about the CICS Execution Diagnostic Facility (CEDF), see TXSeries for Multiplatforms Administration Reference.


© Copyright IBM Corp.