MAPDEF

Format

A

Usage

Data mapping is an enhancement added to the REXXIMS interface. Because REXX does not offer variable structures, parsing the fields from your database segments or MFS output maps can be time consuming, especially when data conversion is necessary. The MAPDEF, MAPGET, and MAPPUT commands allow simple extraction of most formatted data.

• mapname is a 1- to 16-character case-independent name.
• definition (A) is a variable containing the map definition.
• REPLACE, if specified, indicates that a replacement of an existing map name is allowed. If not specified and the map name is already defined, an error occurs and message DFS3171E is sent to the SYSTPRT.

The map definition has a format similar to data declarations in other languages, with simplifications for REXX. In this definition, you must declare all variables that you want to be parsed with their appropriate data types. The format is shown in A in the syntax diagram.

Variable name

The variable name variable is a REXX variable used to contain the parsed information. Variable names are case-independent. If you use a STEM (REXX terminology for an array-like structure) variable, it is resolved at the time of use (at the explicit or implicit MAPGET or MAPPUT call time), and this can be powerful. If you use an index type variable as the STEM portion of a compound variable, you can load many records into an array simply by changing the index variable. Map names or tokens cannot be substituted for variable names inside a map definition.

Repositioning the internal cursor

A period (.) can be used as a variable place holder for repositioning the internal cursor position. In this case, the data type must be C, and the length can be negative, positive, or zero. Use positive values to skip over fields of no interest. Use negative lengths to redefine fields in the middle of a map without using absolute positioning.

All numeric data types can have a period and a number next to them. The number indicates the number of digits to the right of a decimal point when converting the number.

The .digit specification is expanded to 31 digits.

The length value can be a number or an asterisk (*), which indicates that the rest of the buffer will be used. You can specify an asterisk only for data types C and V. Data type V maps a 2-byte length field preceding the data string, such that when the declared length is 2, it takes 4 bytes. Data types P and Z accept values of 0 to 31 digits.

If a value other than asterisk (*) is given, the cursor position is moved by that value.

The startpos value resets the parsing position to a fixed location. If startpos is omitted, the column to the right of the previous map variable definition (cursor position) is used. If it is the first variable definition, column 1 is used.

Example

DBMapDef = 'RECORD         C    * :',  /* Pick up entire record     */
           'NAME           C   10 :',  /* Cols 1-10 hold the name   */
           'PRICE          Z.2  6 :',  /* Cols 11-16 hold the price */
           'CODE           C    2 :',  /* Cols 17-18 hold the code  */
           '.              C   25 :',  /* Skip 25 columns           */
           'CATEGORY       B    1'     /* Col 42 holds category     */
Address REXXIMS 'MAPDEF DBMAP DBMapDef'

Address REXXTDLI 'GU DBPCB *DBMAP' /* Read and decode a segment      */
If RC¬=0 Then Signal BadCall       /* Check for failure              */
Say CODE                           /* Can now access any Map Variable*/

The entire segment retrieved on the GU call is placed in RECORD. The first 10 characters are placed in NAME, and the next 6 are converted from zoned decimal to EBCDIC with two digits to the right of the decimal place and placed in PRICE. The next two characters are placed in CODE, the next 25 are skipped, and the next character is converted from binary to EBCDIC and placed in CATEGORY. The 25 characters that are skipped are present in the RECORD variable.