Page History
9.195 SET_SESSION_VALUE
| Note |
|---|
| Note: Built-In Function Rules Usage Rules Usage Options |
Allows various Visual LANSA session values to be dynamically altered by an executing application.
Note that a change to a session value only exists until the session (i.e., the X_RUN command) completes execution.
Refer to the Standard X_RUN Parameters for further information.
Arguments
No | Type | Req/ Opt | Description | Min Len | Max Len | Min Dec | Max Dec |
|---|---|---|---|---|---|---|---|
1 | A | Req | Name of session value to be set or reset. Currently the following session values may be set or reset by this Built-In Function: USER: The current user - cannot be changed on IBM i. When you set USER, USEX (default user id when connecting to servers) also set. Refer to Technical Notes for Session Value USER=, GUSR= and USEX GUSR: The current group user - cannot be changed on IBM i. USER_AUDIT: The user to be used in user audit stamping. This must be explicitly set on the IBM i. Changing it in Visual LANSA will not update the IBM i in a Superserver application. PRTR: The current printer PPTH: The current fully qualified directory for printer files JOBPTY: Job queue priority DBMS_OPTIMIZE: Optimize heavy DBMS activity CONNECT_PARTITION: The default partition to be used by the CONNECT_SERVER Built-In Function. DPTH: Directory in which emulated IBM i data queues are to be created / accessed. EXPS: The action to take when importing object security records. HELP: Help system to use HLPF: Help file to use HMJB: Identifies that the current application is a Host Monitor job. 'Y' or 'N' . It is reserved for use by the LANSA development team only. LANG: Change currently executing language. This is designed to be used only with intimate knowledge of the internal working of LANSA so use is restricted to applications created by the LANSA development team. All tracing parameters e.g. ITRO. This can be useful for turning tracing on only whilst an issue is occurring so that the trace file size is kept to a minimum. PSRA=: Primary Server Route Authority. Setting PSRA=Y indicates that authority checks should be routed to the server. PSRR: Primary Server Route Repository. Setting PSRR=Y (the default) indicates that if the repository data cannot be retrieved locally, a request should be sent to the server to retrieve the data. UDEF: User-defined values with spaces up to 256 bytes. If the value contains spaces or you wish to use embedded quotes, it must be enclosed in double quotes, reducing the usable length to 254 bytes. Note: All embedded quotes must be single quotes; if you embed double quotes it will cause submitted jobs to fail. Windows printing extension parameters such as WPEN, WPPN, WPPS, WPPD, WPFD, WPDF, WPDS, WPFO and WPAS may be specified in this parameter. Any value specified in argument 2 should follow the same rules as defined for use of the windows printing extension parameter on the command line. (Refer to Windows Printing Extensions.) XCMD: Obscures values of specific parameters such as password. This parameter only becomes active for jobs submitted after it has been set. CIPH: Symmetric cipher to use when LANSA calls OPenSSL. | 1 | 50 | ||
2 | A | Req | Value to which the session value should be set or reset. Refer to the following technical notes for more details. | 1 | 256 |
Return Values
No return values.
...
The session value name (e.g., USER) that you specify is converted to uppercase before being tested for validity.
The session value can be specified with or without the equal sign. For example USER= and USER are both valid and identical.
The actual value that you specify may be converted to uppercase. Refer to the session value specific notes for details.
Any value specified must not be blank or null. In all other cases it is accepted. You are responsible for ensuring the integrity and correctness of any value that you pass to this Built-In Function. Invalid or inappropriate specification of values may result in application failure and/or unexpected results on the current platform or any associated server platforms.
Generally this Built-In Function is designed to be used very high in any invocation stack as an 'entry point' function that establishes various settings and that passes control into the actual application.
Once a session setting is altered, it remains in effect until the session (ie: x_run command) completes execution. An altered session value effects all subsequently invoked facilities.
When a session value is altered, functions, OAMs or communication sessions that are already active may ignore the change. As a very simple example of the concept of 'already active' consider:
...
define #chguser reffld(#user)
...
begin_loop
request #chguser
...
request #chguser
use set_session_value with_args('user=' #chguser)
display #user
...
display #user
end_loop
This function will not display the changed user. It will display #user (defaulted from *USER) at the time the function was originally invoked. The defaulting system variable *USER is static and is only initialized during function startup.
The following specific session value technical notes may refer to a 'designated use'. When a designated use has been specified you must not use this Built-In Function in any other context.
Invalid or inappropriate use of this Built-In Function may result in application failure and/or unexpected results on the current platform or any associated server platforms.
| Anchor | ||||
|---|---|---|---|---|
|
This session value is designated for use in a top level entry point function to allow you to design and implement your own 'sign on' function. After the user profile has been established the current user profile and group profile values may be altered.
It is not designed to support multiple changes of user scattered throughout an executing application. Do not attempt to design or implement applications using such an approach.
The value specified for USER= or GUSR= must conform to the rules defined in the x_run command. The correct value for no associated group user profile is *NONE.
The value specified is always converted to uppercase.
When you set USER, you also set USEX. The value you pass must be in a variable that maintains case. That value is first used to set USEX and then it is uppercased and USER is set.
USEX is the default User ID used when establishing connections to servers. For some servers the case is important and this allows the default to be changed in one place whilst also correctly controlling security access, if it is used. When the User ID is passed to X_RUN, it puts the exact case in the USEX parameter, the same as this Built-In Function now does.
...
Technical Notes for Session Value DBMS_OPTIMIZE=
Portability Considerations | When using this Built-In Function in RDMLX code on the IBM i, a COMMIT is issued so Commitment Control must be started. |
...
BEGIN_SYNC_nnnn | Specifies the beginning of a complex DBMS activity and switches on DBMS optimize mode. "Hard" commits are to be performed at every "nnnn" invocations of the "soft" synchronization point. | ||
SYNC_POINT | Specifies a "soft" synchronization point for a complex DBMS activity. A soft synchronization point is the equivalent of a "optimized" commitment control boundary. | ||
END_SYNC | Specifies the end of a complex DBMS activity and switches off DBMS optimize mode. | ||
The use of DBMS_OPTIMIZE is best illustrated by example.
Consider this simple RDML function:
begin_loop from(1) to(2000)
...
insert fields(......) to_file(testfile)
end_loop
In normal circumstances this function would be using auto-commit and would be performing a DBMS commit operation after every single insert.
...
If the function was changed to:
...
use set_session_value ( DBMS_OPTIMIZE BEGIN_SYNC_100 )
begin_loop from(1) to(2000)
...
insert fields(......) to_file(testfile)
...
use set_session_value ( DBMS_OPTIMIZE SYNC_POINT )
end_loop
use set_session_value ( DBMS_OPTIMIZE END_SYNC )
then it may run much faster than before. The DBMS_OPTIMIZE operations are enabling the underlying OAM (Object Access Module) to understand the transaction better, and thus to optimize it.
...
Another example might be this "batch" style function:
...
select fields(.....) from_file(customer) where(.......)
...
select fields(.....) from_file(orders) with_key(customer)
...
call *direct calculate
...
select fields(.....) from_file(items) with_key(orderno)
...
update fields(.....) in_file(items)
endselect
...
endselect
update fields(.....) in_file(orders)
...
endselect
endselect
The performance of this batch style program, could be enhanced by changing it to this:
use set_session_value ( DBMS_OPTIMIZE BEGIN_SYNC_20 )
select fields(.....) from_file(customer) where(.......)
select fields(.....) from_file(orders) with_key(customer)
...
call *direct calculate
...
select fields(.....) from_file(items) with_key(orderno)
...
update fields(.....) in_file(items)
endselect
...
endselect
update fields(.....) in_file(orders)
endselect
use set_session_value ( DBMS_OPTIMIZE SYNC_POINT ) endselect
use set_session_value ( DBMS_OPTIMIZE END_SYNC )
Some things that you must understand and rules that you must follow when using DBMS_OPTIMIZE are:
...