zCICS

Application Programming Guide

v11

Automated Software Tools Corporation.

Copyright 2009 Automated Software Tools Corporation.

This is part of z390 distributed under open source GPL License.
zCICS Application Programming Guide

Table of Contents

Introduction
Assembly Notes
VSAM Notes
Basic Mapping Support
zCOBOL Support
Extra Parameters
Supported EXEC CICS commands (summary by type)
Supported EXEC CICS commands (detail by type)

Appendicies
Keypress information
Change Summary
References
Trademarks
Credits

General
HANDLE AID
HANDLE CONDITION
IGNORE CONDITION
POP HANDLE
PUSH HANDLE
ADDRESS
ASSIGN

Terminal Control
RECEIVE
SEND
SEND CONTROL

File Control
READ
STARTBR
READNEXT
READPREV
ENDBR
RESETBR

Storage Control
FREEMAIN
GETMAIN

Copyright 2009 Automated Software Tools Corporation.

This is part of z390 distributed under open source GPL License.
2
zCICS Application Programming Guide

Temporary Storage Control

DELETEQ
READQ
WRITEQ

Program Control
ABEND
HANDLE ABEND
LINK
LOAD
RELEASE
RETURN
XCTL

Interval Control
ASKTIME
DELAY
FORMATTIME
START
RETRIEVE
CANCEL

Task Control
ENQ
DEQ

BMS
RECEIVE MAP
SEND MAP

DUMP CONTROL
DUMP

System
INQUIRE FILE
SET FILE

Copyright 2009 Automated Software Tools Corporation.

This is part of z390 distributed under open source GPL License.
3
zCICS Application Programming Guide

Channels and Containers

GET
PUT
DELETE
MOVE
STARTBROWSE
GETNEXT
ENDBROWSE

Copyright 2009 Automated Software Tools Corporation.

This is part of z390 distributed under open source GPL License.
4
zCICS Application Programming Guide

Introduction

The EXEC CICS commands and parameters listed here are the only ones currently
supported in the zCICS environment.

Differences between mainframe operation and zCICS are explained.

For the operation of each command and parameter please refer to the Manuals
listed in the Reference section at the end of this document.

If you create your own zCICS applications, it would be wise to create a .BAT file that
re-assembles them all in one go. The internal interfaces are volatile at present and
this will be a frequent instruction.

The current zCICS environment and all test programs can be re-assembled using
[Link]. The test VSAM catalog and files can be rebuilt using [Link].

Assembly notes

CICS must be added as an option to CALL MZ390.

PROLOG and EPILOG are defaults.

NOEPILOG is supported but not fully tested, testing and correct usage is scheduled
for a future release of zCICS.

PROLOG inserts the following:

DFHEISTG -- Define the prefix areas of the Dynamic Storage Area (DSA).
DFHEIEND – Replaces the END statement and defines the end of the DSA.
DFHEIENT – Replaces the first CSECT statement
Establish linkage and base registers
GETMAIN the DSA
Establish addressability to the EIB and TCTTE
Some COMMAREA management

Other macros...
DFHEIBLK -- EIB DSECT
DFHPCT -- Transaction definition
DFHFCT – File definitions and options
EXEC -- Converts EXEC CICS statements into a unique macro call with a
parameter list
DFHREGS – A synonym for EQUREGS

Copyright 2009 Automated Software Tools Corporation.

This is part of z390 distributed under open source GPL License.
5
zCICS Application Programming Guide

Copy books...
DFHAID Standard CICS equates for AID keys
DFHBMSCA Mapping support equates
DFHPCTUS User transaction codes
DFHFCTUS User file definitions

Inclusion of the macro DFHREGS/EQUREGS is mandatory.

Register Usage...

R0 Reserved for internal use

R1 Reserved for internal use
R10 TCTTE address, must not be modified
R11 EIB address, must not be modified
R12 Default base register
R13 DSA address, must not be modified
R14 Reserved for internal use
R15 Reserved for internal use

Multiple base registers (assembler only)

The standard entry for a CICS program is as follows:

e.g. DFHEISTG DSECT

MYFIELD DS CL100 demo user field
...
MYPROG CSECT

This standard method with the PROLOG option (default) will generate a single code
base of R12 and a single DSA base of R13.

If you want to extend the code base and/or the DSA base registers, convert your
code in line with the sample given, and include the NOPROLOG option in CALL
MZ390.

e.g. DFHEISTG
MYFIELD DS CL100 demo user field
...
MYPROG DFHEIENT CODEREG=(R8,R5),DATAREG=(R13,R6,R7)

Notes:You cannot override the first DATAREG value, it will always be R13
i.e. if you code DATAREG=(R6,R7) you will get DATAREG=(R13,R7).

There is no cross-checking for register conflicts.

Copyright 2009 Automated Software Tools Corporation.

This is part of z390 distributed under open source GPL License.
6
zCICS Application Programming Guide

EXEC CICS command syntax (Assembler only)

There is no formal definition of an EXEC CICS command in any IBM Manual.

These assembler syntaxes are currently supported...

a) In-line space separated

name EXEC CICS function subfunction parm parm()

b) In-line comma separated

name EXEC CICS function,subfunction,parm,parm(), parm ()

c) Split, space separated

Non-blank in column 72 is assumed for all lines except the last.
Comments are only allowed following a dot or comma delimiter on the last line.
name EXEC CICS function
subfunction
parm
parm() parm (). a nice comment

d) Split, comma separated

Non-blank in column 72 is assumed for all lines except the last.
Comments are allowed on all lines that end with comma+space.
name EXEC CICS function, some
subfunction, very
parm, nice
parm(),parm (), comments

name is supported and optional.

EXEC CICS is expected, EXECUTE CICS is not currently supported.
subfunction is optional and depends on the function but must follow function,
e.g. EXEC CICS WRITEQ TS

parm() without spacing and parm () with spacing are allowed.

VSAM Notes

See the zCICS VSAM Guide for guidance in the setup of a VSAM environment.
This document also contains extensions to the VSAM facilities currently available.

Copyright 2009 Automated Software Tools Corporation.

This is part of z390 distributed under open source GPL License.
7
zCICS Application Programming Guide

Basic Mapping Support

The commands RECEIVE MAP, SEND MAP and SEND CONTROL are documented
here.
For general BMS documentation and the mapping macros DFHMSD, DFHMDI and
DFHMDF see the zCICS BMS Guide.

zCOBOL support

EXEC CICS command format follows the rules for COBOL.

Each command must end END-EXEC (a following dot may affect the logic).

Parameters like SET() which address imported structures may use the ADDRESS
OF special register.

LENGTH, FLENGTH and KEYLENGTH which would normally allow a numeric option
may use the LENGTH OF special register.

Extra Parameters

You can add NOEDF to any EXEC CICS command if you wish that command to be
excluded from a CEDF session.

You can add NOEDF to the CALL MZ390 if you wish all CEDF intercepts in that
program excluded.

Copyright 2009 Automated Software Tools Corporation.

This is part of z390 distributed under open source GPL License.
8
zCICS Application Programming Guide

Supported EXEC CICS commands (summary by type)

1) General commands (02)

a) HANDLE AID key() key
b) HANDLE CONDITION condition() condition
c) IGNORE CONDITION condition
d) POP HANDLE
e) PUSH HANDLE
f) ADDRESS
g) ASSIGN

2) Terminal Control (04)

a) RECEIVE INTO() LENGTH() NOHANDLE
b) SEND FROM() LENGTH()

3) File Control (06)

a) READ FILE()/DATASET() INTO()/SET() LENGTH()/FLENGTH()
RIDFLD() RBA/XRBA/RRN/GENERIC GTEQ/EQUAL KEYLENGTH()
b) STARTBR FILE()/DATASET() RIDFLD() REQID()
RBA/XRBA/RRN/GENERIC GTEQ/EQUAL KEYLENGTH()
c) READNEXT FILE()/DATASET() INTO()/SET() LENGTH()/FLENGTH()
RIDFLD() REQID() RBA/XRBA/RRN KEYLENGTH()
d) READPREV FILE()/DATASET() INTO()/SET() LENGTH()/FLENGTH()
RIDFLD() REQID() RBA/XRBA/RRN KEYLENGTH()
e) ENDBR FILE()/DATASET() REQID()
f) RESETBR FILE()/DATASET() RIDFLD() REQID()
RBA/XRBA/RRN/GENERIC GTEQ/EQUAL KEYLENGTH()

4) Storage Control (08)

a) FREEMAIN DATA()/DATAPOINTER()
b) GETMAIN SET() LENGTH()/FLENGTH() INITIMG()

5) Temporary Storage Control (0A)

a) DELETEQ TS QUEUE()/QNAME()
b) READQ TS QUEUE()/QNAME() INTO()/SET() LENGTH()/FLENGTH()
NUMITEMS() ITEM()/NEXT
c) WRITEQ TS QUEUE()/QNAME() FROM() LENGTH()/FLENGTH()
NUMITEMS() ITEM() REWRITE

Copyright 2009 Automated Software Tools Corporation.

This is part of z390 distributed under open source GPL License.
9
zCICS Application Programming Guide

6) Program Control (0E)

