SET Statement

Format 1

SET {result} ... TO value

Format 2

SET {result} ... {UP  } BY value
                 {DOWN}

Format 3

SET { {cond-name} ... TO {TRUE } } ...
                         {FALSE}

Format 4

SET { {switch-name} ... TO {ON } } ...
                           {OFF}

Format 5

SET FILE-PREFIX TO file-prefix

Format 6

SET {CONFIGURATION} { env-name TO env-value } ...
    {ENVIRONMENT  }

Format 7

SET pointer TO { ADDRESS OF data-item }
               { NULL                 }

Format 8

SET result-item TO SIZE OF data-item

Format 9

SET ADDRESS OF linkage-item TO { pointer             }
                               { ADDRESS OF data-item}
                               { NULL                }

Format 10

SET {INPUT       } WINDOW TO window-1
    {INPUT-OUTPUT}
    {I-O         }
    {OUTPUT      }

Format 11

SET {handle-1} ... TO HANDLE OF {screen-1       }
                                {CONTROL ID id-1}

Format 12

SET THREAD {thread-id} PRIORITY TO priority

Format 13

SET EXCEPTION {VALUE } { exc-value TO {ITEM-HELP           } } ...
              {VALUES}                {HELP-CURSOR         }
                                      {CUT-SELECTION       }
                                      {COPY-SELECTION      }
                                      {PASTE-SELECTION     }
                                      {DELETE-SELECTION    }
                                      {UNDO                }
                                      {SELECT-ALL-SELECTION}

Syntax Rules

result is a numeric data item or index name.
value is a numeric literal, a numeric data item, or an index name.
file-prefix is a nonnumeric literal or alphanumeric data item.
cond-name is any condition-name (level 88 item). If the FALSE option is used, then cond-name must have a WHEN SET TO FALSE phrase in its definition.
switch-name must be a mnemonic name associated with an external switch in the SPECIAL-NAMES section of the Environment Division.
env-name is a nonnumeric literal or data item.
env-value is a USAGE DISPLAY numeric or nonnumeric literal or data item. If numeric, it must be an integer.
CONFIGURATION and ENVIRONMENT are equivalent.
pointer must be a data item with USAGE POINTER.
result-item must be a numeric data item.
linkage-item must be declared in the Linkage section.
window-1 is a USAGE HANDLE or PIC X(10) data item that refers to a floating window or the main application window.
handle-1 is a USAGE HANDLE data item. When the control is an ActiveX, COM, or .NET control, handle-1 must be a typed handle that matches the control; i.e., handle-1 must be declared with the USAGE HANDLE OF control-type syntax. See USAGE Clause for more information.
screen-1 must refer to an elementary Screen Section item that describes a graphical control.
id-1 and priority are numeric literals or data items.
thread-id is a USAGE HANDLE or HANDLE OF THREAD data item.
exc-value is an integer literal or data item.

Format 1 General Rules

Each result is set to value. This assignment is done such that the numeric values of result and value will be the same.

Format 2 General Rules

value is either added to (UP BY) or subtracted from (DOWN BY) each result item. No size error checking is done.

Format 3 General Rules

When the TRUE phrase is used, the literal in the VALUE clause for cond-name is moved to its associated condition-variable. If the VALUE clause contains more than one literal, the first one is used.
When the FALSE phrase is used, the literal defined in the WHEN SET TO FALSE phrase of cond-name is moved to its associated condition-variable.

Format 4 General Rules

Format 4 of the SET statement alters the on/off status of external switches. These switches are initially off unless otherwise specified when the program is run.

Format 5 General Rules

The FILE-PREFIX is a special register maintained by ACUCOBOL-GT to aid in translating COBOL ASSIGN names to actual file names on the host computer. See File Name Interpretation, in the ACUCOBOL-GT User's Guide for a complete description of its function.
A Format 5 SET statement is equivalent to this Format 6 SET statement:
```
SET ENVIRONMENT "FILE-PREFIX" TO file-prefix
```

Format 6 General Rules

ACUCOBOL-GT maintains a set of configuration variables that can affect various aspects of the runtime system. These variables can be initially set in the ACUCOBOL-GT runtime configuration file described in Compiler and Runtime in the ACUCOBOL-GT User's Guide. The Format 6 SET statement can be used to modify these values at runtime.
env-name is the name of the configuration variable to set. In it, lower-case characters are treated as upper case, and underscores are treated as hyphens. The first space character delimits the name. env-name may specify either the literal name of the variable or a data-item whose value is the name of the variable. If you specify the actual name of the variable, such as COMPRESS-FILES, then you must enclose the name in quotes. env-value is the value to set the variable to. If it is a numeric data item, then it is treated as if it were redefined as an alphanumeric data item.
If env-name does not match the name of one of the runtime system's configuration variables, then env-name and env-value are placed in the runtime system's local environment. These entries are used to do file name translations. See File Name Interpretation in the ACUCOBOL-GT User's Guide for more information. .
The complete list of environment variables used by ACUCOBOL-GT can be found in ACUCOBOL-GT Appendices, Appendix H.

Format 7 General Rules

If the ADDRESS OF option is used, then the address of data-item is stored in pointer. If the NULL option is used, then pointer is set to point to no data item.

