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 .NET native array.
The SET statement is used to initialize the contents of a .NET 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 .NET
native type.
General Formats




















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
- 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.
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.
Condition-name-1 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.
Each FALSE or TRUE phrase applies to the occurrences of condition-name-1
that precede that phrase and follow a previous FALSE or TRUE phrase, if any.

Identifier-1 must reference a level 01 or level 77 data item that is declared
in the Linkage Section.



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.
Identifier-1 must be declared in the Linkage Section, the Local-Storage
Section or the Working-Storage Section

Pointer-name-1, pointer-name-2 must each be an identifier that references
an elementary data item with USAGE IS POINTER.
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.
- 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.
- Integer-2 and integer-3 may be signed. Integer-2 must be positive.
- Identifier-7 must reference an elementary numeric integer.
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.

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

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
Event-pointer-1 must be defined as a data item with USAGE
EVENT-POINTER.
Event-pointer-1 and event-pointer-2 must be defined as data items with USAGE
EVENT-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.
Monitor-pointer-1 and monitor-pointer-2 must be defined as data items with
USAGE MONITOR-POINTER.
Mutex-pointer-1 must be defined as a data item with USAGE
MUTEX-POINTER.
Mutex-pointer-1 and mutex-pointer-2 must be defined as data items with USAGE
MUTEX-POINTER.
Semaphore-pointer-1 must be defined as a data item
with USAGE SEMAPHORE-POINTER.
Identifier-11 must reference an integer.
Semaphore-pointer-1 and semaphore-pointer-2 must be defined as data items
with USAGE SEMAPHORE-POINTER.
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.
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 to separate
the values into subarrays.
Identifier-15 and identifier-16 must have usage CONDITION-VALUE.
Condition-name-2 and condition-name-3 must be associated with conditional
variables.
If condition-name-2 is specified and the TRUE phrase is not specified, the
FALSE phrase must be specified in the VALUE clause of the Data Description
entry for condition-name-2.
Identifier-17 is the receiving item.
Identifier-18, 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-17 and identifier-18 are objects of the same class.
- The class of identifier-18 inherits directly or indirectly from the class
of identifier-17.
- Identifier-17 conforms to an interface and identifier-18 implements that
interface.
- There is an implicit conversion operator for an item with the class of identifier-18
to the class of identifier-17.
- Identifier-17 is alphanumeric or national.
General Rules
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.)
The literal in the VALUE clause associated with condition-name-1 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 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 is placed in the conditional
variable according to the rules for the VALUE clause. (See the topic The
VALUE Clause.)

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.
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.
- 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.
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 |
Table 1: SET Index Statement Valid Operand Combinations
1 = No conversion takes place.
- 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.
- 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.
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.

If identifer-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 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.
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.
Event-pointer-1 is set to reference the same event data item that event-pointer-2
references.
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.
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.
Monitor-pointer-1 is set to reference the same monitor data item that monitor-pointer-2
references.
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.
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.
Mutex-pointer-1 is set to reference the same mutex data item that mutex-pointer-2
references.
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.
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.
Semaphore-pointer-1 is set to reference the same semaphore data item that
semaphore-pointer-2 references.
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.
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 specfied values..
The contents of the data-item referenced by identifier-15 or condition-item-2
is set to the contents of the data item referencesby identifier-16 or condition-name-3
or to TRUE or FALSE.
If identifier-17 is 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-17. 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.