a) ABEND ABCODE() CANCEL NODUMP
b) HANDLE ABEND CANCEL/RESET/LABEL()/PROGRAM()
c) LINK PROGRAM() COMMAREA() LENGTH() CHANNEL()
d) LOAD PROGRAM() ENTRY()/SET() LENGTH() FLENGTH()
e) RELEASE PROGRAM()
f) RETURN TRANSID() COMMAREA() LENGTH() CHANNEL() IMMEDIATE
g) XCTL PROGRAM() COMMAREA() LENGTH() CHANNEL()

7) Interval Control (10 and 4A)

a) ASKTIME ABSTIME()
b) DELAY REQID()/INTERVAL()/TIME() FOR/UNTIL HOURS() MINUTES()
SECONDS()
c) FORMATTIME all parameters
d) START TRANSID() INTERVAL()/TIME() TERMID() CHANNEL()
REQID() FROM() LENGTH() QUEUE() RTRANSID() RTERMID()
AFTER/AT HOURS() MINUTES() SECONDS()
e) RETRIEVE INTO()/SET() LENGTH() RTRANSID() RTERMID() QUEUE()
f) CANCEL REQID()

8) Task Control (12)

a) ENQ RESOURCE() LENGTH() NOSUSPEND
b) DEQ RESOURCE() LENGTH()

9) BMS (18)
a) RECEIVE MAP(name) MAPSET(name) INTO()
b) SEND MAP(name) MAPSET(name)
CURSOR/CURSOR() DATAONLY/MAPONLY ERASE/ERASEAUP
FROM() LENGTH() ALARM FREEKB FRSET
SET()
c) SEND CONTROL CURSOR/CURSOR() ERASE/ERASEAUP
ALARM FREEKB FRSET

10) Dump Control (1C)

a) DUMP TRANSACTION DUMPCODE() COMPLETE
FROM() LENGTH()/FLENGTH()
SEGMENTLIST() LENGTHLIST() NUMSEGMENTS()

11) Inquire (4C)

a) INQUIRE FILE
b) SET FILE

Copyright 2009 Automated Software Tools Corporation.

This is part of z390 distributed under open source GPL License.
10
zCICS Application Programming Guide

12) Channels and Containers (34 and 96)

a) GET CONTAINER() CHANNEL() INTO()/SET()/NODATA FLENGTH()
b) PUT CONTAINER() CHANNEL() FROM() FLENGTH()
c) DELETE CONTAINER() CHANNEL()
d) MOVE CONTAINER() AS() CHANNEL() TOCHANNEL()
e) STARTBROWSE CONTAINER CHANNEL() BROWSETOKEN()
f) GETNEXT CONTAINER() BROWSETOKEN()
g) ENDBROWSE CONTAINER BROWSETOKEN()

Copyright 2009 Automated Software Tools Corporation.

This is part of z390 distributed under open source GPL License.
11
zCICS Application Programming Guide

Supported EXEC CICS commands (detail by type)

1) General commands (02)

a) HANDLE AID

Name Operation Operands

name EXEC CICS HANDLE AID
key(label) key etc.

The following parameters are not supported...

CLRPARTN, LIGHTPEN, OPERID, TRIGGER

The manual is not clear about ANYKEY (no label). I have assumed that it
clears all settings for CLEAR, PA and PF keys.

label may take three forms:

Direct reference
Indirect reference
Adcon literal

e.g. EXEC CICS HANDLE AID PA1(GOPA1) PA2(INDGOPA1) PA3(=A(GOPA1))

...
GOPA1 DS 0H
...
INDGOPA1 DC A(GOPA1)

Notes:
There is a current limit of 30 AIDs, please request more if needed.

Errors
AN INTERNAL ERROR HAS OCCURRED
NO PARAMETERS SPECIFIED
NUMBER OF AIDS EXCEEDS 30
BAD PARM
HANDLE TYPE NOT RECOGNISED

Copyright 2009 Automated Software Tools Corporation.

This is part of z390 distributed under open source GPL License.
12
zCICS Application Programming Guide

b) HANDLE CONDITION

Name Operation Operands

name EXEC CICS HANDLE CONDITION
condition(label) condition etc.

label may take three forms:

Direct reference
Indirect reference
Adcon literal

See HANDLE AID for examples of these forms.

Notes:
There is a current limit of 30 conditions, please request more if needed.

DSIDERR is supported as a synonym to FILENOTFOUND.

Errors
AN INTERNAL ERROR HAS OCCURRED
NUMBER OF CONDITIONS EXCEEDS 30
BAD PARM
HANDLE TYPE NOT RECOGNISED

c) IGNORE CONDITION

Name Operation Operands

name EXEC CICS IGNORE CONDITION
condition...

Notes:
Ignoring an error may lead to unpredictable abends.
There is a current limit of 30 conditions, please request more if needed.

INVREQ, PGMIDERR or ERROR by default...

The EXEC CICS command treated as never existed.

INVREQ on EXEC CICS RETURN will abend the task ASRA as I cannot
ignore a RETURN.

LENGERR or ERROR by default...

NOHANDLE and any outstanding HANDLE AID will not invoke this
condition.

DSIDERR is supported as a synonym to FILENOTFOUND.

Copyright 2009 Automated Software Tools Corporation.

This is part of z390 distributed under open source GPL License.
13
zCICS Application Programming Guide

Errors
BAD PARM
IGNORE TYPE NOT RECOGNISED
AN INTERNAL ERROR HAS OCCURRED
NO PARAMETERS SPECIFIED
NUMBER OF CONDITIONS EXCEEDS 30

d) POP HANDLE

Name Operation Operands

name EXEC CICS POP HANDLE

For the HANDLE ABEND, a POP is the equivalent of a HANDLE ABEND

RESET.

Errors
BAD PARM
POP TYPE NOT RECOGNISED

Conditions (RESP/RESP2)
INVREQ/0

e) PUSH HANDLE

Name Operation Operands

name EXEC CICS PUSH HANDLE

For the HANDLE ABEND, a PUSH is the equivalent of a HANDLE ABEND

CANCEL.

Errors
BAD PARM
PUSH TYPE NOT RECOGNISED

f) ADDRESS

Name Operation Operands

name EXEC CICS ADDRESS
COMMAREA(label)
CWA(label)
EIB(label)

CWA has a different implementation in zCICS.

See "CWA Management" in "zCICS Diagnosis Reference"

Errors
BAD PARM

Copyright 2009 Automated Software Tools Corporation.

This is part of z390 distributed under open source GPL License.
14
zCICS Application Programming Guide

g) ASSIGN

Name Operation Operands

name EXEC CICS ASSIGN

The following parameters are not supported:

ACTIVITY,ACTIVITYID,ALTSCRNHT,ALTSCRNWD,APPLID,
ASRAINTRPT,ASRAKEY,ASRASPC,ASRASTG,BRIDGE,
DELIMITER,DESTCOUNT,DESTID,DESTIDLENG,GCHARS,GCODES,I
NITPARM,INITPARMLEN,INPARTN,
LDCMNEM,LDCNUM,NETNAME,NUMTAB,OPCLASS,OPERKEYS,
OPID,OPSECURITY,ORGABCODE,PAGENUM,
PARTNPAGE,PARTNPAGE,PRINSYSID,PROCESS,
PROCESSTYPE,QNAME,SIGDATA,STATIONID,SYSID,
TELLERID,USERID,USERNAME

Note: zCICS allows a CWA size greater than 32K. If the CWA
does exceed 32K, then ASSIGN CWALENG() will return an
incorrect value.

Conditions (RESP/RESP2)
INVREQ/2
INVREQ/5

Errors
BAD PARM

2) Terminal Control (04)

a) RECEIVE

Name Operation Operands

name EXEC CICS RECEIVE
INTO(label)
LENGTH(label)
NOHANDLE

INTO(label) and LENGTH(label) are mandatory.

LENGTH must point to a 2-byte field.

Although MAXLENGTH is not implemented yet, there is an internal

maximum length set to the implied length of the INTO label.

NOHANDLE is optional.

Copyright 2009 Automated Software Tools Corporation.

This is part of z390 distributed under open source GPL License.
15
zCICS Application Programming Guide

Errors
BAD PARM
BOTH INTO AND LENGTH ARE REQUIRED
LENGTH ERROR

Conditions (RESP/RESP2)
NOTALLOC/0
LENGERR/0

b) SEND

Name Operation Operands

name EXEC CICS SEND
FROM(label)
LENGTH()

FROM(label) is mandatory.
label may take three forms:
Direct reference
Indirect reference
Adcon literal

LENGTH
Can be specified as LENGTH(value) or LENGTH(label)
LENGTH(value) supports the use of the length attribute.
label must point to a 2-byte hex value.

The parameters TERMINAL, WAIT, DEFAULT and TEXT are discarded.

Errors
BAD PARM
FROM IS MANDATORY
LENGTH IS MANDATORY

Conditions (RESP/RESP2)

INVREQ/0
Note: Attempt to execute this in a non-terminal attached task.
This is not documented in the Manual.

LENGERR/E1

c) SEND CONTROL

Name Operation Operands

name EXEC CICS SEND CONTROL
CURSOR/CURSOR()
Copyright 2009 Automated Software Tools Corporation.
This is part of z390 distributed under open source GPL License.
16
zCICS Application Programming Guide
ERASE/ERASEAUP
ALARM
FREEKB
FRSET

