The SET Statement
The SET statement is used to alter the status of external switches.
The SET statement is used to alter the value of conditional variables.
The SET statement is used to assign the address of a data item to a pointer data item. It is also used to adjust the contents
of a pointer data item.
The SET statement establishes reference points for table handling operations by setting indices associated with table elements.
The SET statement is used to assign the address of a program or an entry-point in a program to a procedure-pointer data item.
The SET statement is used to assign the address of a pointer to a program-pointer data item.
The SET statement is used to assign object references.
The SET statement is used to alter the value of a synchronization data item.
The SET statement is used to assign the address of a synchronization data item to another synchronization data item.
The SET statement is used to alter the size of a native array.
The SET statement is used to initialize the contents of a native array and to set the array size based on those contents.
The SET statement is used to alter the value of a boolean data item with usage CONDITION-VALUE.
The SET statement is used to alter the value of a data item with a native type.
The SET statement is used to set the dynamic length of a receiving item to the same length as the sending item.
General Formats for Format 1 (Switch-setting)
General Formats for Format 2 (Condition-setting)
General Formats for Format 3 (Data-pointer-assignment)
General Formats for Format 5 (Data-pointer-arithmetic)
General Formats for Format 6 (Index-assignment)
General Formats for Format 7 (Index-arithmetic)
General Formats for Format 8 (Procedure-pointer-assignment)
General Formats for Format 9 (Object-reference-assignment)
General Formats for Format 10 (Value-of-Event-pointer)
General Formats for Format 11 (Address-of-Event-pointer)
General Formats for Format 12 (Value-of-Monitor-pointer)
General Formats for Format 13 (Address-of-Monitor-pointer)
General Formats for Format 14 (Value-of-Mutex-pointer)
General Formats for Format 15 (Address-of-Mutex-pointer)
General Formats for Format 16 (Value-of-Semaphore-pointer)
General Formats for Format 17 (Address-of-Semaphore-pointer)
General Formats for Format 18 (Size-of-array)
General Formats for Format 19 (Content-of-array)
General Formats for Format 20 (CONDITION-VALUE setting)
General Formats for Format 21 (data-setting)
General Formats for Format 22 (dynamic length)
Directives
- In addition to Compiler directives which provide flagging and modify the reserved word list, the following directives may
impact either the syntax or the semantics described in this section.
- STICKY-LINKAGE - determines whether addresses of data items placed in pointer data items by the SET statement are retained between invocations of a subprogram.
Syntax Rules for All Formats
- The figurative constant NULL or NULLS or the data item referenced by pointer-name-2 or procedure-pointer-name-2 represents
the sending area. ADDRESS OF identifier-2, ENTRY identifier-8, ENTRY literal-1 or the value held in the sending area, represents
the sending value.
The data item referenced by pointer-name-1, pointer-name-3 or procedure-pointer-name-1 or the COBOL system area implied by ADDRESS OF identifier-1 represents the receiving area.
Identifier-3, integer-1 or LENGTH OF identifier-4 represents the increment value.
Syntax Rules for Format 1
- Mnemonic-name-1 must be associated with an external switch, the status of which can be altered.
See the topic
The Special-Names Paragraph for details of which external switches can be referenced in the SET statement.
Syntax Rules for Format 2
- Condition-name-1 and condition-name-2 must be associated with a conditional variable.
- If the FALSE phrase is specified, the FALSE phrase must be specified in the VALUE clause of the Data Description entry for
condition-name-1 or condition-name-2.
- Each FALSE or TRUE phrase applies to the occurrences of condition-name-1 or condition-name-2 that precede that phrase and
follow a previous FALSE or TRUE phrase, if any.
Syntax Rules for Format 3
- Identifier-1 must reference a level 01 or level 77 data item that is declared in the Linkage Section.
Identifier-1 must be declared in the Linkage Section, the Local-Storage Section or the Working-Storage Section
- Identifier-1 must not be a dynamic-length group item or a dynamic-length elementary item.
- Identifier-2 must reference a data item with a level of 77 or between 01 and 49 inclusive.
Identifier-2 must be declared in the Linkage Section.
- Pointer-name-1, pointer-name-2 must each be an identifier that references an elementary data item with USAGE IS POINTER.
Syntax Rules for Format 5
- Pointer-name-3 must be an identifier that references an elementary data item with USAGE IS POINTER.
- Identifier-3 must be an elementary numeric integer.
- Integer-1 may be signed.
Syntax Rules for Format 6
- Identifier-5 and identifier-6 must each reference an index data item or an elementary item described as an integer. If both are specified, they must not both reference an elementary item.
Syntax Rules for Formats 6 and 7
- Integer-2 and integer-3 may be signed. Integer-2 must be positive.
Syntax Rules for Format 7
- Identifier-7 must reference an elementary numeric integer.
Syntax Rules for Format 8
-
Procedure-pointer-name-1 and procedure-pointer-name-2 must each be an identifier that references an elementary data item
with USAGE IS PROCEDURE-POINTER.
- Identifier-8 must be defined as an alphanumeric data item such that its value can be a COBOL or a non-COBOL program name.
- Literal-1 must be a nonnumeric literal.
Syntax Rules for Format 9
- Identifier-9 must be any item of class object that is permitted as a receiving item.
- Identifier-10 must be a class-name or an object reference; the predefined object reference SUPER must not be specified.
- If the data item referenced by identifier-9 is a universal object reference, the only predefined object references that may
be specified for identifier-10 are SELF and NULL.
- If the data item referenced by identifier-9 is described with an interface-name that identifies the interface int-1, the data
item referenced by identifier-10 must be one of the following:
- An object reference described with an interface-name that identifies int-1 or an interface inheriting from int-1.
- An object reference described with a class-name, subject to the following rules:
- If described with a FACTORY phrase, the factory object of the specified class must implement int-1
- If described without a FACTORY phrase, the instance objects of the specified class must implement int-1.
- An object reference described with an ACTIVE-CLASS phrase, subject to the following rules:
- If described with a FACTORY phrase, the factory object of the class containing the data item referenced by identifier-10 must implement int-1.
- If described without a FACTORY phrase, the instance objects of the class containing the data item referenced by identifier-10 must implement int-1.
- A class-name whose factory object implements int-1.
- The predefined object reference SELF, subject to the following rules:
- If the SET statement is contained in a method within the factory definition of the class, that factory definition must be described with an IMPLEMENTS clause that references int-1.
- If the SET statement is contained in a method within the instance definition of the class, that instance definition must be described with an IMPLEMENTS clause that references int-1.
- The predefined object reference NULL
- If the data item referenced by identifier-9 is described with a class-name, the data item referenced by identifier-10 must
be one of the following:
- An object reference described with a class-name, subject to the following rules:
- If the data item referenced by identifier-9 is described with an ONLY phrase, the data item referenced by identifier-10 must be described with the ONLY phrase, and the class-name specified in the description of the data item referenced by identifier-10 must be the same as the class-name specified in the description of the data item referenced by identifier-9
- If the data item referenced by identifier-9 is described without an ONLY phrase, the class-name specified in the description of the data item referenced by identifier-10 must reference the same class or a subclass of the class specified in the description of the data item referenced by identifier-9
- The presence or absence of the FACTORY phrase must be the same as in the description of the data item referenced by identifier-9
- An object reference described with an ACTIVE-CLASS phrase, subject to the following rules:
- The data item referenced by identifier-9 must not be described with the ONLY phrase
- The class containing the data item referenced by identifier-10 must be the same class or a subclass of the class specified in the description of the data item referenced by identifier-9
- The presence or absence of the FACTORY phrase must be the same as in the description of the data item referenced by identifier-9
- The predefined object reference SELF, subject to the following rules:
- The data item referenced by identifier-9 must not be described with the ONLY phrase
- The class of the object containing the SET statement must be the same class or a subclass of the class specified in the description of the data item referenced by identifier-9
- If the data item referenced by identifier-9 is described without a FACTORY phrase, the object containing the SET statement must be an instance object
- If the data item referenced by identifier-9 is described with a FACTORY phrase, the object containing the SET statement must be a factory object
- A class-name, provided the data item referenced by identifier-9 is described with the FACTORY phrase, and class-name references the same class or a subclass of the class specified in the description of the data item referenced by identifier-9
- The predefined object reference NULL
- An object reference described with a class-name, subject to the following rules:
- If the data item referenced by identifier-9 is described with an ACTIVE-CLASS phrase, the data item referenced by identifier-10
must be one of the following:
- An object reference described with the ACTIVE-CLASS phrase, where the presence or absence of the FACTORY phrase is the same as in the data item referenced by identifier-9
- The predefined object reference SELF, subject to the following rules:
- If the data item referenced by identifier-9 is described without a FACTORY phrase, the object containing the SET statement must be an instance object
- If the data item referenced by identifier-9 is described with a FACTORY phrase, the object containing the SET statement must be a factory object
- The predefined object reference NULL
- If identifier-9 is of type String, then identifier-10 may be of any type.
Syntax Rules for Format 10 (Value of Event-pointer)
-
Event-pointer-1 must be defined as a data item with USAGE EVENT-POINTER.
Syntax Rules for Format 11 (Address of Event-pointer)
- Event-pointer-1 and event-pointer-2 must be defined as data items with USAGE EVENT-POINTER.
Syntax Rules for Format 12 (Value of Monitor-pointer)
-
Monitor-pointer-1 must be defined as a data item with USAGE MONITOR-POINTER.
- If the NOT phrase is specified, then the CONVERTING phrase must not be specified.
Syntax Rules for Format 13 (Address of Monitor-pointer)
- Monitor-pointer-1 and monitor-pointer-2 must be defined as data items with USAGE MONITOR-POINTER.
Syntax Rules for Format 14 (Value of Mutex-pointer)
-
Mutex-pointer-1 must be defined as a data item with USAGE MUTEX-POINTER.
Syntax Rules for Format 15 (Address of Mutex-pointer)
- Mutex-pointer-1 and mutex-pointer-2 must be defined as data items with USAGE MUTEX-POINTER.
Syntax Rules for Format 16 (Value of Semaphore-pointer)
-
Semaphore-pointer-1 must be defined as a data item with USAGE SEMAPHORE-POINTER.
- Identifier-11 must reference an integer.
Syntax Rules for Format 17 (Address of Semaphore-pointer)
- Semaphore-pointer-1 and semaphore-pointer-2 must be defined as data items with USAGE SEMAPHORE-POINTER.
Syntax Rules for Format 18 (Size-of-Array)
- Identifier-12 must be described with a format 3 OCCURS clause.
- Identifier-13 must describe an integer.
- The number of operands after the TO phrase must not exceed the number of dimensions specified for identifier-12.
Syntax Rules for Format 19 (Content-of-Array)
- Identifier-14 must be described with a format 3 OCCURS clause as either a one-dimensional array or a rectangular array.
- Literal-2 must be a valid literal for a VALUE clause describing the subject of the entry.
- Parentheses may be used within the repetitions of literal-2 or identifier-15 to separate the values into subarrays.
Syntax Rules for Format 20 (CONDITION-VALUE setting)
- Identifier-16 and identifier-17 must have usage CONDITION-VALUE.
- Condition-name-3 must be associated with a conditional variable.
Syntax Rules for Format 21 (.NET-data-setting)
- Identifier-18 and Identifier-19 are the receiving items.
- Identifier-20, literal-3 or arithmetic-expression-1 is the sending item.
- The SET statement is legal if any of the following are true:
- Both the sending item and the receiving item are numeric
- Identifier-18, identifier-19 and identifier-20 are objects of the same class.
- The class of identifier-20 inherits directly or indirectly from the class of identifier-18 and identifier-19.
- Identifier-18 and identifier-19 conform are of an interface type and identifier-20 implements that interface.
- There is an implicit conversion operator for an item with the class of identifier-20 to the class of identifier-18 and identifier-19.
- Identifier-18 and identifier-19 are alphanumeric or national.
Syntax Rules for Format 22 (Dynamic Length)
- identifier-21 must be a dynamic-length elementary item.
- identifier-22 must be an elementary numeric integer item.
- integer-6 must be an integer greater than or equal to zero.
General Rules for Format 1
- The status of each external switch associated with the specified mnemonic-name-1 is modified such that the truth value resulting
from evaluation of a condition-name associated with that switch reflects an on status if the ON phrase is specified, or an
off status if the OFF phrase is specified. (See the topic
Switch-Status Condition in the chapter
Procedure Division.)
General Rules for Format 2
- The literal in the VALUE clause associated with condition-name-1 or condition-name-2 is placed in the conditional variable
according to the rules of the VALUE clause (see the section
The VALUE Clause.) If more than one literal is specified in the VALUE clause, the conditional variable is set to the value of the first literal
that appears in the VALUE clause.
- If multiple condition-names are specified, the results are the same as if a separate SET statement had been written for each
condition-name-1 or condition-name-2 in the same order as specified in the SET statement.
- If the FALSE phrase is specified, the literal in the FALSE phrase of the VALUE clause associated with condition-name-1 or
condition-name-2 is placed in the conditional variable according to the rules for the VALUE clause. (See the topic
The VALUE Clause.)
General Rules for Format 3
- The sending value represents the address of a data item. If pointer-name-2 is specified, the sending value is the value contained
with the data item referenced by pointer-name-2. If ADDRESS OF identifier-2 is specified, the sending value represents the
address of identifier-2.
- If pointer-name-1 is specified, the sending value is moved to the data name referenced by pointer-name-1.
- If ADDRESS OF identifier-1 is specified, the sending value is moved to a COBOL system area and the runtime element subsequently
operates such that the area of storage referenced by identifier-1 is located at the address represented by the sending value.
Whether or not the link is retained between invocations of a subprogram is dependent on the STICKY-LINKAGE Compiler directive.
General Rules for Format 5
- Before execution of the SET statement, the value of the data item referenced by pointer-name-3 must represent the address
of a data item within a logical record, the original address. After execution of the SET statement, the value of the data
item referenced by pointer-name-3 represents the new address. If the original address and the new address do not both lie
within the same logical record, (or, for environments in which address space is segmented, within the same segment) then the
results of using the value of the data item referenced by pointer-name-3 are undefined.
- If the UP clause is specified, the new address is formed by adding the number of bytes given by the increment value to the
original address.
- If the DOWN clause is specified, the new address is formed by subtracting the number of bytes given by the increment value
from the original address.
General Rules for Format 5
- The following steps are repeated for each recurrence of index-name-1 or identifier-5. Each time, the value of index-name-2
or identifier-6 is used as it was at the beginning of the execution of the statement. Any subscripting or indexing associated
with identifier-5 is evaluated immediately before the value of that data item is changed.
- If index-name-1 is specified, index-name-1 is set to a value causing it to refer to the table element that corresponds in occurrence number to the table element referenced by index-name-2, identifier-6, or integer-2. If identifier-6 references an index data item, or if index-name-2 is related to the same table as index-name-1, no conversion takes place.
- If identifier-5 references an index data item, it can be set equal to either the contents of index-name-2 or identifier-6 where identifier-6 also references an index item; no conversion takes place in either case.
- If identifier-5 does not reference an index data item, it can be set only to an occurrence number that corresponds to the value of index-name-2. Neither identifier-6 nor integer-2 can be used in this case.
- The following table represents the validity of various operand combinations in the SET statement. The general rule reference
indicates the applicable general rule.
Table 1. SET Index Statement Valid Operand Combinations Sending Item Receiving Item Integer Data Item Index-Name Index Data Item Integer Literal No/11c Valid/11a No/11b Integer Data Item No/11c Valid/11a No/11b Index-Name Valid/11c Valid/11a Valid/11b1 Index Data Item No/11c Valid/11a1 Valid/11b1 1 = No conversion takes place.
General Rules for Formats 6 and 7
- Index-names are associated with a given table by being specified in the INDEXED BY phrase of the OCCURS clause for that table.
- If index-name-1 is specified, the value of the index after the execution of the SET statement must correspond to an occurrence
number of an element in the table associated with index-name-1. The value of the index associated with an index-name after
the execution of a PERFORM or SEARCH statement may be set to an occurrence number that is outside the range of its associated
table. (See the topic
The PERFORM Statement and the topic
The SEARCH Statement.)
If index-name-2 is specified, the value of the index before the execution of the SET statement must correspond to an occurrence number of an element in the table associated with index-name-1.
If index-name-3 is specified, the value of the index both before and after the execution of the SET statement must correspond to an occurrence number of an element in the table associated with index-name-3.
General Rules for Format 7
- The contents of index-name-3 are incremented (UP BY) or decremented (DOWN BY) by a value that corresponds to the number of occurrences represented by the value of integer-3 or the data item referenced by identifier-7; thereafter, the process is repeated for each recurrence of index-name-3. For each repetition, the value of the data item referenced by identifier-7 is used as it was at the beginning of the execution of the statement.
General Rules for Format 8
- The sending value represents the address of the start of a procedure within a COBOL or non-COBOL program.
- The sending value is moved to the data item referenced by procedure-pointer-name-1.
- If procedure-pointer-name-2 is specified, the sending value is the value contained within the data item referenced by procedure-pointer-name-2.
- Literal-1 or the content of the data item referenced by identifier-8 is the name of the referenced procedure. If the referenced
procedure is a COBOL procedure, the name of the referenced procedure must contain the program-name contained in the Program-ID
paragraph of the referenced program or the entry-name contained in the ENTRY statement of the referenced procedure.
If the program being called is not a COBOL program, the rules for the formation of the program or procedure name are given in your COBOL system documentation on interfacing.
If the referenced procedure has been previously made available and remains available at the time of execution of the SET statement, then the sending value represents the address of the referenced procedure.
If the referenced procedure is not available at the time of execution of the SET statement, then the sending value represents the address of a COBOL system error procedure.
General Rules for Format 9
- If identifier-10 is an object reference, a reference to the object identified by identifier-10 is placed into each data item
referenced by identifier-9 in the order specified.
- If identifier-10 is a class-name, a reference to the factory object of the class identified by identifier-10 is placed into
each data item referenced by identifier-9 in the order specified.
- If identifier-9 is of type String, and identifier-10 is of any type, and no implicit conversion exists between the type of
identifier-10 and String, then the ToString method is applied to identifier-10 to convert it to a string, and the result is
placed in identifier-9.
General Rules for Formats 10 and 11
- If more than one event-pointer-1 is specified, the results are the same as if a separate SET statement had been written for
each event-pointer-1 in the same order as specified in the SET statement.
General Rules for Format 10 (Value of Event-pointer)
- The execution of the SET statement sets the value of the event referenced by event-pointer-1 to TRUE or FALSE.
Note: When an event is set to FALSE, the execution of any thread which executes a WAIT statement which references that event suspends until the event is set to TRUE in another thread.
General Rules for Format 11 (Address of Event-pointer)
- Event-pointer-1 is set to reference the same event data item that event-pointer-2 references.
General Rules for Formats 12 and 13
- If more than one monitor-pointer-1 is specified, the results are the same as if a separate SET statement had been written
for each monitor-pointer-1 in the same order as specified in the SET statement.
General Rules for Format 12 (Value of Monitor-pointer)
- If the NOT phrase is not specified, the value of the monitor referenced by monitor-pointer-1 is set to one of BROWSING, READING,
or WRITING, thus establishing the corresponding form of lock. This specific lock type for this specific monitor must be eventually
released by a SET statement either with a matching NOT phrase or a matching CONVERTING FROM phrase.
For example, the lock established by
SET mon-1 TO READING
can be cleared by
SET mon-1 TO NOT READING
- The CONVERTING phrase is used to change the current type of lock established on a monitor. The lock type specified in the
FROM phrase must be currently established by that thread and upon successful execution of the statement, that lock will have
been changed, in one atomic operation, to the lock type specified in the TO phrase.
- Nested locks can be obtained by the execution of successive SET monitor statements with no intervening SET statement that
releases the lock. Once a READING lock is established, no BROWSING or WRITING lock is allowed to nest within that thread.
Once a BROWSING lock or a WRITING lock is established, any other level of lock is allowed to nest within that thread.
General Rules for Format 13 (Address of Monitor-pointer)
- Monitor-pointer-1 is set to reference the same monitor data item that monitor-pointer-2 references.
General Rules for Formats 14 and 15
- If more than one mutex-pointer-1 is specified, the results are the same as if a separate SET statement had been written for
each mutex-pointer-1 in the same order as specified in the SET statement.
General Rules for Format 14 (Value of Mutex-pointer)
- The execution of the SET statement sets the value of the mutex referenced by mutex-pointer-1 to ON or OFF.
- When a mutex is set to ON, the execution of any thread that attempts to set that mutex to ON suspends until the mutex is set
to OFF in the thread that set it ON.
General Rules for Format 15 (Address of Mutex-pointer)
- Mutex-pointer-1 is set to reference the same mutex data item that mutex-pointer-2 references.
General Rules for Formats 16 and 17
- If more than one semaphore-pointer-1 is specified, the results are the same as if a separate SET statement had been written
for each semaphore-pointer-1 in the same order as specified in the SET statement.
General Rules for Format 16 (Value of Semaphore-pointer)
- The contents of the semaphore data item referenced by semaphore-pointer-1 are incremented (UP BY) or decremented (DOWN BY)
by a value that corresponds to the value of integer-4 or the data item referenced by identifier-11; thereafter, the process
is repeated for each recurrence of semaphore-pointer-1. For each repetition, the value of the data item referenced by identifier-11
is used as it was at the beginning of the execution of the statement.
- If a semaphore is set DOWN BY n and the semaphore is less than n, the thread is suspended until another thread raises the
semaphore to above n.
General Rules for Format 17 (Address of Semaphore-pointer)
- Semaphore-pointer-1 is set to reference the same semaphore data item that semaphore-pointer-2 references.
General Rules for Format 18 (Size-of-Array)
- The SET statement sets the size of the .NET array described by identifier-12 to the contents of the data item referenced by
identifier-13 or the value of integer-5.
General Rules for Format 19 (Content-of-Array)
- The SET statement creates an a .NET array of the size required to contain the values specified by the repetitions of literal-2
and initializes the array to the specified values.
General Rules for Format 20 (CONDITION-VALUE setting)
- The data-item referenced by identifier-16 is set to the value of the data item referenced by identifier-17 or to condition-name-3,
a conditional expression or to TRUE or FALSE.
General Rules for Format 21 (.NET-data-setting)
- If identifier-18 and identifier-19 are alphanumeric or national, the ToString method is automatically invoked on the sending
item and the resulting string moved to the data item referenced by identifier-18 and identifier-19. Note that the ToString
method exists for any class since it is implemented in System.Object.
- The sending item is moved to the receiving item.
General Rules for Format 22 (Dynamic Length)
- The length of identifier-21 is set to zero if identifier-22 is less than zero.
- If the current length of identifier-21 is greater than the value of identifier-22 or integer-6, then the length of identifier-21 is set to the specified value and the item truncated on the right.
- If the current length of identifier-21 is shorter than identifier-22 or integer-6, then the length of identifier-21 is set to the specified value, no padding occurs, and the newly available character positions on the right are not initialized.