9 218 SET_SESSION_VALUE

9.218 SET_SESSION_VALUE

Þ Note: Built-In Function Rules.

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.

More information can be found on some session values by searching in the LANSA Global guide. In particular, refer to the Standard X_RUN Parameters.

For use with

Arguments

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 for the web jobs, the session value should be set for each browser interaction, since jobs may time-out 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=

• 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:

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 

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.