SETLOG

Set the value of an environment variable

WTSupported in traditional Synergy on Windows
WNSupported in Synergy .NET on Windows
USupported on UNIX
VSupported on OpenVMS
xcall SETLOG(logical, [translation], status)

Arguments

logical

The case‑sensitive logical name of the environment variable to set. (a)

translation

(optional) The environment variable’s new value. (a)

status

The variable that will be loaded with one of the following values: (n)

1 = The routine was successful.

0 = The routine was not successful.

Discussion

The SETLOG subroutine sets the value of an environment variable or logical device in the current environment. (See Environment Variables for information about specific environment variables.) On UNIX and OpenVMS, a maximum of 254 characters can be set.

Note

Environment variable are a process‑wide operating system concept. Therefore, using SETLOG to set an environment variable in any .NET thread or AppDomain sets that environment variable in all threads and AppDomains.

Note

For Toolkit‑specific environment variables, the U_START routine must be called before SETLOG.

You can use the SETLOG subroutine to process DBLOPT options at runtime, which enables you to toggle runtime options on and off. (We recommend using %OPTION to set system options.)

If you don’t pass a translation value on Windows or OpenVMS, the SETLOG subroutine unsets (deletes) the specified environment variable. If you don’t pass a translation value on UNIX, the SETLOG subroutine clears the specified variable, but the variable remains defined.

SETLOG only affects the current environment and any child processes; when your program terminates, the environment variable is the same as when your program began. Typically, environment variables are only read by the runtime when it starts up; therefore, setting any of them with SETLOG only affects child processes. However, the following environment variables change in response to a call to SETLOG: DBLCASE (UNIX only), DBLOPT, ISAMC_REV (UNIX and Windows), SCSCOMPR (UNIX and Windows), TERM (UNIX only), and TNMBR.

On OpenVMS, because SETLOG requires the command line interpreter, if you are using xfServerPlus, you cannot XCALL this routine from within a shared image.

You can use the SETLOG subroutine to create search list logicals. To do this, separate the individual elements of the list with commas within the translation value. If you want to create an ordinary logical that contains a comma, you must enclose at least the comma in quotation marks, just as you would with the DEFINE command in DCL.

For example:

$ DEFINE DBLOPT 35","43

or

$DEFINE DBLOPT "35,43"

could be coded as

xcall setlog("DBLOPT", "35’,’43", status)

or

xcall setlog("DBLOPT", "’35,43’", status)

To include a quotation mark in the translation value, use two consecutive quotation marks in the value string:

xcall setlog("LOGNAME", ’He said ""Hello""’)

To include quotation marks of the same type as the string delimiting quotation marks, you must include four quotation marks. Each pair designates one quotation mark in the string that builds into the code. For example, the above setting could be coded

xcall setlog("LOGNAME", "He said """"HELLO""""")

Examples

The example below sets system option #25.

xcall getlog("DBLOPT", optstr, optlen)
if (optlen)
  if (.not. %instr(1, optstr(1, optlen), "25"))
    begin
.ifdef OS_VMS
      optstr = '"' + %atrim(optstr) + ',25"'
.else
      optstr = %atrim(optstr) + ",25"
.endc
      optlen = %trim(optstr)
      xcall setlog("DBLOPT", optstr(1, optlen), sts)
    end

The following example unsets the environment variable specified by lognam.

xcall setlog(lognam,, status)