Rational Developer for System z
Enterprise COBOL for z/OS, Version 4.1, Language Reference


SET statement

The SET statement is used to perform one of the following operations:

Index-names are related to a given table through the INDEXED BY phrase of the OCCURS clause; they are not further defined in the program.

When the sending and receiving fields in a SET statement share part of their storage (that is, the operands overlap), the result of the execution of that SET statement is undefined.

Format 1: SET for basic table handling

When this form of the SET statement is executed, the current value of the receiving field is replaced by the value of the sending field (with conversion).

Read syntax diagramSkip visual syntax diagram
Format 1: SET statement for basic table handling

        .------------------.                         
        V                  |                         
>>-SET----+-index-name-1-+-+--TO--+-index-name-2-+-------------><
          '-identifier-1-'        +-identifier-2-+   
                                  '-integer-1----'   

index-name-1
Receiving field.

Must name an index that is specified in the INDEXED BY phrase of an OCCURS clause.

identifier-1
Receiving field.

Must name either an index data item or an elementary numeric integer item. A receiving field cannot be a windowed date field.

index-name-2
Sending field.

Must name an index that is specified in the INDEXED BY phrase of an OCCURS clause. The value of the index before the SET statement is executed must correspond to an occurrence number of its associated table.

identifier-2
Sending field.

Must name either an index data item or an elementary numeric integer item. A sending field cannot be a windowed date field.

integer-1
Sending field.

Must be a positive integer.

The following table shows valid combinations of sending and receiving fields in a format-1 SET statement.

Table 1. Sending and receiving fields for format-1 SET statement
Sending field

Index-name
receiving field

Index data item receiving field Integer data item receiving field
Index-name* Valid Valid** Valid
Index data item* Valid** Valid** Invalid
Integer data item Valid Invalid Invalid
Integer literal Valid Invalid Invalid
*An index-name refers to an index named in the INDEXED BY phrase of an OCCURS clause. An index data item is defined with the USAGE IS INDEX clause.

**No conversion takes place.

Receiving fields are acted upon in the left-to-right order in which they are specified. Any subscripting or indexing associated with identifier-1 is evaluated immediately before that receiving field is acted upon.

The value used for the sending field is the value at the beginning of SET statement execution.

The value of an index after execution of a SEARCH or PERFORM statement can be undefined; therefore, use a format-1 SET statement to reinitialize such indexes before you attempt other table-handling operations.

If index-name-2 is for a table that has a subordinate item that contains an OCCURS DEPENDING ON clause, then undefined values can be received into identifier-1.

For more information about complex OCCURS DEPENDING ON, see the Enterprise COBOL Programming Guide.

Format 2: SET for adjusting indexes

When this form of the SET statement is executed, the value of the receiving index is increased (UP BY) or decreased (DOWN BY) by a value that corresponds to the value in the sending field.

Read syntax diagramSkip visual syntax diagram
Format 2: SET statement for adjusting indexes

        .--------------.                                  
        V              |                                  
>>-SET----index-name-3-+--+-UP BY---+--+-identifier-3-+--------><
                          '-DOWN BY-'  '-integer-2----'   

The receiving field is an index specified by index-name-3. The index value both before and after the SET statement execution must correspond to an occurrence number in an associated table.

The sending field can be specified as identifier-3, which must be an elementary integer data item, or as integer-2, which must be a nonzero integer. identifier-3 cannot be a windowed date field.

When the format-2 SET statement is executed, the contents of the receiving field are increased (UP BY) or decreased (DOWN BY) by a value that corresponds to the number of occurrences represented by the value of identifier-3 or integer-2. Receiving fields are acted upon in the left-to-right order in which they are specified. The value of the incrementing or decrementing field at the beginning of SET statement execution is used for all receiving fields.

If index-name-3 is for a table that has a subordinate item that contains an OCCURS DEPENDING ON clause, and if the ODO object is changed before executing a format-2 SET Statement, then index-name-3 cannot contain a value that corresponds to an occurrence number of its associated table.

For more information about complex OCCURS DEPENDING ON, see the Enterprise COBOL Programming Guide.

Format 3: SET for external switches

When this form of the SET statement is executed, the status of each external switch associated with the specified mnemonic-name is turned ON or OFF.

Read syntax diagramSkip visual syntax diagram
Format 3: SET statement for external switches

        .----------------------------------.   
        | .-----------------.              |   
        V V                 |              |   
>>-SET------mnemonic-name-1-+--TO--+-ON--+-+-------------------><
                                   '-OFF-'     

mnemonic-name-1
Must be associated with an external switch, the status of which can be altered.

Format 4: SET for condition-names

When this form of the SET statement is executed, the value associated with a condition-name is placed in its conditional variable according to the rules of the VALUE clause.

Read syntax diagramSkip visual syntax diagram
Format 4: SET statement for condition-names

        .------------------.            
        V                  |            
>>-SET----condition-name-1-+--TO TRUE--------------------------><

condition-name-1
Must be associated with a conditional variable.

If more than one literal is specified in the VALUE clause of condition-name-1, its associated conditional variable is set equal to the first literal.

If multiple condition-names are specified, the results are the same as if a separate SET statement had been written for each condition-name in the same order in which they are specified in the SET statement.

Format 5: SET for USAGE IS POINTER data items

When this form of the SET statement is executed, the current value of the receiving field is replaced by the address value contained in the sending field.

Read syntax diagramSkip visual syntax diagram
Format 5: SET statement for data-pointers

        .------------------------------.   
        V                              |   
