zCICS
Basic Mapping Support
v11
Automated Software Tools Corporation.
Copyright 2009 Automated Software Tools Corporation.
This is part of z390 distributed under open source GPL License.
zCICS Basic Mapping Support
Table of Contents
Introduction
BMS Macros
DFHMSD
DFHMDI
DFHMDF
Map generation
Change Summary
Trademarks
Credits
Copyright 2009 Automated Software Tools Corporation.
This is part of z390 distributed under open source GPL License.
2
zCICS Basic Mapping Support
Introduction
This document outlines the extensions and facilities implemented in zCICS.
Please refer to the IBM Manuals on BMS usage.
The documentation for EXEC CICS SEND MAP, RECEIVE MAP and SEND
CONTROL are in the zCICS Application Programming Guide.
The following BMS facilities are not yet implemented:
Support for devices outside the 3270 family
Printers
Extended Attributes (other than colour) and alternate screen size
Dynamic Map Positioning and ACCUM processing
Partitioning
Paging
Copyright 2009 Automated Software Tools Corporation.
This is part of z390 distributed under open source GPL License.
3
zCICS Basic Mapping Support
BMS Macros
1) DFHMSD -- Mapset definition and termination
Although DFHMSD is optional it is recommended that one is coded. A default set of
values will be internally generated from the DFHMDI macro if missing.
Name Operation Operands
mapset DFHMSD TYPE=MAP/DSECT/FINAL
MODE=IN/OUT/INOUT
LANG=ASM/COBOL
CTRL=
CURSLOC=YES/NO
DSATTS=
EXTATT=YES/NO/MAPONLY
MAPATTS=
STORAGE=AUTO
TIOAPFX=YES/NO
TERM=
Notes:
TERM= is supported but discarded
Errors:
A MAXIMUM OF 3 OPERANDS ALLOWED IN CTRL
CANNOT HAVE MORE THAN ONE DFHMSD MACRO
DSATTS IS SPECIFIED WITHOUT MAPATTS
EXTATT CONFLICTS WITH DSATTS/MAPATTS
EXTATT NOT NO, MAPONLY OR YES
INVALID CURSLOC -- cursloc
INVALID LANG -- lang
INVALID MODE -- mode
INVALID STORAGE -- storage
INVALID TIOAPFX -- tioapfx
INVALID TYPE -- type
MAPSET NAME IS MISSING
POSITIONAL OPERAND xxxx INVALID
Copyright 2009 Automated Software Tools Corporation.
This is part of z390 distributed under open source GPL License.
4
zCICS Basic Mapping Support
2) DFHMDI -- Map definition
Name Operation Operands
mapname DFHMDI TYPE=MAP/DSECT
MODE=IN/OUT/INOUT
LANG=ASM/COBOL
CTRL=
CURSLOC=YES/NO
DSATTS=
EXTATT=
MAPATTS=
SIZE=(24,80)
LINE=1
COLUMN=1
STORAGE=AUTO
TIOAPFX=YES/NO
JUSTIFY=
NOLABEL=
Notes:
TYPE and STORAGE are required here only if the DFHMSD macro is omitted.
Parameters TYPE, MODE, LANG, CTRL, CURSLOC, DSATTS, EXTATT,
MAPATTS, STORAGE and TIOAPFX can all be omitted if the settings specified
in DFHMSD are correct for this map.
MODE may be specified as an override to DFHMSD.
This facility is an extension.
Any option(s) specified in CTRL will override all the options specified in
DFHMSD.
For LINE and COLUMN, only numeric parameters are supported.
JUSTIFY is discarded.
NOLABEL is a special parameter for zCICS maps.
It suppresses the label indicated and speeds up the map assembly.
When used on the DFHMDI macro it applies to all labelled DFHMDF macros
that follow. When specified on the DFHMDF macro it overrides any
specification on the DFHMDI macro.
The labels that can be suppressed are as follows:
A (attribute), C (colour), F (flag), L (length), O (output)
eg. NOLABEL=ACF
Copyright 2009 Automated Software Tools Corporation.
This is part of z390 distributed under open source GPL License.
5
zCICS Basic Mapping Support
Errors:
A MAXIMUM OF 3 OPERANDS ALLOWED IN CTRL
COLUMN CANNOT EXCEED nn
DSATTS is specified without MAPATTS
EXTATT conflicts with MAPATTS/DSATTS
EXTATT not omitted, NO, MAPONLY or YES
INVALID CTRL OPTION - ctrl
INVALID CURSLOC -- cursloc
INVALID MODE -- mode
INVALID SIZE -- size
INVALID TIOAPFX -- tioapfx
LINE CANNOT EXCEED nn
MAPNAME IS MISSING
MSD AND MDI TYPE MISMATCH
POSITIONAL OPERAND xxxx INVALID
Copyright 2009 Automated Software Tools Corporation.
This is part of z390 distributed under open source GPL License.
6
zCICS Basic Mapping Support
3) DFHMDF -- Field definition
Name Operation Operands
fldname DFHMDF POS=n/(n,n)
LENGTH=
ATTRB=
COLOR=
JUSTIFY=
INITIAL=
XINIT=
PICIN=
PICOUT=
OCCURS=
GRPNAME=
NOLABEL=
Notes:
fldname may now use long names
POS does not have to be in sequence.
If ATTRB is missing then ATTRB=(ASKIP,NORM) is assumed.
If protection or intensity parameters are missing then a sensible default is
assumed.
A field specified as ATTRB=(UNPROT,NUM) will only accept digits 0-9. Some
3270 models also allowed dots and commas.
Extensive cross-checking is made, such that any 'unusual' map structure is
flagged as an error. A peruse of the errors below give a good indication of
these types of map structure.
Extensions:
ATTRB=(ALPHA) has been added as the opposite of NUM
XINIT=FF..
The dots are replaced by a hex code of a fill character.
This will generate an RA order to fill this field for its whole length.
e.g.
Instead of coding INITIAL='__________'
Code XINIT=FF6D
PICIN and PICOUT (General)
These parameters are not well-described in the IBM Manuals.
Copyright 2009 Automated Software Tools Corporation.
This is part of z390 distributed under open source GPL License.
7
zCICS Basic Mapping Support
PICIN (COBOL)
A symbolic reference to the input data, the data cannot be
changed.
ie. PICIN='$$$9' does not make any sense
PICIN='99V99' tells COBOL where the decimal point is
PICOUT (COBOL)
The data is subject to an editting process.
ie. PICOUT='$$$9' the data is editted
PICOUT='99V99' is the same as '9(4)'
PICIN (Assembler)...extension
The incoming data IS subjected to an editting process.
Described below.
PICOUT (Assembler)...extension
The outgoing data is subjected to an editting process.
Described below.
PICIN and PICOUT (Assembler)
The parameter is (almost) a standard edit word with some
restraints.
Currently only numeric data can be subjected to PICIN/PICOUT.
PICOUT...
Operates for a SEND MAP, but not if MAPONLY is specified.
Data is taken from the map structure and subjected to the
edit word before being sent to the screen.
PICIN...
Operates for a RECEIVE MAP.
The data received is subjected to the edit word and then
passed to the application in the map structure.
Note that the resulting data may no longer be numeric.
The edit word has some strict rules at present. Suggested
extensions are most welcome.
The first hex pair must be 40 (blank), 5C (asterisk), 5B (dollar)
or 4D (open bracket).
Blank and asterisk are fill characters, dollar and open bracket
are float characters.
The remaining hex pairs can be 20 (digit select), 21 (significance
Copyright 2009 Automated Software Tools Corporation.
This is part of z390 distributed under open source GPL License.
8
zCICS Basic Mapping Support
starter), 4B (dot) or 6B (comma).
The number of 20 and 21's must be odd.
Examples...
PICOUT=4020216B202020
Data is 12345, displayed as 12,345
PICOUT=5B20216B202020
Data is 1234 , displayed as $1,234
PICOUT=5C20216B202020
Data is 89, displayed as *****89
PICIN is no different, just that it edits incoming data.
If the data to be processed is not numeric after being PACKed,
a MAPFAIL/8 condition is raised.
IMG file
For each TYPE=MAP generation, a [Link] file is generated.
This gives a symbolic picture of the resulting screen and can be used for
planning map changes.
See the file [Link] for a good example.
NOLABEL
NOLABEL is a special parameter for zCICS maps.
It suppresses the label indicated and speeds up the map assembly.
When used on the DFHMDI macro it applies to all labelled DFHMDF
macros that follow. When specified on the DFHMDF macro it overrides
any specification on the DFHMDI macro.
The labels that can be suppressed are as follows:
A (attribute), C (colour), F (flag), L (length), O (output)
eg. NOLABEL=ACF
Errors:
A MAXIMUM OF 2 OPERANDS ALLOWED IN JUSTIFY
ADJACENT ATTRIBUTE AT POS nnn
ATTRIBUTE CONFLICT - ALPHA AND NUM
ATTRIBUTE CONFLICT - ASKIP AND ALPHA
ATTRIBUTE CONFLICT - ASKIP AND NUM
ATTRIBUTE CONFLICT - ASKIP AND PROT
Copyright 2009 Automated Software Tools Corporation.
This is part of z390 distributed under open source GPL License.
9
zCICS Basic Mapping Support
ATTRIBUTE CONFLICT - ASKIP AND UNPROT
ATTRIBUTE CONFLICT - BRT AND DRK
ATTRIBUTE CONFLICT - BRT AND NORM
ATTRIBUTE CONFLICT - NORM AND DRK
ATTRIBUTE CONFLICT - PROT AND UNPROT
BAD LENGTH - length
BOTH INITIAL AND XINIT ARE SPECIFIED
CONFLICTING JUSTIFY PARMS
GRPNAME AND OCCURS ARE SPECIFIED
GRPNAME SPECIFIED WITHOUT FLDNAME
IC ATTRIBUTE HAS OCCURRED IN ANOTHER MDF MACRO
INITIAL/XINIT IS GREATER THAN LENGTH
INITIAL/XINIT IS INVALID WITH LENGTH=0
INVALID ATTRB OPTION – attrb
INVALID COLOR
INVALID JUSTIFY OPTION - justify
INVALID OCCURS - occurs
INVALID POS - pos
JUSTIFY CONFLICT - BLANK AND ZERO
JUSTIFY CONFLICT - LEFT AND RIGHT
LENGTH=0 IS INVALID FOR NAMED FIELD
PICIN/PICOUT CAN ONLY BE SPECIFIED FOR A NAMED FIELD
PICIN/PICOUT HAS ODD NUMBER OF HEX DIGITS
PICIN/PICOUT HEX LENGTH NOT EQUAL TO LENGTH
PICIN/PICOUT IS INVALID
PICIN/PICOUT: 1ST PAIR NOT 40, 5C, 5B, 4D
PICIN/PICOUT: NUMBER OF 20/21 IS NOT ODD
POS nnn OVERLAPS WITH ANOTHER FIELD
POS COLUMN+LENGTH EXCEEDS DEFINED MAP SIZE
POS EXCEEDS DEFINED MAP SIZE
POS HAS TOO MANY PARAMETERS
POSITIONAL OPERAND xxxx INVALID
SINGLE POS EXCEEDS DEFINED MAP SIZE
SPECIAL FORMAT XINIT CANNOT BE SPECIFIED IF LENGTH IS LESS
THAN 8
UNNAMED FIELD HAS UNPROT OR FSET, INPUT DATA CANNOT BE
MAPPED
XINIT HAS ODD NUMBER OF HEX DIGITS
The following errors occur owing to internal limits.
Please report them.
AN INTERNAL ERROR HAS OCCURRED
ERROR IN ATTRIBUTE TABLE nnnn
AN INTERNAL ERROR HAS OCCURRED
Copyright 2009 Automated Software Tools Corporation.
This is part of z390 distributed under open source GPL License.
10
zCICS Basic Mapping Support
MAPSIZE TOO LARGE - nnnn
AN INTERNAL ERROR HAS OCCURRED
PICIN/PICOUT LENGTH GREATER THAN 50 BYTES
Copyright 2009 Automated Software Tools Corporation.
This is part of z390 distributed under open source GPL License.
11
zCICS Basic Mapping Support
Map generation
See the sample generation for MAP01 embedded in [Link].
This generates the TYPE=DSECT ([Link]) and the TYPE=MAP
(MAP01.390).
For LANG=COBOL, the structure will have a .CPZ suffix.
This suffix is the default for the zCOBOL COPY statement.
As the program name is the same, the TYPE=DSECT assembler output is
renamed mapset.PR1.
Change Summary
February 1, 2012
Comment on long fldname support added
November 1, 2010
Colour support, EXTATT, DSATTS, MAPATTS and COLOR parameters
added and extra MNOTEs.
DFHMDI and DFHMDF new NOLABEL parameter
August 1, 2009
Update to PICIN and PICOUT doc.
February 21, 2009
Added LANG=COBOL and mention of the .CPZ suffix
Added commentary separating PICIN/PICOUT by language
November 24, 2008
Added comment about POS
TIOAPFX is fully supported
TERM is supported but discarded
Extra error checking for LINE/COLUMN
Trademarks
IBM, CICS and VSAM are registered trademarks of International Business
Machines Corporation.
Copyright 2009 Automated Software Tools Corporation.
This is part of z390 distributed under open source GPL License.
12
zCICS Basic Mapping Support
Credits
Author : Melvyn Maltz
Formatter : 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.
13