File control - commands, options, and conditions - I

Read a record (READ)

READ
FILE¹(name)
{INTO(data-area)|SET(ptr-ref)}
[LENGTH(data-area)]²
RIDFLD(data-area)
[KEYLENGTH(data-value)³[GENERIC]4]
[SYSID(name)]
[RBA4|RRN4|DEBKEY5|DEBREC5]
[GTEQ|EQUAL]4.
[UPDATE]

Conditions: DISABLED, FILENOTFOUND6,
DUPKEY4, ILLOGIC4, INVREQ, IOERR,
ISCINVREQ, LENGERR, NOTAUTH, NOTFND,
NOTOPEN, SYSIDERR


You use this command to read a record, via a file, from a direct access data set on a local or remote system.

If you include the UPDATE option, you must identify the record to be updated by the record identification field specified in the RIDFLD option. Immediately upon completion of a READ UPDATE command, the RIDFLD data area is available for reuse by the application program.

You can specify only one update operation per data set within a transaction at any given time. Further, to avoid deadlock when accessing a VSAM data set, your next command to the data set should be a REWRITE, DELETE without RIDFLD, or UNLOCK.

The following example shows you how to read a record from a data set, via a file named 'MASTER', into a specified data area:

EXEC CICS READ
INTO(RECORD)
FILE('MASTER')
RIDFLD(ACCTNO)
Write a record (WRITE)

You use this command to write a record to a direct access data set on a local or remote system. For example:

EXEC CICS WRITE
FROM(RECORD)
LENGTH(DATLEN)
FILE('MASTER')
RIDFLD(KEYFLD)

For a VSAM entry-sequenced data set (ESDS), the record is always added at the end of the data set. VSAM does not use the identification field specified in RIDFLD when calculating the RBA of the new record, but the new RBA is returned to the application in the record identification field specified in the RIDFLD option.

For a VSAM KSDS, the record is added in the location specified by the associated key; this location may be anywhere in the data set. For VSAM data sets, the key in the record and the key in the RIDFLD identification field must be the same.

Records for ESDS and KSDS data sets can be either fixed length or variable length. Those for a relative record data set must be fixed length. MASSINSERT operations must proceed with ascending keys, and must be terminated by an UNLOCK before any other request to the same data set.


Minimum function BMS

Minimum function BMS supports the IBM 3270 and IBM 3270-like range of displays and printers (but not SCS printers).

Screen layout design

The features of the 3270 system allow screen layouts to be designed for operator convenience and efficiency. The success of an online system depends on its ease-of-use, screen clarity, and terminal operator acceptance. The following features of some 3270 displays make it easier for the layout designer to fulfil the requirements:

* Color
* Field highlighting
* Programmed symbols
* Easy correction
* Numeric shift for numeric data
* Validation
* Field delimiters or stoppers (to control the length of data entered).

The first step in designing 3270 screen layouts is to divide the screen into functional areas such as a title area, an application data area, and a message area.

Defining a map set

You use the DFHMSD macro to define a set of maps, that is, a 'map set'. The macro consists of operands that define characteristics of the map, or maps,Comprising the map set. Some operands specified in DFHMSD can be overridden, for individual maps or fields that make up the map set, by operands in the map(DFHMDI) and field (DFHMDF) definition macros.

Defining maps within a map set

Each map in a map set is defined using the DFHMDI macro. This macro is similar in form to DFHMSD. It allows you to override some of the options inherited from DFHMSD, and to specify some new ones.

Defining fields within a BMS map

The DFHMDF macro is used to specify initial attributes to be given to fields within a map.
You use DFHMDF to specify the following:

* The one-to-seven character name of the field. You only have to name fields if your application
program refers to them. Only named fields appear in the Symbolic description map.

* The position of the start of the field relative to the map origin. This is the position of the
attribute byte for the field (POS operand).

* The length of the field excluding its attribute byte (LENGTH operand). Specifying the length of
a field does not cause BMS to delimit it with "stopper" fields; You must do that yourself either
by making successive fields contiguous, or by inserting fields with ATTRB=PROT.

* A field cannot extend beyond the right-hand edge of the map, that is, it cannot "wrap" around
the display.

* Whether data placed in the field is to be left-or right-justified. (JUSTIFY operand.)

* What character must be used to pad a justified field? (JUSTIFY=BLANK or JUSTIFY=ZERO.)

* The initial contents of the field. (INITIAL or XINIT operand.)

* Attributes of the field, for example, skip, protect, no display. (ATTRB operand.)

* Extended data stream attributes of the field. (COLOR, HILIGHT, OUTLINE, PS, SOSI,
TRANSP, and VALIDN operands.)

* A picture to be used to edit input. (PICIN and PICOUT operands.)


Terminating a map set definition

The macro DFHMSD TYPE=FINAL terminates a map set definition. It is coded as follows:

mapset DFHMSD TYPE=FINAL

Assembling and cataloging BMS maps

You assemble a BMS map definition to generate either a symbolic description map or a physical map. The CICS/MVS Operations Guide describes how to assemble and catalog the maps.

Symbolic description map

A symbolic description map set definition (DFHMSD TYPE=DSECT) is assembled, and cataloged in the source statement library. The member name is usually the same as the map set name, but it need not be. Alternatively, the symbolic description map can be copied or inserted directly into the application program.

Physical map

A physical map set definition (DFHMSD TYPE=MAP) is assembled, link edited, and cataloged in the CICS load library.

When you catalog the physical map, consider whether to add a suffix to its name (specified with the NAME statement). The reason for suffixing a map is that you might want to produce alternative versions of it for different terminal models.

Map set suffixing

If you want to execute the same transaction from more than one type of terminal, you might need to use BMS map set suffixing. If you are prepared to use the same map to format data for all your terminals, you need not read the rest of this section. If however, you wish to organize output data according to the terminal in use, making best use of its features, you ought to consider suffixing map sets.
For example, if you have displays with screens of different sizes, you might want to arrange display fields differently for each size of screen, ensuring that each display appears "balanced." You add a different suffix to each version of the same map. When a mapping operation is requested by a BMS command, CICS adds a suffix to the map set name specified in the command, and attempts to load a map set with that suffixed name.