TERMINAL and WAIT are accepted and discarded.

ACCUM and SET are not supported.

CURSOR() refers to the 24x80 screen.

CURSOR is not documented.
SEND CONTROL CURSOR ERASEAUP means erase all input fields
and don't move the cursor.

Errors
BAD PARM
CURSOR POSITION AND SYMBOLIC CURSOR SPECIFIED
ERASE AND ERASEAUP SPECIFIED

Conditions (RESP/RESP2)

INVREQ/0
Note: Attempt to execute this in a non-terminal attached task.
This is not documented in the Manual.

3) File Control (06)

Notes:
FLENGTH and XRBA are extensions; do not use these parameters if the
source code is likely to be ported back to a mainframe environment.

RBA access to a KSDS is not supported.

DATASET is supported for legacy applications. It is noted that this parameter

no longer appears in the Manuals.

When conditions are raised as a result of a VSAM error, the RPL feedback codes
(2nd and 4th bytes) are placed in EIBRCODE +1 and +2.

a) READ

Name Operation Operands

name EXEC CICS READ
FILE()/DATASET()
INTO()/SET()
LENGTH()/FLENGTH()
RIDFLD()
RBA/XRBA/RRN/GENERIC

Copyright 2009 Automated Software Tools Corporation.

This is part of z390 distributed under open source GPL License.
17
zCICS Application Programming Guide
GTEQ/EQUAL
KEYLENGTH()

LENGTH
Can be specified as a constant, literal or label.
A constant must not exceed 32767.
A literal or label must be 2 bytes and must not exceed 32767.

FLENGTH
Can be specified as a constant, literal or label.
A constant must not exceed 2G-1.
A literal or label must be 4 bytes and must not exceed 2G-1.

LENGTH/FLENGTH notes:
If SET is specified, LENGTH/FLENGTH are ignored and LENGERR
cannot occur.

If INTO is specified and LENGTH/FLENGTH are not, then the implied

length of INTO is used. This may raise the LENGERR condition if the
data length is larger.

If LENGTH/FLENGTH is numeric then it specifies the maximum data

length that can be received. LENGERR can be raised if the data length
is larger.

If LENGTH/FLENGTH is a label then it specifies the maximum data

length that can be received. LENGERR can be raised if the data length
is larger. The true data length is returned in label.

KEYLENGTH
Can be specified as a constant or label.
A constant must not exceed 32767.
A label must be 2 bytes and must not exceed 32767.
Keylengths greater than 128 are ignored.

The parameter is ignored for ESDS and RRDS.

KEYLENGTH and GENERIC must be paired.

If KEYLENGTH is zero by constant or label then parameters are

changed internally:
GENERIC/EQUAL or GENERIC/GTEQ
Becomes KEYLENGTH(1) Key=X'00' GENERIC GTEQ

RBA RIDFLD has a 4-byte RBA

XRBA RIDFLD has an 8-byte RBA
RRN RIDFLD has a 4-byte relative record number

Copyright 2009 Automated Software Tools Corporation.

This is part of z390 distributed under open source GPL License.
18
zCICS Application Programming Guide

GTEQ/EQUAL
The parameter is ignored for ESDS and RRDS.

GENERIC
KEYLENGTH must be specified.
The parameter is ignored for ESDS and RRDS.

Errors
BAD PARM
BOTH FILE AND DATASET ARE SPECIFIED
BOTH GTEQ AND EQUAL ARE SPECIFIED
BOTH INTO AND SET ARE SPECIFIED
BOTH LENGTH AND FLENGTH ARE SPECIFIED
BOTH RBA AND XRBA ARE SPECIFIED
BOTH RRN AND (X)RBA ARE SPECIFIED
FILE OR DATASET MUST BE SPECIFIED
GENERIC CANNOT BE SPECIFIED WITH RRN OR (X)RBA
GENERIC REQUIRES KEYLENGTH
INTO OR SET MUST BE SPECIFIED
INVALID FILE OR DATASET
KEYLENGTH REQUIRES GENERIC
RIDFLD IS MANDATORY

Conditions (RESP/RESP2)
FILENOTFOUND/1
DISABLED/50
ILLOGIC/110
INVREQ/20
INVREQ/25
INVREQ/42
LENGERR/E1
NOTFND/80
NOTOPEN/60

b) STARTBR

Name Operation Operands

name EXEC CICS STARTBR
FILE()/DATASET()
RIDFLD()
REQID()
RBA/XRBA/RRN/GENERIC
GTEQ/EQUAL
KEYLENGTH()

REQID
Copyright 2009 Automated Software Tools Corporation.
This is part of z390 distributed under open source GPL License.
19
zCICS Application Programming Guide

Can be specified as a constant, literal or label.

A constant must not exceed 32767.
A literal or label must be 2 bytes and must not exceed 32767.
If omitted, zero is assumed.

RBA RIDFLD has a 4-byte RBA

XRBA RIDFLD has an 8-byte RBA
RRN RIDFLD has a 4-byte relative record number

KEYLENGTH
Can be specified as a constant or label.
A constant must not exceed 32767.
A label must be 2 bytes and must not exceed 32767.
Keylengths greater than 128 are ignored.

The parameter is ignored for ESDS and RRDS.

KEYLENGTH and GENERIC must be paired.

If KEYLENGTH is zero by constant or label then parameters are

changed internally:
GENERIC/EQUAL or GENERIC/GTEQ
Becomes KEYLENGTH(1) Key=X'00' GENERIC GTEQ

GTEQ/EQUAL
The parameter is ignored for ESDS and RRDS.

GENERIC
KEYLENGTH must be specified.
The parameter is ignored for ESDS and RRDS.

Errors
BAD PARM
BOTH FILE AND DATASET ARE SPECIFIED
BOTH GTEQ AND EQUAL ARE SPECIFIED
BOTH RBA AND XRBA ARE SPECIFIED
BOTH RRN AND (X)RBA ARE SPECIFIED
FILE OR DATASET MUST BE SPECIFIED
GENERIC CANNOT BE SPECIFIED WITH RRN OR (X)RBA
GENERIC REQUIRES KEYLENGTH
INVALID FILE OR DATASET
KEYLENGTH REQUIRES GENERIC
RIDFLD IS MANDATORY

Conditions (RESP/RESP2)
DISABLED/50
FILENOTFOUND/1

Copyright 2009 Automated Software Tools Corporation.

This is part of z390 distributed under open source GPL License.
20
zCICS Application Programming Guide

ILLOGIC/110
INVREQ/20
INVREQ/25
INVREQ/33
INVREQ/42
NOTFND/80
NOTOPEN/60

Note: NOTFND cannot occur for an ESDS or RRDS

c) READNEXT

Name Operation Operands

name EXEC CICS READNEXT
FILE()/DATASET()
INTO()/SET()
LENGTH()/FLENGTH()
RIDFLD()
REQID()
RBA/XRBA/RRN
KEYLENGTH()

LENGTH
Can be specified as a constant, literal or label.
A constant must not exceed 32767.
A literal or label must be 2 bytes and must not exceed 32767.

FLENGTH
Can be specified as a constant, literal or label.
A constant must not exceed 2G-1.
A literal or label must be 4 bytes and must not exceed 2G-1.

LENGTH/FLENGTH notes:
If either is not a label then...
If INTO is specified, then the length received is the implied length of
INTO. This may raise the LENGERR condition if the data length is
larger.

If SET is specified, the complete record is returned and LENGERR

cannot occur.

If either is a label then...

If INTO or SET is specified, then it specifies the maximum data
length that can be received. LENGERR can be raised if the data
length is larger. The true data length is returned in label.

Copyright 2009 Automated Software Tools Corporation.

This is part of z390 distributed under open source GPL License.
21
zCICS Application Programming Guide

REQID
Can be specified as a constant, literal or label.
A constant must not exceed 32767.
A literal or label must be 2 bytes and must not exceed 32767.
If omitted, zero is assumed.

RBA RIDFLD has a 4-byte RBA

XRBA RIDFLD has an 8-byte RBA
RRN RIDFLD has a 4-byte relative record number

KEYLENGTH
Can be specified as a constant or label.
A constant must not exceed 32767.
A label must be 2 bytes and must not exceed 32767.
Keylengths greater than 128 are ignored.

The parameter is ignored for ESDS and RRDS.

If KEYLENGTH is zero by constant or label then parameters are

changed internally:
GENERIC/EQUAL or GENERIC/GTEQ
Becomes KEYLENGTH(1) Key=X'00' GENERIC GTEQ

Errors
BAD PARM
BOTH FILE AND DATASET ARE SPECIFIED
BOTH INTO AND SET ARE SPECIFIED
BOTH LENGTH AND FLENGTH ARE SPECIFIED
BOTH RBA AND XRBA ARE SPECIFIED
BOTH RRN AND (X)RBA ARE SPECIFIED
FILE OR DATASET MUST BE SPECIFIED
INTO OR SET MUST BE SPECIFIED
INVALID FILE OR DATASET
RIDFLD IS MANDATORY
THIS TYPE OF INTO REQUIRES LENGTH/FLENGTH

Conditions (RESP/RESP2)
DISABLED/50
ENDFILE/90
FILENOTFOUND/1
ILLOGIC/110
INVREQ/20
INVREQ/25
INVREQ/26
INVREQ/34

