|
|
|
Changes the logon environment of a process.
Syntax
REC CA REC I32
AIFCHANGELOGON ( overall_status, logon_cmd, logon_desc, options,
REC I32
error_status, user_id );
Parameters
- overall_status
- record by reference (required)
Returns the overall status of the call. A zero indicates a successful
call. A negative value indicates an error in the overall call. A
positive value indicates a warning. Refer to appendix A for meanings of
status values.
Record type : status_type (Refer to appendix B.)
- logon_cmd
- character array by reference (optional)
logon_cmd must be declared as a packed array less than
or equal to 128 characters in length, and terminated by either a NULL
character (ASCII 0) or a carriage return (ASCII 13).
The format of logon_cmd is:
jobname, user/userpass.acct/acctpass, group/grouppass
The parameters userpass, acctpass, and
grouppass refer to the user, account, and group
passwords, respectively. The jobname and
group/grouppass portions of logon_cmd
are optional. The default is that no jobname is assigned. The default
for group is your home group if you are assigned one by the account
manager. This parameter is required if a home group is not assigned to
user.account.
If logon_cmd is passed, logon_desc can
be passed to return the target logon environment (including the home
group name) in the logon_desc_type format (refer to appendix B.)
You must pass either logon_cmd or
logon_desc or both.
Default: nil
- logon_desc
- record by reference (optional)
Required if logon_cmd is not passed. Passes the target
logon environment in a variable declared as a logon_desc_type.
If the group is not specified in the group_name field, the
target user.account's home group is returned in that field.
If logon_cmd is passed, logon_desc can
be passed to return the target logon environment (including the home
group name) in the logon_desc_type format. (Refer to appendix
B.)
You must pass either logon_cmd or
logon_desc or both.
Record type : logon_desc_type (Refer to appendix B.)
Default: nil
- options
- 32-bit signed integer by value (optional)
Directs AIFCHANGELOGON to skip some of the usual steps
performed in changing the logon environment. Following are the bit
definitions corresponding to the various options (set the bit to 1 to
invoke the option, all the other bits should be set to zero):
- Bit (0:1)
- Do not change the global job name (listed when you use the
SHOWJOB command). When this bit is set, only the process
local job name is updated. The global (jobwide or sessionwide) job
name remains unchanged. For example, the SHOWME command
displays the new job name of the local process, and the
SHOWJOB command displays the original job name (the same
one that would have been displayed before the
AIFCHANGELOGON).
- Bit (1:1)
- Do not change the global user and account name. When this bit is
set, only the process local user and account names are updated.
The global (jobwide or sessionwide) user and account names remain
unchanged. For example, the SHOWME command displays the
new user and account names of the local process, and the
SHOWJOB command displays the original logon user and
account names (the same one that would have been displayed before
the AIFCHANGELOGON).
- Bit (2:1)
- Do not change the global group name. When this bit is set, only
the process local group name is updated. The global (jobwide or
sessionwide) user and account name remains unchanged. For example,
the SHOWME command displays the new group name of the
local process and the SHOWJOB command displays the
original logon group name (the same one that would have been
displayed before the AIFCHANGELOGON).
- Bit (3:1)
- Do not change the allow mask.
- Bit (4:1)
- Keep the current temporary file directory. If this bit is not set
and the process has files open, AIFCHANGELOGON returns an
error.
- Bit (5:1)
- Keep current file equations. If this bit is not set, after an
AIFCHANGELOGON all of the file equations issued prior to
calling AIFCHANGELOGON are reset.
- Bit (6:1)
- Not used. Set to zero.
- Bit (7:1)
- Do not perform password validation.
- Bit (8:24)
- Reserved. Set to zero.
- Default: 0
- error_status
- record by reference (optional)
Returns a valid error number only if -2510 is returned in the
info field of overall_status, indicating that
the target logon environment passed in logon_cmd is not
syntactically valid. You can pass error_status to the
HPERRMSG intrinsic to return a syntax error message.
Refer to the MPE/iX Intrinsics Reference Manual (32650-90028) for
a description of HPERRMSG.
Record type : status_type (Refer to appendix B.)
Default: nil
- user_id
- 32-bit signed integer by value (optional)
The user ID assigned to a vendor at the time of purchase of the
Architected Interface Facility: Operating System product.
If it is not passed, the caller must have previously called
AIFACCESSON.
Default: 0
Operation Notes
The AIFCHANGELOGON AIF changes the logon environment of a process. It
supports the concept of a private logon environment, so the effects of
AIFCHANGELOGON are local to the process. This allows users to call
AIFCHANGELOGON from multiple processes executing within a given
job/session without having the various processes interfere with each other.
All child processes created after calling AIFCHANGELOGON inherit the
user name, account name, group name, job name, and capabilities of the parent.
Processes created prior to calling AIFCHANGELOGON are not affected.
Any program which has called AIFCHANGELOGON and has used the options
parameter to change the global logon environment must call
AIFCHANGELOGON again to restore the logon environment to its original
state before terminating. It the global logon environment is not restored, the
parent process might experience difficulties when accessing logon related
information and at the time of logoff.
Current Restrictions
The current implementation of this procedure is subject to the following
restrictions:
Session Variables:
There is only one variable table per job or session. Session variables, both
user-defined and system-defined, are stored by variable name in this table. If
multiple processes are executing in the same job/session, they all share the
same variables. If one process issues a programmatic SETVAR command
and another process issues a programmatic DELETEVAR or SETVAR
command for the same variable name, the SETVAR issued by the first
process is deleted or overwritten. The AIFCHANGELOGON AIF does not
create private (process-local) variables.
System Variables
Most system variables (HP@) are actually implemented as "active
functions", and they function correctly after a process executes an
AIFCHANGELOGON. They should reflect the changes for the process. A
few system variables are not implemented as active functions. These system
variables will experience the same behavior as user-defined variables; one
process can overwrite the changes made by another process in the same
job/session.
Below is a complete list of system variables implemented as active functions.
The variables marked with an "*" are read/write variables; the rest are read
only.
HPACCOUNT HPACCTCAP HPACCTCAPF *HPAUTOCONT HPCIDEPTH
HPCIERRMSG HPCMDNUM *HPCMDTRACE HPCONNMINS HPCONNSECS
HPCONSOLE HPCONTINUE HPCPUMSECS HPCPUNAME HPCPUSECS
HPDATE HPDATEF HPDAY HPDTCPORTID HPDUPLICATIVE
*HPERRDUMP *HPERRSTOLIST HPEXECJOBS HPGROUP HPGROUPCAP
HPGROUPCAPF HPHGROUP HPHOUR HPINBREAK HPINPRI
HPINTERACTIVE HPINTRODATE HPINTROTIME HPJOBCOUNT HPJOBLIMIT
HPJOBFENCE HPJOBNAME HPJOBNUM HPJOBTYPE HPLDEVIN
HPLDEVLIST HPMINUTE HPMONTH *HPMSGFENCE HPNCOPIES
HPOUTCLASS HPOUTFENCE HPQUIET *HPREDOSIZE HPSCHEDJOBS
HPSESCOUNT HPSESLIMIT HPSTDIN HPSTDLIST HPSUSAN
HPSUSPJOBS HPTIMEF *HPTIMEOUT *HPTYPEAHEAD HPUSER
HPUSERCAP HPUSERCAPF HPUSERCMDEPTH HPUSERSCOUNT HPUSERLIMIT
HPVERSION HPWAITJOBS HPYEAR
Temporary Files
The default for AIFCHANGELOGON is to create a new temporary directory on
release 4.0. For applications which had temporary files open this resulted
in errors being returned. In the past, the temporary directory was shared by
all processes in the job/session domain. Unless the application has a need to
create a new temporary directory, the recommendation is to set bit 4 in the
options parameter to keep the existing temporary directory. When bit 4 is not
set, the caller of AIFCHANGELOGON must close all temporary files. If temporary
files are not closed, and the option to keep the temporary directory is not
set, then AIFCHANGELOGON returns an error.
JOBINFO
If a process calls AIFCHANGELOGON, then information about the process
local logon environment (created my AIFCHANGELOGON) will not be
accessible via the JOBINFO intrinsic. The information returned by
JOBINFO always reflects the global (jobwide or sessionwide) logon
environment. If options to update global information are not selected, the
global information is going to be different from the process local information.
To avoid confusion and assure consistency use AIFJSGET/PUT
and AIFPROCGET/PUT.
DSCOPY
The DSCOPY command does not work correctly when invoked
programmatically from a process that has changed its logon environment using
AIFCHANGELOGON. The DSCOPY process inherits the original
logon characteristics instead of the process local environment. As a result,
the capabilities of the DSCOPY process may be different (more or
less).
DSCOPY capabilities problem
If the original capability is a superset of the new capability, DSCOPY
grants access to files that the process should not have access to. On the
other hand, if the original capability is less (not a superset) then the new
capabilities, DSCOPY denies access to files that the process should
have access to.
DSCOPY non-fully qualified problem
Suppose that you change logon to a new group or account, and you do a
DSCOPY as follows:
DSCOPY filename[.groupname[.acctname]]
If groupname is omitted, the file system qualifies the group
name with your original logon group name. Similarly, if
acctname is omitted, the file system qualifies the account
name with your original logon account name.
UDC environment
The AIFCHANGELOGON AIF does not execute the logon UDC as a regular
logoff and logon would. The UDC environment stays the same as the original
logon. The new user may not be able to use the original logon UDC anymore if
he or she does not have the right capabilities.
|
