Chapter 6: Data Communication Calls

This chapter contains information on coding Data Communication Calls, including CICS, IMS DC, ISPF Dialog, and ISPF Prototyping.

Coding Calls

Observe the following when coding database calls:

Code the command using COBOL indentation.
Arguments can be one of the following:
- Variable
- 1- to 7-digit number
- Literal string delimited by single or double quotes
Separate each command component with a space, unless indicated otherwise in the syntax.
Some arguments are positional. Code positional arguments in the order shown in the syntax for each command.
To omit a positional argument, code an asterisk (*) in its place (unless it is the last argument).
A command can be continued on as many as 101 subsequent lines, by coding an ellipsis followed by a space. Break a command for continuation at any blank space, but do not break a parameter.
The plus symbol (+) serves as a text separator.

Comments:

Code anywhere in your program:

-KYWD-  12-*----20---*--
 /*     commentline

Code in Procedure Division only:

-KYWD-  12-*----20---*----
        /*commentline

Continuation is an ellipsis followed by a space (... ) and must continue on the immediate subsequent line.

CICS

ATTR

[TP-]ATTR screenname attribute1[+attribute2...]
... fieldname[(subscript)][+fieldname[(subscript)] ...]

Valid attributes are: BRT, NORM, DARK, MDTON, MDTOF, NUM[LOCK],NUMOFF, POS, [UN]PROT, ASKIP, DET, DETOFF, DEFCOL, RD, BL, PK, YL, GN, TQ, NU, [NO]BLINK, [NO]RVID, [NO]UNDER.

CIC-ADDRESS

CIC-ADDRESS option(linkdataname) [option(linkdataname) ...]

CIC-ASSIGN

CIC-ASSIGN CICSoption(dataarea) [CICSoption(dataarea)....]
... [ERROR(errorpara)]

CIC-CANCEL

CIC-CANCEL [REQID(name)] [TRANSID(name)]
... [SYSID(name)] [ERROR(errorpara)]

CIC-DELAY

CIC-DELAY [ REQID(name)] [INTERVAL(hhmmss)|TIME(hhmmss)]
... [ERROR(errorpara)]

CIC-DELETEQ

CIC-DELETEQ-TD|TS QUEUE(name) [SYSID(name)] [ERROR(errorpara)]

CIC-FREEMAIN

CIC-FREEMAIN DATA(linkdataname)

CIC-GETMAIN

CIC-GETMAIN SET(linkdataname) LENGTH(value)|FLENGTH(value)
... [INITIMG(value)] [ERROR(errorpara)]

CIC-LOAD

CIC-LOAD PROGRAM(name) [SET(linkdataname)]
... [LENGTH(dataarea)]|[FLENGTH(dataarea)]
... [ENTRY(pointref)] [HOLD] [ERROR(errorpara)]

CIC-READQ-TD

CIC-READQ-TD QUEUE(name) INTO(dataarea)|SET(linkdataname)
... [LENGTH(dataarea)] [SYSID(name)] [ERROR(errorpara)]

CIC-READQ-TS

CIC-READQ-TS QUEUE(name) INTO(dataarea)|SET(linkdataname)
... LENGTH(dataarea) NUMITEMS(dataarea) [ITEM(value)|NEXT]
... [SYSID(name)] [ERROR(errorpara)]

CIC-RELEASE

CIC-RELEASE PROGRAM(name) [ERROR(errorpara)]

CIC-SCHEDULE-PSB

CIC-SCHEDULE-PSB

CIC-SEND-TEXT

CIC-SEND-TEXT FROM(dataarea) LENGTH(value)
... [CICSoptions] [ERROR(errorpara)]

CIC-SERVICE-RELOAD

CIC-SERVICE-RELOAD linkdataname

CIC-START

CIC-START TRANSID(name) [INTERVAL(hhmmss)|TIME(hhmmss)]
... [CISoptions] [ERROR(errorpara)]

CIC-TERM-PSB

CIC-TERM-PSB

CIC-WRITEQ-TD

CIC-WRITEQ-TD QUEUE(name) FROM(dataarea)
... [LENGTH(value)] [SYSID(name)] [ERROR(errorpara)]

CIC-WRITEQ-TS

CIC-WRITEQ-TS QUEUE(name) FROM(dataarea) LENGTH(value)
... [SYSID(name)] [ITEM(dataarea) [REWRITE] [CICSoptions]
... [NOSUSPEND] [ERROR(errorpara)]

CLEAR

[TP-|SC-]CLEAR screenname

CLEAR-ATTRS

[TP-]CLEAR-ATTRS screenname

Error Handling Flags

Use the following 88-level flags for error handling after executing any CICS call:

CBIDERR
DISABLED
DSIDERR
DSSTAT
DUPKEY
DUPREC
ENDDATA
ENDFILE
ENDINPT
ENQBUSY
ENVDEFERR
EODS
EOF
EXPIRED

FUNCERR
IGREQCD
ILLOGIC
INVERRTERM
INVMPSZ
INVREQ
INVTSREQ
IOERR
ISCINVREQ
ITEMERR
JIDERR
LENGERR
MAPFAIL
NOJBUFSP

NOPASSBKRD
NOPASSBKWR
NOSPACE
NOSTG
NOTALLOC
NOTFND
NOTOPEN
PGMIDERR
QBUSY
QIDERR
QZERO
RDATT
RETPAGE
RTEFAIL

SEGIDERR
SELNERR
SESSBUSY
SESSIONERR
SIGNAL
SYSBUSY
SYSIDERR
TERMIDERR
TRANSIDERR
UNEXPIN
WRBRK

Invocation Mode Flags

Use the following 88-level fields provided by APS to indicate program invocation mode.

TP-INVOCATION-MODE           PIC X(01).
 88  TP-TRANSID-INVOKED   VALUE 'T'.
 88  TP-PROGRAM-INVOKED   VALUE 'P'.
 88  TP-SCREEN-INVOKED    VALUE 'S'.
 88  TP-LINK-INVOKED      VALUE 'L'.

LINK

Format 1, linking to an APS program:

[TP-]LINK programname [errorpara]
... [DLIUIB pcbname [pcbname] ...]
... [userparm [userparm]...]
... [COMMAREA(dataarea) LENGTH(value)]|[NOCA]

Format 2, linking to a non-APS program:

[TP-]LINK programname(NONAPS)[errorpara]
... [COMMAREA(dataarea) LENGTH(value)]|[NOCA]

NTRY

NTRY|ENTR screenname[(mapsetname)] [errorpara] [RETRY|NORETRY]

PF Key Values

Use the following PF key 88-levels generated by APS.

88-level PF-KEY	Value	88-levelPF-KEY	Value
ENTER-KEY	'''	PF8	'8'
CLEAR-KEY	'_'	PF9	'9'
PEN	'='	PF10	':'
OPID	'W'	PF11	'#'
MSRE	'X'	PF12	'@'
STRF	'H'	PF13	'A'
TRIG	'"'	PF14	'B'
PA1	'%'	PF15	'C'
PA2	'>'	PF16	'D'
PA3	','	PF17	'E'
PF0\|PF00	'''	PF18	'F'
PF1	'1'	PF19	'G'
PF2	'2'	PF20	'H'
PF3	'3'	PF21	'I'
PF4	'4'	PF22	'['
PF5	'5'	PF23	'.'
PF6	'6'	PF24	'<'
PF7	'7'

RESET-PFKEY

[TP-]RESET-PFKEY keyvalue

SCRNLIST

[TP-]SCRNLIST screenname1 [... screenname12]
... [MAPSET(mapsetname)] [LINKAGE] [REDEFINE|NOREDEF]

SEND

[TP-]SEND screen[(mapsetname)] [errorpara]
... [TRANSID(name)] [NORETURN] [NOERASE]
... [CICSoption [CICSoption] ...]

TERM

[TP-]TERM

TP-BACKOUT

TP-BACKOUT [ABORT[(name)]|NOABORT]

TP-LINKAGE

TP-LINKAGE linkdataname[/copybookname/macrofilename]
... [linkdataname[/copybookname/macrofilename] ...]

TP-NULL

TP-|SC-NULL screenname

TP-PERFORM

Format 1, performing a paragraph:
```
TP-PERFORM paragraphname
```

Format 2, performing a paragraph that passes arguments:

TP-PERFORM paragraphname actualarg1 [... actualarg8]
  .
  .
paraname ([+|-]formalarg1 [... [+|-]formalarg8)

XCTL

Format 1, transferring to an APS program:

[TP-]XCTL programname [errorpara] [LENGTH(value)]
... [DLIUIB pcbname [pcbname ...]] [userparm [userparm] ...]

Format 2, transferring to a non-APS program:

[TP-]XCTL programname(NONAPS) [errorpara] [LENGTH(value)]

IMS DC

ATTR

[TP-]ATTR screenname attribute1[+attribute2...]
... fieldname[(subscript)][+fieldname[(subscript)] ...]

Valid attributes are: BRT, NORM, DARK, NUM[OFF], POS, [UN]PROT, ASKIP, DET, DETOFF, DEFCOL, RD, BL, PK, YL, GN, TQ, NU, [NO]BLINK, [NO]RVID, [NO]UNDER.

CLEAR

[TP-|SC-]CLEAR screenname

CLEAR-ATTRS

[TP-]CLEAR-ATTRS screenname

Error Handling Flags

Use the following 88-level flags for error handling after executing any IMS DC call:

Flag	Status Code	Explanation
AB-ON-DC-CALL	CH X1 X8	Category 5 status code returned; call is not completed.
FP-ERR	FF FH FS FV	Category 3 status code returned. Fast Path error occurred; call is completed.
NO-MORE-MSGS	QC	Category 3 status code returned on the TP call; no more input messages exist.
NO-MORE-SEGS	QD	Category 3 status code returned; no more segments exist for this message.
SEG-NOT-FOUND	GE	Category 1 status code returned; segment not found.
OK-ON-DC-CALL	2 spaces, CC CE CF CG CI CJ CK CL FD FW FF FH FS FV GE QC QD	Categories 1 and 2 status codes returned; processing proceeds.
SEC-VIO	A4 FI	Category 4 status code returned; security violation occurred; call is not completed.
SPA-IO-ERR	XA XB XE XF XG X1 X2 X3 X4 X5 X6 X7 X8 X9	Categories 4 and 5 status codes returned; SPA error occurred; call is not completed.
TP-PGM-ERR	AA AB AD AL AP AT AY AZ A1 A2 A3 A4 A5 A6 A7 A8 A9 CA CB CD QE QH	Category 4 status code returned. Programming error occurred; call is not completed.

Flag

Status Code

Explanation

AB-ON-DC-CALL

CH X1 X8

Category 5 status code returned; call is not completed.

FP-ERR

FF FH FS FV

Category 3 status code returned. Fast Path error occurred; call is completed.

NO-MORE-MSGS

Category 3 status code returned on the TP call; no more input messages exist.

NO-MORE-SEGS

Category 3 status code returned; no more segments exist for this message.

SEG-NOT-FOUND

Category 1 status code returned; segment not found.

OK-ON-DC-CALL

2 spaces, CC CE CF CG CI CJ CK CL
FD FW FF FH FS FV GE QC QD

Categories 1 and 2 status codes returned; processing proceeds.

SEC-VIO

A4 FI

Category 4 status code returned; security violation occurred; call is not completed.

SPA-IO-ERR

XA XB XE XF XG X1 X2 X3 X4 X5 X6
X7 X8 X9

Categories 4 and 5 status codes returned; SPA error occurred; call is not completed.

TP-PGM-ERR

AA AB AD AL AP AT AY AZ A1 A2 A3
A4 A5 A6 A7 A8 A9 CA CB CD QE QH

Category 4 status code returned. Programming error occurred; call is not completed.

$IM- Calls

$IM-CHNG altview [destination]
$IM-CMD [PCBname] [msgarea]
$IM-GCMD [PCBname] [msgarea]
$IM-GN PCBname ssa1 [... ssa15]
$IM-GU PCBname ssa1 [... ssa15]
$IM-ISRT [PCBname]altview] ssa1 [... ssa15]
$IM-PURG [PCBname] [msgarea] [mod]

Invocation Mode Flags

Use the following 88-level fields provided by APS to indicate program invocation mode.

TP-INVOCATION-MODE           PIC X.
 88  TP-TRANSID-INVOKED   VALUE 'T'.
 88  TP-PROGRAM-INVOKED   VALUE 'P'.
 88  TP-SCREEN-INVOKED    VALUE 'S'.

LINK

[TP-]LINK subprogram [errorpara] [argument1 ... argument36]

MSG-SW

[TP-]MSG-SW trancode|programname|dataname [errorpara]
... [screenname|recordname] [keyword[+keyword]...]

NTRY

Format 1:
```
NTRY|ENTR
```

Format 2:

NTRY|ENTR screenname [errorpara] [RETRY|NORETRY]

Format 3:

NTRY|ENTR recordname [errorpara] [RETRY|NORETRY] *RECORD

PF Key Values

Use the following PF key 88-levels generated by APS.

88-level PF key	Value	88-level PF key	Value
ENTER-KEY	' '	PF11	'B'
NO-KEY-USED	LOW-VALUES	PF12	'C'
PF0\|PF00	' '	PF13	'D'
PF1\|PF01	'1'	PF14	'E'
PF2\|PF02	'2'	PF15	'F'
PF3\|PF03	'3'	PF16	'G'
PF4\|PF04	'4'	PF17	'H'
PF5\|PF05	'5'	PF18	'I'
PF6\|PF06	'6'	PF19	'J'
PF7\|PF07	'7'	PF20	'K'
PF8\|PF08	'8'	PF21	'L'
PF9\|PF09	'9'	PF22	'M'
PF10	'A'	PF23	'N'
		PF24	'O'

RESET-PFKEY

[TP-]RESET-PFKEY keyvalue

SCRNLIST

Format 1:

[TP-]SCRNLIST screenname1 [/screenname2[.../screenname40]]

Format 2:

[TP-]SCRNLIST screenname1 [ screenname2[... screenname40]

SEND

[TP-]SEND screenname|recordname [errorpara] [lterm]
... [keyword[+keyword] ...]

System Service Calls

IM-CHKP PCBname checkpointID
... [length1 dataarea1 [... length7 dataarea7]]
IM-XRST PCBname
... [length1 area1 [... length7 area7]]
... [checkpointID maxiolength]
IM-CHKP-OSVS PCBname checkpointID
IM-DEQ PCBname deqcharacter
IM-GSCD PCBname
IM-LOG PCBname logcode loglength message
IM-ROLB PCBname [msgarea]
IM-ROLL
IM-STAT-DBAS-FULL PCBname
IM-STAT-DBAS-UNFORMATED PCBname
IM-STAT-DBAS-SUMMARY PCBname
IM-STAT-VBAS-FULL PCBname
IM-STAT-VBAS-UNFORMATED PCBname
IM-STAT-VBAS-SUMMARY PCBname

TERM

[TP-]TERM

TP-BACKOUT

TP-BACKOUT [ABORT|NOABORT]

TP-LINKAGE

TP-LINKAGE linkdataname[/copybookname/macrofilename]
... [linkdataname[/copybookname/macrofilename] ...]

TP-NULL

TP-|SC-NULL screenname

TP-PERFORM

Format 1, performing a paragraph:
```
TP-PERFORM paragraphname
```

Format 2, performing a paragraph that passes arguments:

TP-PERFORM paragraphname
... actualargument1 [... actualrgument8]
  .
  .
paraname ([+|-]formalargument1 [... [+|-]formalargument8)

ISPF Dialog

ATTR

[TP-]ATTR screenname attribute1[+attribute2...]
... fieldname[(subscript)][+fieldname[(subscript)] ...]

Valid attributes are: BRT, NORM, DARK, NUM[OFF], POS, [UN]PROT, ASKIP, DET, DETOFF, DEFCOL, RD, BL, PK, YL, GN, TQ, NU, [NO]BLINK, [NO]RVID, [NO]UNDER.

CLEAR

[TP-|SC-]CLEAR screenname

CLEAR-ATTRS

[TP-]CLEAR-ATTRS screenname

DLG-ISPEXEC

DLG-ISPEXEC commandproceduresyntax

DLG-ISREDIT

DLG-ISREDIT commandproceduresyntax

DLG-SETMSG

Format 1, SETMSG definition:
```
DLG-SETMSG [erroridentifier|messageID]
```

Format 2, SETMAG definition for execution by Format 3:

DLG-SETMSG [SHORT 'shortmessagetext'] [LONG 'longmessagetext']
... [ALARM 'YES'|'NO'] [HELP 'helppanelname']

Format 3, SETMSG execution:

DLG-SETMSG erroridentifier
... [SHORT 'shortmessagetext'] [LONG 'longmessagetext']
... [ALARM 'YES'|'NO'] [HELP 'helppanelname']

DLG-VCOPY

DLG-VCOPY [COBOLlevel] COBOLvariable [[FROM] dialogvariable]
... PIC COBOLpicture|LEN value [GENONLY]

DLG-VDEFINE

DLG-VDEFINE [COBOLlevel] COBOLvariable [[AS] dialogvariable]
...PIC COBOLpicture|LEN value [GENONLY]

DLG-VDELETE

DLG-VDELETE dialogvariable|*

DLG-VREPLACE

DLG-VREPLACE [COBOLlevel] COBOLvariable 
... [[INTO] dialogvariable]
... PIC COBOLpicture|LEN value [GENONLY]

DLG-VRESET

DLG-VRESET

Invocation Mode Flags

Use the 88-level fields provided by APS to indicate program invocation mode.

TP-INVOCATION-MODE           PIC X(01).
 88  TP-TRANSID-INVOKED   VALUE 'T'.
 88  TP-PROGRAM-INVOKED   VALUE 'P'.
 88  TP-SCREEN-INVOKED    VALUE 'S'.
 88  TP-LINK-INVOKED      VALUE 'L'.

LINK

Format 1, CALL format:

[TP-]LINK programname [errorpara]
... [userparm [userparm]...] [COMMAREA]

Format 2, SELECT format:

[TP-]LINK programname [errorpara] [options]

NTRY

NTRY|ENTR screenname [errorpara] [RETRY|NORETRY]
... [CANCEL|RETURN] [dataareas]

PF Key Values

Use the following PF key 88-levels generated by APS.

88-level PF key	Value	88-level PF key	Value
ENTER-KEY	' '	PF13	'PF13'
PF1\|PF01	'PF01'	PF14	'PF14'
PF2\|PF02	'PF02'	PF15	'PF15'
PF3\|PF03	'PF03'	PF16	'PF16'
PF4\|PF04	'PF04'	PF17	'PF17'
PF5\|PF05	'PF05'	PF18	'PF18'
PF6\|PF06	'PF06'	PF19	'PF19'
PF7\|PF07	'PF07'	PF20	'PF20'
PF8\|PF08	'PF08'	PF21	'PF21'
PF9\|PF09	'PF09'	PF22	'PF22'
PF10	'PF10'	PF23	'PF23'
PF11	'PF11'	PF24	'PF24'
PF12	'PF12'

RESET-PFKEY

[TP-]RESET-PFKEY keyvalue

SCRNLIST

Format 1:

[TP-]SCRNLIST screenname1[(LK)] [... screenname40[(LK)]]

Format 2:

[TP-]SCRNLIST screenname1[ ... screenname40]... [LINKAGE]

SEND

[TP-]SEND screen [errorpara] [CONTINUE|NOCONTINUE]

TERM

TERM call:ISPF DialogTP-TERM call:ISPF Dialog[TP-]TERM

TP-LINKAGE

TP-LINKAGE linkdataname[/copybookname/macrofilename]
... [linkdataname[/copybookname/macrofilename] ...]

TP-NULL

TP-|SC-NULL screenname

TP-PERFORM

Format 1, performing a paragraph:
```
TP-PERFORM paragraphname
```

Format 2, performing a paragraph that passes arguments:

TP-PERFORM paragraphname
... actualargument1 [... actualargument8]
  .
  .
paraname ([+|-]formalargument1 [... [+|-]formalargument8)

ISPF Prototyping

ATTR

[TP-]ATTR screenname POS fieldname[(subscript)]

LINK

[TP-]LINK programname [errorpara] [COMMAREA(dataarea)
... LENGTH(value)]|[NOCA]

MSG-SW

[TP-]MSG-SW trancode|programname|dataname [errorpara]
... [screenname]

NTRY

NTRY|ENTR screenname [RETRY|NORETRY] [CANCEL|RETURN]
... [dataareas]

RESET-PFKEY

[TP-]RESET-PFKEY keyvalue

SCRNLIST

Any syntax valid in the other DC environments

SEND

Format 1:

[TP-]SEND screen[(mapsetname)] [errorpara]
... [TRANSID(name)] [NORETURN] [NOERASE]
... [CICSoption [CICSoption] ...]

Format 2:

[TP-]SEND screen[(mapsetname)] [errorpara] [lterm]

Format 3:

[TP-]SEND screen [errorpara] [CONTINUE|NOCONTINUE]

TERM

[TP-]TERM

TP-PERFORM

Format 1, performing a paragraph:
```
TP-PERFORM paragraphname
```

Format 2, performing a paragraph that passes arguments:

TP-PERFORM paragraphname
... actualargument1 [... actualargument8]
  .
  .
paraname ([+|-]formalargument1 [... [+|-]formalargument8)

XCTL

Format 1:
```
[TP-]XCTL programname [LENGTH(value)]
```

Format 2:

[TP-]XCTL programname(NONAPS) [LENGTH(value)]