Verbs and Built-in Functions › &ASSIGN › &ASSIGN Syntax for MDO Data Assignments

&ASSIGN Syntax for MDO Data Assignments

When &ASSIGN OPT=DATA is specified, the MDO operand is used to indicate that a source or target data item is all or part of an MDO. The full syntax allowable is as follows:

&ASSIGN [ OPT=DATA ]
        { VARS=aaa |
          VARS=(aaa,bbb,...,ccc) |
          VARS=aaa* [ RANGE=(start, end) | GENERIC ] |
          REPLACE | ADD | UPDATE |
          ARGS [ RANGE=(start, end) ] |
          MDO=aaa.bbb.ccc |
          MDO=aaa.bbb.ccc.* |
          MDO=aaa.bbb{*}.ccc [ RANGE=(start, end) ] |
          MDO=aaa [ MAP=map ] }  
        { FROM
          { VARS=aaa |
            VARS=(aaa,bbb,...,ccc) |
            VARS=aaa* [ RANGE=(start, end) | GENERIC ] |
            ARGS [ RANGE=(start, end) ] |
            MDO=aaa.bbb.ccc |
            MDO=aaa.bbb.ccc.* |
            MDO=aaa.bbb{*}.ccc [ RANGE=(start, end) ] |
            MDO=aaa }|
          DATA=data }

Example: A stem name MDO with no other &ASSIGN operands

&ASSIGN MDO=aaa

When no other operands are present, this assignment statement is interpreted as an MDO deletion operation. This is the only way to delete an MDO.

Example: A stem name MDO as the target of &ASSIGN

Using this form of assignment, the entire MDO with name aaa is created, or updated:

&ASSIGN MDO=aaa MAP=map

This has two functions:

If the MDO does not exist, then it is created and assigned to the map name provided, but contains no data.

If the MDO already exists, then it is assigned to the map name provided, but its data remains unchanged.

If the map name is unknown, then the MDO is unmapped, and its data can only be referenced in entirety by the MDO stem name.

&ASSIGN MDO=aaa [ MAP=map ] FROM MDO=xxx

Allows the MDO named aaa to be created or updated as a copy of the entire contents of the MDO named xxx. If the MAP operand is omitted, then the map name of the source MDO is assumed.

&ASSIGN MDO=aaa [ MAP=map ] FROM MDO=xxx.yyy.zzz

Allows the MDO named aaa to be created or updated as a copy of only a section of the source MDO named xxx.yyy.zzz. If the MAP operand is omitted, then the map name of the source MDO is assumed.

&ASSIGN MDO=aaa [ MAP=map ] DATA=xxx

Allows the MDO named aaa to be created or updated to contain only the data specified. If the MAP operand is omitted, then the MDO is unmapped, and its data can only be referenced in entirety by the MDO stem name.

&ASSIGN MDO=aaa [ MAP=map ] FROM VARS=xxx

Allows the MDO named aaa to be created or updated to contain only the data from the token xxx. If the MAP operand is omitted, then the MDO is unmapped, and its data can only be referenced in entirety by the MDO stem name.

&ASSIGN MDO=aaa [ MAP=map ]
        FROM { ARGS [ RANGE=(start,end) ] |
               VARS=xxx* [ RANGE=(start,end) ] |
               VARS=(aaa,bbb,...,ccc) }

Allows the MDO named aaa to be created or updated to contain the data from all the tokens in the range or list specified. If MAP=$NCL is specified, then special processing occurs to encapsulate all the source tokens in an MDO such that their individual names, attributes, and data contents are preserved. If the MAP operand is omitted, or if a map name other than $NCL is specified, then the source tokens are treated as a list of data items concatenated together to form the MDO contents. If the MAP operand is omitted, then the MDO is unmapped, and its data can only be referenced in entirety by the MDO stem name.

Example: A compound name MDO as the target of &ASSIGN