Copyright 2009 Automated Software Tools Corporation.

This is part of z390 distributed under open source GPL License.
22
zCICS Application Programming Guide

INVREQ/42
LENGERR/E1
NOTFND/80
NOTOPEN/60

d) READPREV

Name Operation Operands

name EXEC CICS READPREV
FILE()/DATASET()
INTO()/SET()
LENGTH()/FLENGTH()
RIDFLD()
REQID()
RBA/XRBA/RRN
KEYLENGTH()

LENGTH
Can be specified as a constant, literal or label.
A constant must not exceed 32767.
A literal or label must be 2 bytes and must not exceed 32767.

FLENGTH
Can be specified as a constant, literal or label.
A constant must not exceed 2G-1.
A literal or label must be 4 bytes and must not exceed 2G-1.

LENGTH/FLENGTH notes:
If either is not a label then...
If INTO is specified, then the length received is the implied length of
INTO. This may raise the LENGERR condition if the data length is
larger.

If SET is specified, the complete record is returned and LENGERR

cannot occur.

If either is a label then...

If INTO or SET is specified, then it specifies the maximum data
length that can be received. LENGERR can be raised if the data
length is larger. The true data length is returned in label.

REQID
Can be specified as a constant, literal or label.
A constant must not exceed 32767.
A literal or label must be 2 bytes and must not exceed 32767.
If omitted, zero is assumed.

Copyright 2009 Automated Software Tools Corporation.

This is part of z390 distributed under open source GPL License.
23
zCICS Application Programming Guide

RBA RIDFLD has a 4-byte RBA

XRBA RIDFLD has an 8-byte RBA
RRN RIDFLD has a 4-byte relative record number

KEYLENGTH
Can be specified as a constant or label.
A constant must not exceed 32767.
A label must be 2 bytes and must not exceed 32767.
Keylengths greater than 128 are ignored.

The parameter is ignored for ESDS and RRDS.

If KEYLENGTH is specified, the value must be equal to the keylength
defined for the file.

Errors
BAD PARM
BOTH FILE AND DATASET ARE SPECIFIED
BOTH INTO AND SET ARE SPECIFIED
BOTH LENGTH AND FLENGTH ARE SPECIFIED
BOTH RBA AND XRBA ARE SPECIFIED
BOTH RRN AND (X)RBA ARE SPECIFIED
FILE OR DATASET MUST BE SPECIFIED
INTO OR SET MUST BE SPECIFIED
INVALID FILE OR DATASET
RIDFLD IS MANDATORY
THIS TYPE OF INTO REQUIRES LENGTH/FLENGTH

Conditions (RESP/RESP2)
DISABLED/50
ENDFILE/90
FILENOTFOUND/1
ILLOGIC/110
INVREQ/20
INVREQ/24
INVREQ/26
INVREQ/41
LENGERR/E1
NOTFND/80
NOTOPEN/60

Note: ENDFILE can occur when a READPREV attempts to read past

the beginning of the file.

Copyright 2009 Automated Software Tools Corporation.

This is part of z390 distributed under open source GPL License.
24
zCICS Application Programming Guide

e) ENDBR

Name Operation Operands

name EXEC CICS ENDBR
FILE()/DATASET()
REQID()

REQID
Can be specified as a constant, literal or label.
A constant must not exceed 32767.
A literal or label must be 2 bytes and must not exceed 32767.
If omitted, zero is assumed.

Note: In real CICS, ENDBR cannot cause a file to open, but it will in zCICS.
The ENDBR command will be invalid, and may result in a transaction
abend.

Errors
BAD PARM
BOTH FILE AND DATASET ARE SPECIFIED
FILE OR DATASET MUST BE SPECIFIED
INVALID FILE OR DATASET

Conditions (RESP/RESP2)
DISABLED/50
FILENOTFOUND/1
ILLOGIC/110
INVREQ/20
INVREQ/35
NOTOPEN/60

f) RESETBR

Name Operation Operands

name EXEC CICS RESETBR
FILE()/DATASET()
RIDFLD()
REQID()
RBA/XRBA/RRN/GENERIC
GTEQ/EQUAL
KEYLENGTH()

REQID
Can be specified as a constant, literal or label.
A constant must not exceed 32767.
A literal or label must be 2 bytes and must not exceed 32767.
If omitted, zero is assumed.

Copyright 2009 Automated Software Tools Corporation.

This is part of z390 distributed under open source GPL License.
25
zCICS Application Programming Guide

RBA RIDFLD has a 4-byte RBA

XRBA RIDFLD has an 8-byte RBA
RRN RIDFLD has a 4-byte relative record number

KEYLENGTH
Can be specified as a constant or label.
A constant must not exceed 32767.
A label must be 2 bytes and must not exceed 32767.
Keylengths greater than 128 are ignored.

The parameter is ignored for ESDS and RRDS.

KEYLENGTH and GENERIC must be paired.

If KEYLENGTH is zero by constant or label then parameters are

changed internally:
GENERIC/EQUAL or GENERIC/GTEQ
Becomes KEYLENGTH(1) Key=X'00' GENERIC GTEQ

GTEQ/EQUAL
The parameter is ignored for ESDS and RRDS.

GENERIC
KEYLENGTH must be specified.
The parameter is ignored for ESDS and RRDS.

Note: In real CICS, RESETBR cannot cause a file to open, but it will in
zCICS. The RESETBR command will be invalid, and may result in a
transaction abend.

Errors
BAD PARM
BOTH FILE AND DATASET ARE SPECIFIED
BOTH GTEQ AND EQUAL ARE SPECIFIED
BOTH RBA AND XRBA ARE SPECIFIED
BOTH RRN AND (X)RBA ARE SPECIFIED
FILE OR DATASET MUST BE SPECIFIED
GENERIC CANNOT BE SPECIFIED WITH RRN OR (X)RBA
GENERIC REQUIRES KEYLENGTH
INVALID FILE OR DATASET
KEYLENGTH REQUIRES GENERIC
RIDFLD IS MANDATORY

Conditions (RESP/RESP2)
DISABLED/50
FILENOTFOUND/1

Copyright 2009 Automated Software Tools Corporation.

This is part of z390 distributed under open source GPL License.
26
zCICS Application Programming Guide

ILLOGIC/110
INVREQ/20
INVREQ/25
INVREQ/36
INVREQ/42
NOTFND/80
NOTOPEN/60

Note: NOTFND cannot occur for an ESDS or RRDS

4) Storage Control (08)

a) FREEMAIN

Name Operation Operands

name EXEC CICS FREEMAIN
DATA()/DATAPOINTER()

DATA(label)
label may only be an indirect reference to the address.

DATAPOINTER
Must be specified as a permitted general register value.

Errors
BAD PARM
BOTH DATA AND DATAPOINTER ARE SPECIFIED
DATA OR DATAPOINTER MUST BE SPECIFIED

Conditions (RESP/RESP2)
INVREQ/1

b) GETMAIN

Name Operation Operands

name EXEC CICS GETMAIN
SET()
LENGTH()/FLENGTH()
INITIMG()

SET is mandatory
Must be specified as a permitted general register value.

LENGTH
Can be specified as a constant, literal or label.
A constant must not exceed 32767.
A literal or label must be 2 bytes and must not exceed 32767.
Copyright 2009 Automated Software Tools Corporation.
This is part of z390 distributed under open source GPL License.
27
zCICS Application Programming Guide

FLENGTH
Can be specified as a constant, literal or label.
A constant must not exceed 2G-1.
A literal or label must be 4 bytes and must not exceed 2G-1.

INITIMG is optional
If omitted, the storage contents are not predictable.
Can be specified as a constant, literal or label.
zCOBOL supports all 3 data types, but for mainframe COBOL programs
only label is supported.
Only the first byte generated by the parameter is used.

Errors
BAD PARM
BOTH LENGTH AND FLENGTH ARE SPECIFIED
LENGTH OR FLENGTH MUST BE SPECIFIED
SET IS MANDATORY

5) Temporary Storage Control (0A)

Note:
FLENGTH is an extension; do not use this parameter if the source code is
likely to be ported back to a mainframe environment.

a) DELETEQ

Name Operation Operands

name EXEC CICS DELETEQ TS
QUEUE()/QNAME()

The parameters MAIN and AUXILIARY are accepted and discarded.

QUEUE may be specified as:

A quoted string which must not exceed 8 bytes.
A label which points to an 8-byte field.
A literal not exceeding 8 bytes.
Only label or literal may be used to specify a QUEUE with hex
characters.

QNAME may be specified as:

A quoted string which must not exceed 16 bytes.
A label which points to a 16-byte field.
A literal not exceeding 16 bytes.
Only label or literal may be used to specify a QNAME with hex
characters.

Copyright 2009 Automated Software Tools Corporation.

This is part of z390 distributed under open source GPL License.
28
zCICS Application Programming Guide

Errors
BAD PARM
BOTH QUEUE AND QNAME ARE SPECIFIED
DELETEQ TYPE NOT RECOGNIZED
INVALID QUEUE OR QNAME
QUEUE OR QNAME MUST BE SPECIFIED

Conditions (RESP/RESP2)
INVREQ/0
QIDERR/0

b) READQ

Name Operation Operands

