EXEC CICS WRITEQ TS QUeue( ) | QName ( )

From ( )

[ SYsid( ) ] [ Length( ) ]

[ NUmitems ( ) | Item( ) [ Rewrite ] ] [ Main | Auxiliary ]

[ NOsuspend ] END-EXEC

Example:

EXEC CICS WRITEQ TS QUEUE(UNIQNAME) FROM (WS-DATA) END-EXEC

Notes:

WRITEQ TS stores temporary data (records) in a temporary storage queue in main or auxiliary storage. If a queue has been defined as recoverable, the program must not issue a WRITEQ TS if a DELETEQ TS has previously been issued within the same logical unit of work. In other words, following a DELETEQ TS, no WRITEQ TS can be issued until after a syncpoint has occurred.

If there is insufficient space available in the temporary storage data set or main storage to satisfy the WRITEQ TS request, the task is suspended until space does become available. (Space may be released by other tasks in the system.) If, however, space is not available in the temporary storage data set or main storage, and the NOSUSPEND option has been specified, the NOSPACE condition is raised.

Options AUXILIARY

specifies that the temporary storage queue is on a direct access storage device in auxiliary storage. This is the default value for the first write. This option is ignored:

for an existing queue,

if a TSMODEL resource definition with a matching prefix is installed in the system.

if the AUXILIARY option is specified for a temporary storage data queue that resides in a temporary storage pool.

FROM(data-area)

specifies the data to be written to temporary storage.

ITEM(data-area)

specifies, as a halfword binary value, the item number of the logical record to be replaced in the queue (REWRITE option also specified). ITEM can be both an input and output field to CICS. As such, programmers should ensure that the ITEM field is not defined within protected storage when issuing a WRITEQ command. If the ITEM value were a literal (for example), command checking (CMDPROT=YES) would result in an AEYD abend occurring.

Note: In earlier releases, ITEM on a WRITEQ TS without REWRITE would perform a similar function to NUMITEMS. This function is retained for compatibility.

LENGTH(data-value)

specifies the length, as a halfword binary value, of the data to be written. You must specify this option if you are using SYSID.

The maximum length is 32763.

MAIN

specifies that the temporary storage queue is in main storage. This option is ignored: for an existing queue,

if a TSMODEL resource definition with a matching prefix is installed in the system.

if the MAIN option is specified for a temporary storage data sharing queue that resides in a temporary storage pool.

If you use the MAIN option to write data to a temporary storage queue on a remote system, the data is stored in main storage if the remote system is accessed by the CICS multiregion operation (MRO) facility. If these conditions are not met, the data is stored in auxiliary storage.

If the system is MRO and MAIN is specified, the queue is not recoverable and SYNCPOINT ROLLBACK does not function.

NOSUSPEND

specifies that the application program is not to be suspended if there is insufficient space in the temporary storage data set or in main storage to satisfy the WRITEQ TS request. Instead, the NOSPACE condition s raised.

Note, however, that if a HANDLE CONDITION for NOSPACE is active when the command is executed, this also overrides the default action, and control is passed to the user label supplied in the HANDLE CONDITION.

This takes precedence over the NOSUSPEND option but is, of course, negated by either NOHANDLE or RESP.

NUMITEMS(data-area)

specifies a halfword binary field into which CICS stores a number indicating how many items there are now in the queue, after the WRITEQ TS command is executed. If the record starts a new queue, the item number assigned is 1; subsequent item numbers follow on sequentially. NUMITEMS is not valid if REWRITE is specified.

QUEUE(name)

specifies the symbolic name (1-8 characters) of the queue to be written to. If the name has less than 8 characters, you must still use an 8-character field, padded with blanks if necessary. If the queue name appears in the TST, and the entry is marked as remote, the request is shipped to a remote system. The name must be unique within the CICS system. Do not use X'FA' through X'FF', or **, or $$, or DF, as the first character of the name; these characters are reserved for CICS use. The name cannot consist solely of binary zeros.

QNAME(name)

an alternative to QUEUE, QNAME specifies the symbolic name (1-16 characters) of the queue to be written to. If the name has less than 16 characters, you must still use a 16-character field, padded with blanks if necessary. If the queue name appears in the TST, and the entry is marked as remote, or if the QNAME is described by a TSMODEL resource definition which identifies a remote system, the request is shipped to a remote system. The name must be unique within the CICS system. Do not use X'FA' through X'FF', or **, or $$, or DF, as the first character of the name; these characters are reserved for CICS use. The name cannot consist solely of binary zeros.

REWRITE

specifies that the existing record in the queue is to be overwritten with the data provided. If the REWRITE option is specified, the ITEM option must also be specified. If the specified queue does not exist, the QIDERR condition occurs. If the correct item within an existing queue cannot be found, the ITEMERR condition occurs and the data is not stored.

SYSID(systemname)

(remote and shared queues only) specifies the system name (1-4 characters) identifying the remote system or shared queue pool to which the request is directed.

LINK

EXEC CICS LINK PROGRAM(name)

[ COmmarea ( ) [ Length ( ) ] [ Datalength ] ] [ SYsid( ) ]