Using this form of assignment, the MDO with name aaa must exist or a null operation takes place. If the MDO exists, then the structure named aaa.bbb.ccc that is referenced is created, updated, or deleted. If no structure named aaa.bbb.ccc is known to Mapping Services, then no assignment takes place. If the structure is known, but the data source specified resolves to nulls, then a null assignment takes place but components are not deleted.

&ASSIGN MDO=aaa.bbb.ccc

This is used to delete the MDO structure named aaa.bbb.ccc. If it is a fixed length positional component, then it is set to nulls. If it is a variable length, keyed component, then it is deleted, and thus removed from the MDO completely.

&ASSIGN MDO=aaa.bbb.ccc FROM MDO=xxx

&ASSIGN MDO=aaa.bbb.ccc FROM MDO=xxx.yyy.zzz

These examples allow the MDO structure named aaa.bbb.ccc to be created or updated from the MDO structure nominated.

&ASSIGN MDO=aaa.bbb.ccc DATA=xxx

Allows the MDO structure named aaa.bbb.ccc to be created or updated to contain only the data specified.

&ASSIGN MDO=aaa.bbb.ccc FROM VARS=xxx

Allows the MDO structure named aaa.bbb.ccc to be created or updated to contain only the data from the token xxx.

&ASSIGN MDO=aaa.bbb.ccc
        FROM {ARGS [ RANGE=(start,end) ] |
              VARS=xxx* [ RANGE=(start,end) ] |
              VARS=(aaa,bbb,...,ccc) }

Allows the MDO structure named aaa.bbb.ccc to be created or updated to contain the data from all the tokens in the range or list specified. The source tokens are treated as a list of data items concatenated together to form the MDO structure contents.

Example: A stem name MDO as the source of &ASSIGN

In these assignments the MDO stem name specified following the FROM keyword is used to select the data for the assignment.

&ASSIGN MDO=aaa [ MAP=map ] FROM MDO=aaa

Allows the MDO named aaa to be created or updated as a copy of the entire contents of the MDO named xxx. If the MAP operand is omitted, then the map name of the source MDO is assumed.

&ASSIGN MDO=aaa.bbb.ccc FROM MDO=aaa

Allows the MDO structure named aaa.bbb.ccc to be created or updated from the MDO structure nominated.

&ASSIGN { VARS=aaa |
          VARS=(aaa,bbb,...,ccc) |
          VARS=aaa* [ RANGE=(start,end) ] |
          ARGS [ RANGE=(start,end) ] }
        FROM MDO=aaa

The variables that are the target of the assignment are assigned from consecutive 256-byte sections of the MDO name aaa.

Example: A compound name MDO as the source of &ASSIGN

In these assignments, the MDO compound name specified following the FROM keyword is used to select the data for the assignment.

&ASSIGN MDO=aaa [ MAP=map ] FROM MDO=aaa.bbb.ccc

Allows the MDO structure named aaa.bbb.ccc to be created or updated from the MDO structure nominated.

&ASSIGN MDO=aaa.bbb.ccc FROM MDO=aaa.bbb.ccc

Allows the MDO structure named aaa.bbb.ccc to be created or updated from the MDO structure nominated.

&ASSIGN { VARS=aaa |
          VARS=(aaa,bbb,...,ccc) |
          VARS=aaa* [ RANGE=(start,end) ] |
          ARGS [ RANGE=(start,end) ] }
        FROM MDO=aaa.bbb.ccc

The variables that are the target of the assignment are assigned from consecutive 256-byte sections of the MDO component aaa.bbb.ccc.

After using any verb that references an MDO, the MDO return code (&ZMDORC) and feedback (&ZMDOFDBK) system variables are set. Therefore you should check most verbs when using operations involving MDOs. The possible values of the return code and feedback system variables and their meanings are shown in the following table.

If &CONTROL MDOCHK is in effect, then an &ZMDORC value of 8 or more causes the NCL procedure to abend. If &CONTROL NOMDOCHK (the default) is in effect, you should check the values of &ZMDORC and &ZMDOFDBK after any verb involving MDOs.