Note that the -Zm compiler option Causes the compiler to generate code that tells the runtime the size of a data item specified in the SET statement. See Miscellaneous Options for details on the -Zm option.

Format 8 General Rules

The number of standard character positions occupied by data-item is stored in result-item.

Format 9 General Rules

If pointer is specified, then the address of the linkage-item is set to pointer. If the ADDRESS OF option is used, then the address of the linkage-item is set to the address of data-item. If the NULL option is used, then the address of the linkage-item is set to point to no data item.
The level of linkage-item must be either 01 or 77.
If the linkage-item is not listed in the PROCEDURE DIVISION USING phrase and is referenced before the SET ADDRESS OF statement, then the runtime will abort with the message, Use of a LINKAGE data item not passed by the caller.

Format 9 is helpful if you want to allocate a sizable piece of memory for temporary use, access this memory via a COBOL table, and then free the memory. For example:

Use the library routine M$ALLOC to allocate the memory.
SET the address of a Linkage section table to the pointer returned from M$ALLOC.
Complete the desired procedures.
Free the memory with M$FREE.

The code sample that follows shows how Format 9 works.

identification division.

program-id.     sample-program.

data division.

working-storage section.

linkage section.

* item-a and ptr-a are passed in by the calling 
* program

    01 item-a    pic x(10).

* ptr-a is set to the address of item-a 
* in the calling program

    01 ptr-a   usage pointer.

* item-b is used in the SET Statement. 
* It is not passed in by the calling program. 

    01 item-b   pic x(10).

procedure division using item-a, ptr-a.
main-logic.

* Assuming item-a has a value of "ABCDEFGHIJ", 
* and ptr-a points to item-a,
* the following will display "ABCDEFGHIJ" three 
* times

    display item-a.

* "ABCDEFGHIJ" is displayed

    set address of item-b to ptr-a.
    display item-b.

* "ABCDEFGHIJ" is displayed

    set address of item-b to address of item-a.
    display item-b.

* "ABCDEFGHIJ" is displayed

    stop run.

Format 10 General Rules

Format 10 of the SET verb makes window-1 the current, or current and active window. The current window is the window to which DISPLAY statements refer. The active window is the window that is highlighted and the one to which user input is directed. window-1 must be a handle to a valid floating window. If window-1 does not refer to a valid floating window, the SET statement has no effect.
INPUT, INPUT-OUTPUT, and I-O are synonymous. They cause window-1 to become both the current and active window.
OUTPUT causes window-1 to become the current window.

Format 11 General Rules

A Format 11 SET statement retrieves the handle to the control described by screen-1 or Id-1 and stores it in handle-1. Id-1 must specify a value greater than zero. If a matching control is found, handle-1 is set to the handle of that control. If no matching control is found, handle-1 is set to NULL. If more than one control has a matching ID, then handle-1 is arbitrarily set to one of those controls. Note that the handle can be used in any statement that can use control handles. One reason you might want this handle is if you need to pass a control to a subprogram. You cannot pass Screen Section names to subprograms, but you can pass the handle instead.

Format 12 General Rules

A Format 12 SET statement sets the execution priority of a thread. Execution switches between threads at various points in the program. Each opportunity to change the active thread is called a switch point. The execution priority determines which thread gets control at each switch point.
The execution priority is an integer. The higher the priority, the more often that thread gets control at a switch point. By default, threads start with a priority value of 100. Threads receive control in proportion to their priority. Thus, a thread with a priority of 50 gains control half as often as a thread with a priority of 100. Of course, if a thread is paused for any reason (waiting for input, for example), then it does not gain control.
If thread-id is specified, then the priority for the thread identified by thread-id is set to priority. Otherwise, the current thread's priority is set to priority. If thread-id does not correspond to an existing thread, then the SET statement has no effect.
The minimum priority for a thread is 1. The maximum is 32767.

Format 13 General Rules

A Format 13 SET statement associates the exception value specified in exc-value with an automated action that the runtime can perform. Any keystroke, menu item, or control that produces the exc-value exception value will automatically cause the associated action to be performed (you do not have to code the action; it happens automatically). If the runtime handles the exception in this way, then the exception is not passed on to the COBOL program.

The ITEM-HELP action produces context-sensitive help for the control with the current input focus. The HELP-CURSOR action places the mouse into help mode. For a description of the ITEM-HELP and HELP-CURSOR actions, see The Help Processor in ACUCOBOL-GT User Interface Programming.

The remaining actions take effect if the current control is an entry field (otherwise, they have no effect). These actions cause the entry field to do the following:

CUT-SELECTION	Cuts the current selection to the clipboard
COPY-SELECTION	Copies the current selection to the clipboard
PASTE-SELECTION	Pastes the clipboard into the entry field at the current location (replaces any existing selection)
DELETE-SELECTION	Deletes the current selection
UNDO	Undoes the last change
SELECT-ALL-SELECTION	Selects all the text in the entry field. In a multi-line entry field, this includes the text in all lines.

The cut, copy, paste, delete, and undo effects are accomplished automatically via the ACTION property of entry fields. Usually, you will want to assign these exception values to various menu items and toolbar push buttons. When you are setting up a push button to correspond to one of these actions, you should ensure that you make the push button a SELF-ACT button (otherwise the act of pushing the button makes the button the current control, not the entry field).