name EXEC CICS READQ TS
QUEUE()/QNAME()
INTO()/SET()
LENGTH()/FLENGTH()
NUMITEMS()
ITEM()/NEXT

The parameters MAIN and AUXILIARY are accepted and discarded.

QUEUE may be specified as:

A quoted string which must not exceed 8 bytes.
A label which points to an 8-byte field.
A literal not exceeding 8 bytes.
Only label or literal may be used to specify a QUEUE with hex
characters.

QNAME may be specified as:

A quoted string which must not exceed 16 bytes.
A label which points to a 16-byte field.
A literal not exceeding 16 bytes.
Only label or literal may be used to specify a QNAME with hex
characters.

LENGTH
May be specified as LENGTH(value) or LENGTH(label)
LENGTH(value) supports the use of the length attribute.
label must point to a 2-byte hex value.

FLENGTH
Can be specified as a constant, literal or label.
A constant must not exceed 2G-1.
A literal or label must be 4 bytes and must not exceed 2G-1.
Copyright 2009 Automated Software Tools Corporation.
This is part of z390 distributed under open source GPL License.
29
zCICS Application Programming Guide

LENGTH/FLENGTH can be omitted. When they are, the implied length

of INTO is used. LENGTH/FLENGTH is mandatory when SET is used.

ITEM
May be specified as ITEM(value) or ITEM(label)
label must point to a 2-byte hex value.

Errors
BAD PARM
BOTH INTO AND SET ARE SPECIFIED
BOTH ITEM AND NEXT ARE SPECIFIED
BOTH LENGTH AND FLENGTH ARE SPECIFIED
BOTH QUEUE AND QNAME ARE SPECIFIED
INTO OR SET MUST BE SPECIFIED
INVALID QUEUE OR QNAME
ITEM OR NEXT MUST BE SPECIFIED
QUEUE OR QNAME MUST BE SPECIFIED
READQ TYPE NOT RECOGNIZED
SET REQUIRES LENGTH

Conditions (RESP/RESP2)
INVREQ/0
LENGERR/0
ITEMERR/0
QIDERR/0

c) WRITEQ

Name Operation Operands

name EXEC CICS WRITEQ TS
QUEUE()/QNAME()
FROM()
LENGTH()/FLENGTH()
NUMITEMS()
ITEM()
REWRITE

The parameters MAIN and AUXILIARY are accepted and discarded.

QUEUE may be specified as:

A quoted string which must not exceed 8 bytes.
A label which points to an 8-byte field.
A literal not exceeding 8 bytes.
Only label or literal may be used to specify a QUEUE with hex
characters.

Copyright 2009 Automated Software Tools Corporation.

This is part of z390 distributed under open source GPL License.
30
zCICS Application Programming Guide

QNAME may be specified as:

A quoted string which must not exceed 16 bytes.
A label which points to a 16-byte field.
A literal not exceeding 16 bytes.
Only label or literal may be used to specify a QNAME with hex
characters.

FROM(label) is mandatory.
label may take three forms:
Direct reference
Indirect reference
Adcon literal

LENGTH
May be specified as LENGTH(value) or LENGTH(label)
LENGTH(value) supports the use of the length attribute.
label must point to a 2-byte hex value.

FLENGTH
Can be specified as a constant, literal or label.
A constant must not exceed 2G-1.
A literal or label must be 4 bytes and must not exceed 2G-1.

LENGTH/FLENGTH can be omitted. When they are, the implied length

of FROM is used.
LENGTH/FLENGTH is mandatory when FROM is an indirect reference.

ITEM
May be specified as ITEM(value) or ITEM(label)
label must point to a 2-byte hex value.

Note: For compatibility with old releases of CICS, ITEM is accepted

without REWRITE and becomes NUMITEMS. ITEM must be a
label in this case.

Errors
BAD PARM
BOTH LENGTH AND FLENGTH ARE SPECIFIED
BOTH QUEUE AND QNAME ARE SPECIFIED
FROM IS MANDATORY
IF NUMITEMS IS SPECIFIED, ITEM AND REWRITE ARE INVALID
INVALID QUEUE OR QNAME
LENGTH/FLENGTH IS MANDATORY FOR INDIRECT FROM
LENGTH WITHOUT FROM
NUMITEMS MUST BE A LABEL (MAY HAVE ORIGINATED AS ITEM)
QUEUE OR QNAME MUST BE SPECIFIED

Copyright 2009 Automated Software Tools Corporation.

This is part of z390 distributed under open source GPL License.
31
zCICS Application Programming Guide

REWRITE REQUIRES ITEM

WRITEQ TYPE NOT RECOGNIZED

Conditions (RESP/RESP2)
INVREQ/0
LENGERR/0
ITEMERR/0
QIDERR/0

6) Program Control (0E)

a) ABEND

Name Operation Operands

name EXEC CICS ABEND
ABCODE()
CANCEL
NODUMP

ABCODE can be specified as ABCODE('xxxx') or ABCODE(label)

label must point to a 4-byte field.

Errors
ABCODE MUST NOT BEGIN WITH 'A'
ABCODE IS INVALID
BAD PARM

b) HANDLE ABEND

Name Operation Operands

name EXEC CICS HANDLE ABEND
CANCEL

Name Operation Operands

name EXEC CICS HANDLE ABEND
RESET

Name Operation Operands

name EXEC CICS HANDLE ABEND
LABEL(label)

label may take three forms:

Direct reference
Indirect reference
Adcon literal

Copyright 2009 Automated Software Tools Corporation.

This is part of z390 distributed under open source GPL License.
32
zCICS Application Programming Guide

Name Operation Operands

name EXEC CICS HANDLE ABEND
PROGRAM()

Can be specified as PROGRAM('xxxxxxxx') or PROGRAM(label)

label must point to an 8-byte field.

Any received COMMAREA when the EXEC CICS HANDLE ABEND is

issued is passed to the handling program when an abend occurs.

Notes:When an XCTL is executed, any HANDLE ABEND LABEL at the

current logical level is cleared as the current program is no longer in
use. HANDLE ABEND PROGRAMs are not cleared.

Errors
BAD PARM
HANDLE TYPE NOT RECOGNISED
INVALID PROGRAM
NO PARAMETERS SPECIFIED
PARMS MISSING OR TOO MANY PARMS

c) LINK

Name Operation Operands

name EXEC CICS LINK
PROGRAM()
COMMAREA(label)
LENGTH()
CHANNEL()

Executes another CICS program.

If COMMAREA is present, the address/length are passed.
Return is to the linker.

In zCICS both CHANNEL and COMMAREA may be specified.

A warning MNOTE is issued.

PROGRAM is mandatory
Can be specified as PROGRAM('xxxxxxxx') or PROGRAM(label)
label must point to an 8-byte field.

COMMAREA(label) is optional
label may take three forms:
Direct reference
Indirect reference
Adcon literal

Copyright 2009 Automated Software Tools Corporation.

This is part of z390 distributed under open source GPL License.
33
zCICS Application Programming Guide

LENGTH
Can be specified as LENGTH(value) or LENGTH(label)
LENGTH(value) supports the use of the length attribute.
label must point to a 2-byte hex value.

LENGTH can be omitted. When it is, the implied length of the

COMMAREA is used. LENGTH is mandatory when COMMAREA is an
indirect reference.

Errors
BAD PARM
INVALID CHANNEL
INVALID PROGRAM
PROGRAM IS MISSING
LENGTH IS MANDATORY FOR INDIRECT COMMAREA
LENGTH WITHOUT COMMAREA

Warning
CHANNEL and COMMAREA specified

Conditions (RESP/RESP2)
CHANNELERR/1
PGMIDERR/3

d) LOAD

Name Operation Operands

name EXEC CICS LOAD
PROGRAM()
ENTRY()/SET()
LENGTH(label)
FLENGTH(label)

Loads a module.
The intention in the zCICS environment is to load a table or some other data,
not an executable program.

PROGRAM is mandatory
Can be specified as PROGRAM('xxxxxxxx') or PROGRAM(label)
label must point to an 8-byte field.

At present, only modules with a suffix of .390 may be LOADed.

ENTRY and SET are optional

Must be specified as a permitted general register value.
Both are equivalent in zCICS.

Copyright 2009 Automated Software Tools Corporation.

This is part of z390 distributed under open source GPL License.
34
zCICS Application Programming Guide

LENGTH is optional
LENGTH(label) is the only format.
label must point to a 2-byte field.

FLENGTH is optional
FLENGTH(label) is the only format.
label must point to a 4-byte field.

Note: At task end the LOADed module is not RELEASEd.

Errors
BAD PARM
INVALID PROGRAM
LENGTH AND FLENGTH SPECIFIED
PROGRAM IS MISSING

Conditions (RESP/RESP2)
PGMIDERR/3

e) RELEASE

Name Operation Operands

name EXEC CICS RELEASE
PROGRAM()

Releases a previously LOADed module.

PROGRAM is mandatory
Can be specified as PROGRAM('xxxxxxxx') or PROGRAM(label)
label must point to an 8-byte field.

Errors
BAD PARM
INVALID PROGRAM
PROGRAM IS MISSING

Conditions (RESP/RESP2)
INVREQ/5
INVREQ/6

Copyright 2009 Automated Software Tools Corporation.