>>-SET----+-identifier-4-------------+-+------------------------>
          '-ADDRESS OF--identifier-5-'     

>--TO--+-identifier-6-------------+----------------------------><
       +-ADDRESS OF--identifier-7-+   
       +-NULL---------------------+   
       '-NULLS--------------------'   

identifier-4
Receiving fields.

Must be described as USAGE IS POINTER.

ADDRESS OF identifier-5
Receiving fields.

identifier-5 must be level-01 or level-77 items defined in the linkage section. The addresses of these items are set to the value of the operand specified in the TO phrase.

identifier-5 must not be reference-modified.

identifier-6
Sending field.

Must be described as USAGE IS POINTER.

ADDRESS OF identifier-7
Sending field. identifier-7 must name an item of any level except 66 or 88 in the linkage section, the working-storage section, or the local-storage section. ADDRESS OF identifier-7 contains the address of the identifier, and not the content of the identifier.
NULL, NULLS
Sending field.

Sets the receiving field to contain the value of an invalid address.

The following table shows valid combinations of sending and receiving fields in a format-5 SET statement.

Table 2. Sending and receiving fields for format-5 SET statement
Sending field USAGE IS POINTER receiving field

ADDRESS OF
receiving field

NULL/NULLS
receiving field

USAGE IS POINTER Valid Valid Invalid
ADDRESS OF Valid Valid Invalid
NULL/NULLS Valid Valid Invalid

Format 6: SET for procedure-pointer and function-pointer data items

When this format of the SET statement is executed, the current value of the receiving field is replaced by the address value specified by the sending field.

At run time, function-pointers and procedure-pointers can reference the address of the primary entry point of a COBOL program, an alternate entry point in a COBOL program, or an entry point in a non-COBOL program; or they can be NULL.

COBOL function-pointers are more easily used than procedure-pointers for interoperation with C functions.

Read syntax diagramSkip visual syntax diagram
Format 6: SET statement for procedure-pointers and function-pointers

        .-----------------------------------.   
        V                                   |   
>>-SET----+-procedure-pointer-data-item-1-+-+------------------->
          '-function-pointer-data-item-1--'     

>--TO--+-procedure-pointer-data-item-2-+-----------------------><
       +-function-pointer-data-item-2--+   
       +-ENTRY--+-identifier-8-+-------+   
       |        '-literal-1----'       |   
       +-NULL--------------------------+   
       +-NULLS-------------------------+   
       '-pointer-data-item-3-----------'   

procedure-pointer-data-item-1, procedure-pointer-data-item-2
Must be described as USAGE IS PROCEDURE-POINTER. procedure-pointer-data-item-1 is a receiving field; procedure-pointer-data-item-2 is a sending field.
function-pointer-data-item-1, function-pointer-data-item-2
Must be described as USAGE IS FUNCTION-POINTER. function-pointer-data-item-1 is a receiving field; function-pointer-data-item-2 is a sending field.
identifier-8
Must be defined as an alphabetic or alphanumeric item such that the value can be a program name. For more information, see PROGRAM-ID paragraph. For entry points in non-COBOL programs, identifier-8 can contain the characters @, #, and, $.
literal-1
Must be alphanumeric and must conform to the rules for formation of program-names. For details on formation rules, see the discussion of program-name under PROGRAM-ID paragraph.

identifier-8 or literal-1 must refer to one of the following types of entry points:

  • The primary entry point of a COBOL program as defined by the PROGRAM-ID paragraph. The PROGRAM-ID must reference the outermost program of a compilation unit; it must not reference a nested program.
  • An alternate entry point of a COBOL program as defined by a COBOL ENTRY statement.
  • An entry point in a non-COBOL program.

The program-name referenced by the SET ... TO ENTRY statement can be affected by the PGMNAME compiler option. For details, see the Enterprise COBOL Programming Guide.

NULL, NULLS
Sets the receiving field to contain the value of an invalid address.
pointer-data-item-3
Must be defined with USAGE POINTER. You must set pointer-data-item-3 in a non-COBOL program to point to a valid program entry point.

Example of COBOL/C interoperability

The following example demonstrates a COBOL CALL to a C function that returns a function-pointer to a service, followed by a COBOL CALL to the service:

IDENTIFICATION DIVISION.
PROGRAM-ID DEMO.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 FP USAGE FUNCTION-POINTER.
PROCEDURE DIVISION.
    CALL "c-function" RETURNING FP.
    CALL FP.

Format 7: SET for USAGE OBJECT REFERENCE data items

When this format of the SET statement is executed the value in the receiving item is replaced by the value in the sending item.

Read syntax diagramSkip visual syntax diagram
Format 7: SET statement for object references

>>-SET--object-reference-id-1--TO--+-object-reference-id-2-+---><
                                   +-NULL------------------+   
                                   '-SELF------------------'   

object-reference-id-1 and object-reference-id-2 must be defined as USAGE OBJECT REFERENCE. object-reference-id-1 is the receiving item and object-reference-id-2 is the sending item. If object-reference-id-1 is defined as an object reference of a certain class (defined as "USAGE OBJECT REFERENCE class-name"), object-reference-id-2 must be an object reference of the same class or a class derived from that class.

If the figurative constant NULL is specified, the receiving object-reference-id-1 is set to the NULL value.

If SELF is specified, the SET statement must appear in the procedure division of a method. object-reference-id-1 is set to reference the object upon which the currently executing method was invoked.


Terms of use | Feedback

This information center is powered by Eclipse technology. (http://www.eclipse.org)