[ SYNconreturn ] [ Transid( ) ]

[ INPUTMSG ( ) [ INPUTMSGLen( ) ] ] END-EXEC

LINK passes control from an application program at one logical level to an application program at the next lower logical level.

Example:

EXEC CICS LINK

PROGRAM(PROGNAME) COMMAREA(COMA) END-EXEC

Its shows how to request a link to an application program called PROGNAME

Notes:

LINK passes control from an application program at one logical level to an application program at the next lower logical level.

If the requested program is not defined to CICS, and AUTOINSTALL is active, CICS supplies a definition for the program. If this is a local definition, and the linked-to program is not already in main storage, CICS loads it.

When the RETURN command is executed in the linked-to program, control is returned to the program initiating the link at the next sequential executable instruction.

The linked-to program operates independently of the program that issues the LINK command with regard to handling conditions, attention identifiers, abends, and execution key. For example, the effects of HANDLE CONDITION commands in the linking program are not inherited by the linked-to program, but the original HANDLE CONDITION commands are restored on return to the linking program.

You can use the HANDLE ABEND command to deal with abnormal terminations in other link levels. Options

COMMAREA(data-area)

specifies a communication area that is to be made available to the invoked program. In this option the data area is passed, and you must give it the name DFHCOMMAREA in the receiving program.

DATALENGTH(data-value)

specifies a halfword binary value that is the length of a contiguous area of storage, from the start of the COMMAREA, to be passed to the invoked program. For a remote LINK request, if the amount of data being passed in a COMMAREA is small, but the COMMAREA itself is large so that the linked-to program can return the requested data, you should specify DATALENGTH in the interest of performance.

The value of DATALENGTH is only checked when the LINK request is remote or dynamic. It is not checked for static local links.

DATALENGTH cannot be used at the same time as INPUTMSG.

INPUTMSG(data-area)

specifies data to be supplied to the invoked program when it first issues a RECEIVE command. This data remains available until the execution of a RECEIVE or RETURN command. An invoked program can invoke a further program and so on, creating a chain of linked programs. If a linked-to chain exists, CICS supplies the INPUTMSG data to the first RECEIVE command executed in the chain. If control returns to the program that issued the LINK with INPUTMSG before the INPUTMSG data has been accepted by a RECEIVE command, CICS assumes that a RECEIVE command has been issued. This means that the original INPUTMSG data is no longer available. INPUTMSG cannot be used at the same time as DATALENGTH.

INPUTMSGLEN(data-value)

specifies a halfword binary value to be used with INPUTMSG.

LENGTH(data-value)

specifies a halfword binary value that is the length in bytes of the COMMAREA (communication area). This value may not exceed 32 500 bytes if the COMMAREA is to be passed between any two CICS servers (for any combination of product/version/release).

PROGRAM(name)

specifies the identifier (1-8 characters) of the program to which control is to be passed unconditionally.

Note the use of quotes:

EXEC CICS LINK PROGRAM('PROGX')

PROGX is in quotes because it is the program name.

EXEC CICS LINK PROGRAM(DAREA)

DAREA is not in quotes because it is the name of a data area that contains the actual program name. Note: When linking to a CICS 3270 program that is to be executed under the Link3270 bridge mechanism, the PROGRAM name must be DFHL3270, not the name of the target 3270 program.

SYNCONRETURN

specifies that the server region named on the SYSID option is to take a syncpoint on successful completion of the server program. Changes to recoverable resources made by the server program are committed or rolled-back independently of changes to recoverable resources made by the client program issuing the LINK request, or changes made by the server in any subsequent LINK.

The NORMAL condition is returned if changes to recoverable resources are committed before return from the server program.

The ROLLEDBACK condition is returned if changes to recoverable resources are rolled back before return from the server program.

The TERMERR condition is raised following failure of the communications link or the system in which the server program is executing. The client program is responsible for handling the condition and ensuring that data consistency is restored.

Synconreturn is only applicable to remote LINKs, it is ignored if the LINK is local.

SYSID(systemname)

specifies the system name of a CICS server region to where the program link request is to be routed. If SYSID specifies a remote system, reference is made to PROGRAM resource definitions held locally if the installed PROGRAM definition specifies remote attribute DYNAMIC(YES). If SYSID specifies the local system, CICS treats the LINK request as if SYSID was not specified.

A remote system name specified on the SYSID option takes priority over any remote system name specified on the PROGRAM resource definition or returned by the dynamic routing program.

TRANSID(name)

specifies the name of the mirror transaction that the remote region is to attach, and under which it is to run the server program. If you omit the TRANSID option, reference is made to PROGRAM resource definitions held locally if the installed PROGRAM definition specifies remote attribute DYNAMIC(YES). Otherwise, the server region attaches either CSMI, CPMI, or CVMI by default. The transaction name you specify on the LINK command takes priority over any transaction specified on the program resource definition. Whilst you can specify your own name for the mirror transaction initiated by DPL requests, the transaction must be defined in the server region, and the transaction definition must specify the mirror program, DFHMIRS.