This is part of z390 distributed under open source GPL License.
35
zCICS Application Programming Guide

f) RETURN

Name Operation Operands

name EXEC CICS RETURN
TRANSID()
COMMAREA(label)
LENGTH()
CHANNEL()
IMMEDIATE

Returns to the last caller.

In zCICS both CHANNEL and COMMAREA may be specified.

A warning MNOTE is issued.

TRANSID
Optional, but when COMMAREA is specified, TRANSID is mandatory.
Can be specified as TRANSID('xxxx') or TRANSID(label)
label must point to a 4-byte field.

COMMAREA(label) is optional
label may take three forms:
Direct reference
Indirect reference
Adcon literal

LENGTH
Can be specified as LENGTH(value) or LENGTH(label)
LENGTH(value) supports the use of the length attribute.
label must point to a 2-byte hex value.

LENGTH can be omitted. When it is, the implied length of the

COMMAREA is used. LENGTH is mandatory when COMMAREA is an
indirect reference.

Errors
BAD PARM
IMMEDIATE REQUIRES TRANSID
INVALID CHANNEL
INVALID TRANSID
TRANSID IS MISSING
LENGTH IS MANDATORY FOR INDIRECT COMMAREA
LENGTH WITHOUT COMMAREA

Warning
CHANNEL and COMMAREA specified

Copyright 2009 Automated Software Tools Corporation.

This is part of z390 distributed under open source GPL License.
36
zCICS Application Programming Guide

Conditions (RESP/RESP2)
See the section on IGNORE for these conditions. Go here
CHANNELERR/1
INVREQ/1
INVREQ/2

g) XCTL

Name Operation Operands

name EXEC CICS XCTL
PROGRAM()
COMMAREA(label)
LENGTH()
CHANNEL()

Executes another CICS program.

In zCICS both CHANNEL and COMMAREA may be specified.

A warning MNOTE is issued.

If COMMAREA is present and both the address and length are the same as
passed to the current program, then address/length are passed to the new
program.

If the address or length differs, then a copy of the COMMAREA is taken and
the new address/length are passed to the new program.

Return is to the last linker.

PROGRAM is mandatory
Can be specified as PROGRAM('xxxxxxxx') or PROGRAM(label)
label must point to an 8-byte field.

COMMAREA(label) is optional
label may take three forms:
Direct reference
Indirect reference
Adcon literal

LENGTH
Can be specified as LENGTH(value) or LENGTH(label)
LENGTH(value) supports the use of the length attribute.
label must point to a 2-byte hex value.

Copyright 2009 Automated Software Tools Corporation.

This is part of z390 distributed under open source GPL License.
37
zCICS Application Programming Guide

LENGTH can be omitted. When it is, the implied length of the

COMMAREA is used. LENGTH is mandatory when COMMAREA is an
indirect reference.

Errors
BAD PARM
INVALID CHANNEL
INVALID PROGRAM
PROGRAM IS MISSING
LENGTH IS MANDATORY FOR INDIRECT COMMAREA
LENGTH WITHOUT COMMAREA

Warning
CHANNEL and COMMAREA specified

Conditions (RESP/RESP2)
CHANNELERR/1
PGMIDERR/3

7) Interval Control (10 and 4A)

Note:
FLENGTH is an extension; do not use this parameter if the source code is
likely to be ported back to a mainframe environment.

a) ASKTIME

Name Operation Operands

name EXEC CICS ASKTIME
ABSTIME()

Errors
BAD PARM

b) DELAY

Name Operation Operands

name EXEC CICS DELAY
REQID()
INTERVAL()/TIME()
FOR/UNTIL
HOURS()
MINUTES()
SECONDS()

Copyright 2009 Automated Software Tools Corporation.

This is part of z390 distributed under open source GPL License.
38
zCICS Application Programming Guide

INTERVAL
Can be specified as INTERVAL(s) through to INTERVAL(hhmmss).
i.e. INTERVAL(234) means wait for 2 minutes 34 seconds.

INTERVAL(label) is also permitted (extension).

label must point to a 6-byte character field with leading character zeros
as needed.
e.g. INTERVAL(MYTIME)
...
MYTIME DC C'000234'

TIME
Can be specified as TIME(s) through to TIME(hhmmss).
i.e. TIME(234) means resume the task at 2 minutes 34 seconds after
midnight. Expiration time rules apply; see the IBM Application
Programming Guide.

TIME(label) is also permitted (extension).

label must point to a 6-byte character field with leading character zeros
as needed.
e.g. TIME(MYTIME)
...
MYTIME DC C'000234'

FOR HOURS() MINUTES() SECONDS()

FOR is an alternative to INTERVAL.
HOURS/MINUTES/SECONDS must be numeric values.

UNTIL HOURS() MINUTES() SECONDS()

UNTIL is an alternative to TIME.
HOURS/MINUTES/SECONDS must be numeric values.
The result from the parameters is a time-of-day.
e.g. UNTIL SECONDS(10000) means resume the task at [Link].
Expiration time rules apply; see the IBM Application Programming Guide.

If no parameters are specified, then DELAY INTERVAL(0) is assumed.

Errors
BAD PARM
BOTH FOR AND UNTIL ARE SPECIFIED
BOTH INTERVAL AND TIME ARE SPECIFIED
FOR/UNTIL SPECIFIED, BUT NO TIME PARMS
HOURS/MINUTES/SECONDS ARE INVALID WITH INTERVAL OR TIME
HOURS/MINUTES/SECONDS ARE SPECIFIED WITHOUT FOR/UNTIL
INTERVAL/TIME CANNOT BE SPECIFIED WITH FOR/UNTIL
INTERVAL/TIME MUST BE 1 TO 6 BYTES

Copyright 2009 Automated Software Tools Corporation.

This is part of z390 distributed under open source GPL License.
39
zCICS Application Programming Guide

INVALID REQID

Conditions (RESP/RESP2)
INVREQ/4
INVREQ/5
INVREQ/6

c) FORMATTIME

Name Operation Operands

name EXEC CICS FORMATTIME
all parameters

Notes:
STRINGFORMAT is discarded as there is only one option.

DATESEP(label) and TIMESEP(label) are added as extensions.

Only the first byte is used.

DATESTRING returns the following 25-byte string.

The time zone (e.g. GMT) is not returned.
e.g. "Mon, 17 Dec 2007 [Link]"

Errors
ABSTIME IS MANDATORY
BAD PARM

Conditions (RESP/RESP2)
INVREQ/1

Copyright 2009 Automated Software Tools Corporation.

This is part of z390 distributed under open source GPL License.
40
zCICS Application Programming Guide

d) START

Name Operation Operands

name EXEC CICS START
TRANSID()
INTERVAL()/TIME()
TERMID()
REQID()
FROM()
LENGTH()/FLENGTH()
CHANNEL()
QUEUE()
RTRANSID()
RTERMID()
AFTER/AT
HOURS()
MINUTES()
SECONDS()

USERID is not supported.

In zCICS both CHANNEL and other parms may be specified.

A warning MNOTE is issued.

INTERVAL and TIME follow the same syntax and rules as for DELAY.
AFTER and AT follow the same syntax and rules as FOR and UNTIL in
DELAY above.

Errors
AFTER/AT SPECIFIED, BUT NO TIME PARAMETERS
BAD PARM
BOTH AFTER AND AT ARE SPECIFIED
BOTH INTERVAL AND TIME ARE SPECIFIED
BOTH LENGTH AND FLENGTH ARE SPECIFIED
FROM/(F)LENGTH MUST BOTH BE MISSING OR BOTH SPECIFIED
HOURS/MINUTES/SECONDS ARE INVALID WITH INTERVAL OR TIME
HOURS/MINUTES/SECONDS ARE SPECIFIED WITHOUT AFTER/AT
INTERVAL/TIME CANNOT BE SPECIFIED WITH AFTER/AT
INTERVAL/TIME MUST BE 1 TO 6 BYTES
INVALID CHANNEL
INVALID QUEUE
INVALID REQID
INVALID RTERMID
INVALID RTRANSID
INVALID TERMID
INVALID TRANSID
TRANSID IS MANDATORY

Copyright 2009 Automated Software Tools Corporation.

This is part of z390 distributed under open source GPL License.
41
zCICS Application Programming Guide

Warning
CHANNEL AND OTHER PARMS SPECIFIED BUT ALLOWED

Conditions (RESP/RESP2)
CHANNELERR/1
INVREQ/0
INVREQ/4
INVREQ/5
INVREQ/6
IOERR
LENGERR
TERMIDERR
TRANSIDERR

e) RETRIEVE

Name Operation Operands

name EXEC CICS RETRIEVE
INTO()/SET()
LENGTH()/FLENGTH()
RTRANSID()
RTERMID()
QUEUE()

WAIT is not supported.

Errors
BAD PARM
BOTH INTO AND SET ARE SPECIFIED
BOTH LENGTH AND FLENGTH ARE SPECIFIED
INTO OR SET MUST BE SPECIFIED
INVALID QUEUE
INVALID RTERMID
INVALID RTRANSID
LENGTH OR FLENGTH MUST BE A LABEL
SET REQUIRES LENGTH OR FLENGTH

Conditions (RESP/RESP2)
INVREQ/0
ENDDATA
ENVDEFERR
LENGERR

