9 195 SET_SESSION

You are here:

9.195 SET_SESSION_VALUE

Note: Built-In Function 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

Type

Req/ Opt

Description

Min Len

Max Len

Min Dec

Max Dec

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.
Use this command to set the value on the fly. This should be done before you define and make the connection. (Refer to PSRA Notes in Using the X_RUN Command.)

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.
Use this command to set the value on the fly. This should be done before you define and make the connection. (Refer to the X_RUN parameters in Using the X_RUN Command.)

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.

Req

Value to which the session value should be set or reset. Refer to the following technical notes for more details.

256

Return Values

No return values.

General Technical Notes

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

use set_session_value with_args('user=' #chguser)

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.

Technical Notes for Session Value USER=, GUSR= and USEX

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 USER_AUDIT

This session value may be used to set the user that will be used in user audit stamping. It may be used where the current user does not give sufficient differentiations, such as in web jobs where all user jobs run under the default web user profiles.

This session value is designated for use in a top level entry point function.

It is not designed to support multiple changes of user audit scattered throughout an executing application. Do not attempt to design or implement applications using such an approach.

The value can be retrieved via system variable *USER_AUDIT.

No conversion to upper case is done on the value.

The audit user setting remains in effect until the session completes execution.

In Visual LANSA (on Windows, IBM i RDMLX and Linux), a session is until the x-run command completes.

On IBM i RDML, the session value remains in effect until the job ends or the LANSA partition is changed.

In LANSA web jobs, the session value should be set for each browser interaction, since jobs may timeout and different jobs may be used to process a request.

Batch jobs start a new session. Consequently, the audit user should be set for the batch job session.

If *LONG_USER_AUDIT is ON, then 256 characters of the session value will be used to set the value that will be used in user audit stamping. Otherwise 10 characters of the session value will be used to set this value.

Technical Notes for Session Value PRTR= and PPTH=

The PRTR= session value is designated for use in reporting functions that wish to alter the name of the logical printing device to which a report should be directed.

The PRTR= session value may also be used in reporting functions that wish to have all report output directed to a file. The special value *PATH should be specified and the PPTH= session value also used.

The value specified for PRTR= must conform to the rules defined in the x_run command.

The value specified for PPTH= must conform to the rules defined in the x_run command.

The value specified is not converted to uppercase. This may be an important consideration for Linux systems.

Technical Notes for Session Value JOBPTY=

This session value is designated for use in controlling the queuing priority of jobs submitted from this (ie: the currently executing) job. This value is defaulted to 5 when the x_run environment is invoked. This value should only be used with (and only has meaning in the context of) IBM i batch job queue and subsystem emulation.

The value specified for JOBPTY= must be an integer value in the range 0 -> 9. Jobs submitted with the lowest JOBPTY value are executed from an emulated job queue first. Jobs with equal JOBPTY values are executed in arrival order.

Please read the section in the Deploying LANSA Client and Server Applications guide that deals with IBM i Job Queue Emulation before attempting to use this facility.

Technical Notes for Session Value CONNECT_PARTITION=

This session value is designated for use in altering the partition identifier that the next CONNECT_SERVER Built-In Function invocation will attempt to connect to on the server system. The session value must be set prior to calling the builtin-in function CONNECT_SERVER and the value remains in effect until the X_RUN command ends or another CONNECT_PARTITION value is specified via this Built-In Function.

This session value specified in the value argument (argument 2) should be the 3 character identifier of a valid partition on the server system.

The value specified is always converted to uppercase.

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.

The DBMS_OPTIMIZE session value is designed to allow you to specify how a heavy or complex DBMS transaction can be optimized.

Judicious use of this option can significantly improve the performance of heavy or complex DBMS activity.

The value parameter, which must be in uppercase, may be set to:

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.

Most DBMS commit operations are usually quite slow. The commit can have a very significant performance impact on this type of application (ie: one doing the same thing 1000's rather than just 5 or 10 times).

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.

The primary reason for the performance improvement is the fact that the "soft" SYNC_POINT will only issue "hard" (ie: real) DBMS commit operations every 100 times that it is executed. This is why the BEGIN_SYNC_100 value is used. Thus the whole DBMS transaction begins to work faster.

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

update fields(.....) in_file(orders)

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

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:

BEGIN_SYNC_nnnn

Must be specified in uppercase characters.

Will abort if a BEGIN_SYNC_nnnn is already active within the current job. BEGIN_SYNC_nnnn operations cannot be nested.

Sets a synchronization "trigger" to the "nnnn" value specified. "nnnn" must be a valid integer in the range 1 to 1000.

Setting "nnnn" to 1 may negate any possible performance improvement because the SYNC_POINT will issue a commit operation every time it is executed.

Set a synchronization point "counter" to zero.

Switches on DBMS optimize mode.

Switches off all "auto-commitment" options. All DBMS tables will now be under full manual commitment control, regardless of how they are defined. Manual commits are issued when:

A SYNC_POINT reaches a trigger level.

An END_SYNC is executed.

A COMMIT operation is issued by an RDML function.

Must have an associated END_SYNC operation that is always executed to indicate the normal completion of a DBMS transaction.

May have an associated SYNC_POINT operation that specifies the point of a commitment control boundary. If no SYNC_POINT is specified then the END_SYNC operation acts as the single commitment control boundary.

Generally the higher the "nnnn" value the better the performance (within DBMS and journalling limits), however values above 500 would be unusual. Remember that the higher the value the more system resources being held/locked and the more data that will be lost if a rollback event occurs.

Should be used with SYNC_POINT and END_SYNC in a simple and well structured way to establish commitment boundaries and to optimize performance. Avoid scattering BEGIN_SYNC, SYNC_POINT and END_SYNC operations across multiple functions and down through complex invocations stacks. Try to keep all operations in a single function and keep the boundaries simple and well delimited.

Should not be used in complex and convoluted invocation stacks involving many different RDML functions and function calls. The primary reason for this is the very real possibility that a called function may well issue a COMMIT (or perform some action that causes a commit to be performed) thus negating any performance benefit that this option may bring.

Has no real meaning when used in LANSA SuperServer mode.

It is recommended that jobs concurrently accessing more than 15 tables should not use this facility.

SYNC_POINT

Must be specified in uppercase characters.

Will abort if DBMS optimize mode is not currently turned on.

Increments the synchronization point "counter"

If the synchronization "counter" is greater than or equal to the synchronization "trigger" value, then a DBMS commit operation is performed and the counter is reset to zero.

Will still issue a commit when used in LANSA SuperServer mode.

END_SYNC

Must be specified in uppercase characters.

Will abort if DBMS optimize mode is not currently turned on.

Unconditionally issues a DBMS commit.

Resets the synchronization counter to zero.

Resets the synchronization trigger to a default value.

Turns DBMS optimize mode off.

Will still issue a commit when used in LANSA SuperServer mode.