AIFCHANGELOGON

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.

Operation Notes - 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.

AIFCHANGELOGON

Technical documentation

» Table of Contents

» Index

Syntax

Parameters

Operation Notes

Operation Notes - Current Restrictions