Copyright 2009 Automated Software Tools Corporation.

This is part of z390 distributed under open source GPL License.
42
zCICS Application Programming Guide

f) CANCEL

Name Operation Operands

name EXEC CICS CANCEL
REQID()

TRANSID is not supported.

Errors
BAD PARM
INVALID REQID
REQID IS MANDATORY

Conditions (RESP/RESP2)
INVREQ
NOTFND

8) Task Control (12)

a) ENQ

Name Operation Operands

name EXEC CICS ENQ
RESOURCE()
LENGTH()
NOSUSPEND

LENGTH
Can be specified as LENGTH(value) or LENGTH(label)
LENGTH(value) supports the use of the length attribute.

Errors
BAD PARM
RESOURCE IS MANDATORY

*** ENQ ON ADDRESS MAY NOT WORK IN zCICS

*** BUT THE COMMAND WILL BE PROCESSED
*** PLEASE CONTACT THE AUTHOR FOR ADVICE

Conditions (RESP/RESP2)
ENQBUSY
LENGERR/1

Copyright 2009 Automated Software Tools Corporation.

This is part of z390 distributed under open source GPL License.
43
zCICS Application Programming Guide

b) DEQ

Name Operation Operands

name EXEC CICS DEQ
RESOURCE()
LENGTH()

LENGTH
Can be specified as LENGTH(value) or LENGTH(label)
LENGTH(value) supports the use of the length attribute.

Errors
BAD PARM
RESOURCE IS MANDATORY

Conditions (RESP/RESP2)
LENGERR/1

9) BMS (18)

a) RECEIVE MAP

Name Operation Operands

name EXEC CICS RECEIVE MAP()
MAPSET()
INTO()

TERMINAL and ASIS are accepted and discarded.

SET, FROM and LENGTH are not supported.

MAP can be a quoted string, maximum 7 characters or a label pointing to a

7-byte field.

If MAP is a label, then INTO is mandatory.

Note: The map structure will not be cleared before the mapping takes
place.

If MAP is a string, then INTO is optional...

If INTO is omitted, the default is map.I
Note: The map structure will be cleared before the mapping takes place.

MAPSET can be a quoted string, maximum 7 characters or an address

pointing to an 8-byte field containing no more than 7 characters.
If MAPSET is omitted, then the MAPname is used.

Errors
BAD PARM
Copyright 2009 Automated Software Tools Corporation.
This is part of z390 distributed under open source GPL License.
44
zCICS Application Programming Guide

FROM NOT SUPPORTED

INTO IS REQUIRED WHEN MAP IS A LABEL
INVALID MAP NAME
INVALID MAPSET NAME
LENGTH NOT SUPPORTED
MAP IS MANDATORY

Conditions (RESP/RESP2)

Note: EIBRESP2 is an extension for MAPFAIL; please see the zCICS BMS
Guide for more information.

Many of the conditions can arise through a mismatch of map and

structure. Typically a map is re-assembled but the programs using it
are not.

INVMPSZ/0

MAPFAIL/1 The map cannot be found in the mapset.

MAPFAIL/2 A short read key (CLEAR or PA) has been pressed or there
are no modified fields.
MAPFAIL/3 Data has been received, but there are no named fields in the
map.
MAPFAIL/4 An SBA has been located, but there is no field in the map
that matches.
MAPFAIL/5 An SBA has been located, but it matches an unnamed field.
MAPFAIL/6 The data received for this field is longer than the DFHMDF
LENGTH= parameter.
MAPFAIL/7 There has been a mismatch between the physical map and
the DSECT.
MAPFAIL/8 Data to be processed by PICIN is over 31 digits.
Data is not numeric after being PACKed.
Data length is greater than the edit pattern allows.

INVREQ/0

Copyright 2009 Automated Software Tools Corporation.

This is part of z390 distributed under open source GPL License.
45
zCICS Application Programming Guide

b) SEND MAP

Name Operation Operands

name EXEC CICS SEND MAP()
MAPSET()
CURSOR/CURSOR()
DATAONLY/MAPONLY
ERASE/ERASEAUP
FROM()
LENGTH()
ALARM
FREEKB
FRSET
SET()

TERMINAL and WAIT are accepted and discarded.

ACCUM is not supported.

MAP can be a quoted string, maximum 7 characters or a label pointing to a

7-byte field.

If MAP is a label, then FROM is mandatory.

If MAP is a string, then FROM and/or LENGTH are optional...

If FROM is omitted, the default is map.O
If LENGTH is omitted, the default is map.L

LENGTH
LENGTH is supported but the value used is always that of the structure
length.
Can be specified as LENGTH(value) or LENGTH(label)
LENGTH(value) supports the use of the length attribute.
label must point to a 2-byte hex value.

MAPSET can be a quoted string, maximum 7 characters or a label pointing

to an 8-byte field containing no more than 7 characters.
If MAPSET is omitted, then MAP is used.

SET() is currently intended to be an internal parameter.

It does not conform to the standard used for BMS PAGING.

Errors
BAD PARM
CONTROL IS NOT COMPATABLE WITH SEND MAP
CURSOR POSITION AND SYMBOLIC CURSOR SPECIFIED
DATAONLY AND MAPONLY SPECIFIED
ERASE AND ERASEAUP SPECIFIED

Copyright 2009 Automated Software Tools Corporation.

This is part of z390 distributed under open source GPL License.
46
zCICS Application Programming Guide

FROM IS REQUIRED WHEN MAP IS A LABEL

INVALID MAP NAME
INVALID MAPSET NAME
MAP IS MANDATORY

Conditions (RESP/RESP2)
Note: EIBRESP2 is an extension for MAPFAIL, please see the zCICS BMS
Guide for more information.

INVMPSZ/0

MAPFAIL/1 The map cannot be found in the mapset.

MAPFAIL/8 Data to be processed by PICOUT is over 31 digits.
Data is not numeric after being PACKed.
Data length is greater than the edit pattern allows.
MAPFAIL/9 Override field or colour attribute is invalid

INVREQ/0
Note: Attempt to execute this in a non-terminal attached task.
This is not documented in the Manual.

10) Dump Control (1C)

a) DUMP

Name Operation Operands

name EXEC CICS DUMP
TRANSACTION
DUMPCODE()
COMPLETE
FROM()
LENGTH()/FLENGTH()
SEGMENTLIST()
LENGTHLIST()
NUMSEGMENTS()

TRANSACTION is mandatory.

DUMPCODE is mandatory and can be a constant or label.

label must point to a 4-byte field.
No syntax checking is done.

COMPLETE
If there are no storage area parameters then COMPLETE is the default.
Produces a SNAP dump ID=997,TEXT='DUMP dddd COMPLETE'

Copyright 2009 Automated Software Tools Corporation.

This is part of z390 distributed under open source GPL License.
47
zCICS Application Programming Guide

If there are storage area parameters and COMPLETE is not specified,

only the storage areas are dumped.

FROM() LENGTH()/FLENGTH()
Produces a SNAP dump ID=997,TEXT='DUMP dddd AREA'

LENGTH
Can be specified as a constant or label.
A constant must not exceed 32767.
A label must be 2 bytes and must not exceed 32767.

FLENGTH
Can be specified as a constant or label.
A constant must not exceed 2G-1.
A label must be 4 bytes and must not exceed 2G-1.

SEGMENTLIST/LENGTHLIST/NUMSEGMENTS
Produces multiple SNAP dumps ID=997,TEXT='DUMP dddd SEGMENT
nnn'

NUMSEGMENTS
Can be specified as a constant or label.
A constant must not exceed 2G-1.
A label must be 4 bytes and must not exceed 2G-1.

Errors
BAD PARM
BOTH LENGTH AND FLENGTH ARE SPECIFIED
DUMPCODE IS GREATER THAN 4 BYTES
DUMPCODE MUST BE SPECIFIED
LENGTH OR FLENGTH REQUIRES FROM
LENGTH OR FLENGTH MUST BE SPECIFIED
SEGMENTLIST, LENGTHLIST AND NUMSEGMENTS MUST
ALL BE SPECIFIED OR ALL ABSENT
TRANSACTION MUST BE SPECIFIED

Copyright 2009 Automated Software Tools Corporation.

This is part of z390 distributed under open source GPL License.
48
zCICS Application Programming Guide

11) System (4C)

a) INQUIRE FILE

The following formats are supported:

Name Operation Operands

name EXEC CICS INQUIRE FILE START

name EXEC CICS INQUIRE FILE START AT()

name EXEC CICS INQUIRE FILE END

name EXEC CICS INQUIRE FILE() NEXT ...

See parameter list below

name EXEC CICS INQUIRE FILE() ...

See parameter list below

The following parameters are supported:

ACCESSMETHOD, ADD, BASEDSNAME, BROWSE, DELETE,
DSNAME, ENABLESTATUS, KEYLENGTH ,KEYPOSITION, OBJECT,
OPENSTATUS, READ, RECORDFORMAT,
RECORDSIZE, TYPE, UPDATE

BASEDSNAME() and DSNAME() parameters:

The length of data returned is the implied length of the data
area to a maximum of 128 bytes. This can be extended on
request.

