GUI ScreenIO for Windows

 ScreenIO.com


SetEnvironmentVariable

This API sets the value of an environmental variable. 

Environmental values may be set but the setting will not survive the current job.  Each job (program) receives a copy of the environment when it is started, and may manipulate this environment at will, but any such changes will disappear at the end of the job.  However, this can be a useful way to set arguments for a sub-process invoked by the winexec API or for setting flags and switches or passing small bits of data to subroutines without the use of arguments in the linkage section. 

Be aware that the size of the environment is fixed at job start time, so if you plan to make extensive use of this you must set the environment size before you start your job.

Why use this?

Some compilers have the utilities or APIs to set environmental variable values. However, these utilities are not transportable to another compiler, nor are they client/server aware, meaning you can not return values from the client unless you uses this API.

Client/Server issues

This API will set the variable in the client.  You can optionally set variables in the server if you can preceded the API call with the following Set statement:

     SET WIN32API-EXECUTE-API-ON-SERVER TO TRUE

Files

Files available to copy to your system:

Usage

     COPY WIN32API.
     COPY ENVIRON.


     
* ------------------------: Call the API.
*

     MOVE LENGTH OF ENV-VARIABLE-VALUE  TO ENV-VALUE-LENGTH
     MOVE LOW-VALUES TO ENV-VARIABLE-VALUE
*                         : This is the environment variable name
*                         : we want to retrieve
     MOVE "TEMP" TO ENV-VARIABLE-NAME
* ------------------------: Call the API to get the value
*
     SET API-SETENVIRONMENTVARIABLE TO TRUE.
     CALL 'GSWINAPI' USING WIN32API-PARMS
                           ENV-VALUE-LENGTH
                           ENV-VARIABLE-NAME
                           ENV-VARIABLE-VALUE
                           WIN32API-D
                           WIN32API-E
                           WIN32API-F.

Parameters specific to this function

ENV-VALUE-LENGTH

This field must be set to the length of the field which holds the value of the environmental variable.  The ENVIRON copybook supplies a generic field of 1024 bytes, but since environmental values can be up to 32k bytes, you may have to substitute a different field for ENV-VARIABLE-VALUE.  In any event, this field must be set to the length of your field. 

ENV-VARIABLE-NAME 

This field should contain the name of the environmental variable you want to set.  It is case insensitive.

ENV-VARIABLE-VALUE

This field (or any alternative field you wish to use) will hold the value of the environmental variable.

WIN32API-PARMS - Used in all GSWINAPI calls

This argument is standard for all CALLs to GSWINAPI. It is used to select the desired API or function, and to return the status of the operation.

WIN32API-RC

Used to return the status of a call to GSWINAPI.  A value of zero is a failure, any other value indicates success. 

Recommended usage is to test the 88-level value WIN32API to see if it worked, then to use the text error message to see why it failed.

* ------------------------: If function failed,
*                         :   display the error in a message box.
*
     IF WIN32API-FAILED
       MOVE WIN32API-ERROR-TEXT TO panel-MESSAGE-TEXT
       SET panel-MESSAGE-IN-MESSAGEBOX TO TRUE.

WIN32API-ERROR-CODE

Error code that was returned by Windows.  This is not generally useful unless you have the Windows Platform SDK documentation available to you.

WIN32API-ERROR-TEXT

Plain-text error message that describes why the operation failed.

WIN32API-A through WIN32API-F

The number of these present varies depending on how many arguments are used by the desired function.  These are not used, but must be present because this CALL requires seven arguments.


2000-2006 Norcom, all rights reserved 

TOC

Send feedback to Norcom