Errors
AT() IS SPECIFIED WITHOUT START
BAD PARM
FILE DOES NOT PRECEDE END
FILE DOES NOT PRECEDE START
FILE() CANNOT BE A STRING WHEN NEXT IS SPECIFIED
FILE() IS MISSING
INQUIRE TYPE NOT RECOGNIZED
INVALID AT()
INVALID FILE()
NEXT AND END ARE SPECIFIED
START AND END ARE SPECIFIED

Copyright 2009 Automated Software Tools Corporation.

This is part of z390 distributed under open source GPL License.
49
zCICS Application Programming Guide

b) SET FILE

The following formats are supported:

Name Operation Operands

name EXEC CICS SET FILE()/DATASET() ...
See parameter list below

The following parameters are supported:

ADD(), ADDABLE, NOTADDABLE, BROWSE(), BROWSABLE,
NOTBROWSABLE, DELETE(), DELETABLE, NOTDELETABLE,
ENABLESTATUS(), ENABLED, DISABLED, OPENSTATUS(), OPEN,
CLOSED, READ(), READABLE, NOTREADABLE, UPDATE(),
UPDATABLE, NOTUPDATABLE

Errors
BAD PARM
BOTH FILE AND DATASET SPECIFIED
FILE OR DATASET MUST BE SPECIFIED
INVALID FILE OR DATASET
MORE THAN ONE ADD PARAMETER
MORE THAN ONE BROWSE PARAMETER
MORE THAN ONE DELETE PARAMETER
MORE THAN ONE ENABLESTATUS PARAMETER
MORE THAN ONE OPEN STATUS PARAMETER
MORE THAN ONE READ PARAMETER
MORE THAN ONE UPDATE PARAMETER

Conditions (RESP/RESP2)
FILENOTFOUND
INVREQ/2
INVREQ/3
INVREQ/4
INVREQ/5
INVREQ/7
INVREQ/12
INVREQ/14
INVREQ/16
INVREQ/17
IOERR

Copyright 2009 Automated Software Tools Corporation.

This is part of z390 distributed under open source GPL License.
50
zCICS Application Programming Guide

12) Channels and Containers (34 and 96)

a) GET

Name Operation Operands

name EXEC CICS GET
CONTAINER()
CHANNEL()
INTO()/FLENGTH()
SET()/FLENGTH()
NODATA/FLENGTH()

Errors
BAD PARM
BOTH INTO AND SET SPECIFIED
CONTAINER IS MANDATORY
INTO AND NODATA SPECIFIED
INTO OR SET OR NODATA IS REQUIRED
INVALID CHANNEL
INVALID CONTAINER
NODATA REQUIRES FLENGTH
SET AND NODATA SPECIFIED
SET OR NODATA REQUIRES FLENGTH AS LABEL
SET REQUIRES FLENGTH

Conditions (RESP/RESP2)
CHANNELERR/2
INVREQ/4
LENGERR/11

b) PUT

Name Operation Operands

name EXEC CICS PUT
CONTAINER()
CHANNEL()
FROM()/FLENGTH()

Errors
BAD PARM
CONTAINER IS MANDATORY
FLENGTH IS MANDATORY FOR INDIRECT FROM
FLENGTH WITHOUT FROM
FROM IS MANDATORY
INVALID CHANNEL
INVALID CONTAINER

Copyright 2009 Automated Software Tools Corporation.

This is part of z390 distributed under open source GPL License.
51
zCICS Application Programming Guide

Conditions (RESP/RESP2)
CHANNELERR/1
CONTAINERERR/18
INVREQ/4
LENGERR/1

c) DELETE

Name Operation Operands

name EXEC CICS DELETE
CONTAINER()
CHANNEL()

Errors
BAD PARM
CONTAINER IS MANDATORY
INVALID CHANNEL
INVALID CONTAINER

Conditions (RESP/RESP2)
CHANNELERR/2
CONTAINERERR/10

d) MOVE

Name Operation Operands

name EXEC CICS MOVE
CONTAINER()
AS()
CHANNEL()
TOCHANNEL()

Errors
BAD PARM
CONTAINER AND/OR AS ARE MISSING
INVALID AS
INVALID CHANNEL
INVALID CONTAINER
INVALID TOCHANNEL

Conditions (RESP/RESP2)
CHANNELERR/1
CHANNELERR/2
CONTAINERERR/10
CONTAINERERR/18
INVREQ/4

Copyright 2009 Automated Software Tools Corporation.

This is part of z390 distributed under open source GPL License.
52
zCICS Application Programming Guide

e) STARTBROWSE

Name Operation Operands

name EXEC CICS STARTBROWSE
CONTAINER
CHANNEL()
BROWSETOKEN()

Errors
BAD PARM
INVALID CHANNEL
BROWSETOKEN IS MANDATORY
STARTBROWSE TYPE NOT RECOGNISED

Conditions (RESP/RESP2)
ACTIVITYERR/2
CHANNELERR/2

f) GETNEXT

Name Operation Operands

name EXEC CICS GETNEXT
CONTAINER()
BROWSETOKEN()

Errors
BAD PARM
BROWSETOKEN IS MANDATORY
CONTAINER IS MANDATORY

Conditions (RESP/RESP2)
END/2
TOKENERR/3

g) ENDBROWSE

Name Operation Operands

name EXEC CICS ENDBROWSE
CONTAINER
BROWSETOKEN()

Errors
BAD PARM
BROWSETOKEN IS MANDATORY
ENDBROWSE TYPE NOT RECOGNISED

Copyright 2009 Automated Software Tools Corporation.

This is part of z390 distributed under open source GPL License.
53
zCICS Application Programming Guide

Condition (RESP/RESP2)
TOKENERR/3

Appendicies

Keypress information

Aid/Function Press
ENTER Enter or Return
CLEAR CTRL+C
PA1-PA3 CTRL+F1 to CTRL+F3
PF1-PF12 F1 to F12
PF13-PF24 CTRL+ALT+F1 to CTRL+ALT+F12

ERASE EOF CTRL+F6

ERASE INPUT CTRL+F7

Change Summary

February 1, 2012
Amended SEND MAP LENGTH parameter description and removed error
message

Added support for FLENGTH on REAQ/WRITEQ TS, START and RETRIEVE

ASSIGN CHANNEL now supported

CHANNEL added to LINK, XCTL, RETURN, START

New Commands: GET, PUT, MOVE, DELETE, STARTBROWSE, GETNEXT,

ENDBROWSE

June 10, 2011

Added DFHREGS
Added Extra Parameters about NOEDF

November 1, 2010
Added INVREQ/1 to RETURN
Added NOTALLOC to RECEIVE
Added INVREQ and extra MNOTE to RECEIVE MAP
Added INVREQ to SEND CONTROL
Added INVREQ to SEND
Added INVREQ and MAPFAIL/9 to SEND MAP

Copyright 2009 Automated Software Tools Corporation.

This is part of z390 distributed under open source GPL License.
54
zCICS Application Programming Guide

Added INVREQ/5 to ASSIGN

New MNOTE for READNEXT and READPREV
Added SET FILE
Added REQID to CANCEL
Added test to HANDLE and IGNORE to detect no parameters
Extended support for the ENQ/DEQ LENGTH parameter
SEND CONTROL moved from BMS to Terminal Control
SEND documents discarded parameters.

August 1, 2009
Added INQUIRE FILE
Added ASSIGN

February 21, 2009

DFHEIGBL has been removed.
zCOBOL support for GETMAIN INITIMG added.
zCOBOL section added for EXEC CICS commands.
EXEC CICS SEND MAP supports SET(), but incompatibly.

November 24, 2008

Logic of READ with SET has changed slightly.
Extra reason for MAPFAIL/8.
GR2 has been eliminated from internal code and is available as a base register
(it isn't advised owing to instructions that may modify it).
DFHEIRET macro has been withdrawn; it is now incorporated into EXEC CICS
RETURN.
Added a section on EXEC CICS command syntax.
SEND MAP has FROM LENGTH and MAP(label) support.
RECEIVE MAP has INTO() support.
DSIDERR is supported for HANDLE/IGNORE CONDITION.
WRITEQ TS supports ITEM without REWRITE, messages changed.
Added START, RETRIEVE and CANCEL commands.
Added IMMEDIATE to EXEC CICS RETURN.
Added ENQ and DEQ commands.

June 27, 2008

Added ERASE EOF and ERASE INPUT to the keypress table
Added commands RECEIVE MAP, SEND MAP, SEND CONTROL and
references to the new BMS document.

January 18, 2008

Added READ/STARTBR/RESETBR parameters:
RRN, GTEQ, EQUAL, GENERIC, KEYLENGTH
Added READNEXT/READPREV parameters RRN, KEYLENGTH
Added ASKTIME, DELAY, FORMATTIME
Added DUMP TRANSACTION

Copyright 2009 Automated Software Tools Corporation.

This is part of z390 distributed under open source GPL License.
55
zCICS Application Programming Guide

References

SC34-6433 CICS Application Programming Guide

SC34-6434 CICS Application Programming Reference

Trademarks

IBM, CICS and VSAM are registered trademarks of International Business Machines
Corporation.

Credits

Author : Melvyn Maltz

Formatting : Walter Petras
Shipping Date : February 1, 2012
Z390 version : V1.5.05
zCICS version: V11

Copyright 2009 Automated Software Tools Corporation.

This is part of z390 distributed under open source GPL License.
56