![[OpenVMS documentation]](../../images/openvms_doc_banner_top.gif)
|
![[Site home]](../../images/buttons/bn_site_home_off.gif)
![[Send comments]](../../images/buttons/bn_comments_off.gif)
![[Help with this site]](../../images/buttons/bn_site_help_off.gif)
![[How to order documentation]](../../images/buttons/bn_order_docs_off.gif)
![[OpenVMS site]](../../images/buttons/bn_openvms_off.gif)
![[Compaq site]](../../images/buttons/bn_compaq_off.gif)
|
|
Updated:
11 December 1998
|
OpenVMS Utility Routines Manual
LGI$ICR_DECWINIT
The LGI$ICR_DECWINIT callout routine enables site-specific
initialization functions for logins from the DECwindows session manager.
Format
LGI$ICR_DECWINIT arg_vector ,context
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Returns status indicating whether and how to proceed with the login.
Arguments
arg_vector
| OpenVMS usage: |
vector |
| type: |
vector_longword_unsigned |
| access: |
modify |
| mechanism: |
by reference |
Vector containing site-specified callbacks and login information.
context
| OpenVMS usage: |
context |
| type: |
longword (unsigned) |
| access: |
modify |
| mechanism: |
by reference |
Pointer to site's local context.
Description
LOGINOUT invokes the LGI$ICR_DECWINIT callout routine at the start of a
DECwindows session login. This callout routine does not support a
return status of LGI$_SKIPRELATED. Returning LGI$_SKIPRELATED for this
callout causes unpredictable results. Use the LGI$ICR_DECWINIT callout
routine only to prepare other callout routines for a DECwindows login.
After issuing the LGI$ICR_DECWINIT callout, LOGINOUT performs the
following tasks:
- Creates the DECwindows login dialog box and reads the user name and
password entered by the user
- Calls the LGI$ICR_IDENTIFY callout
- Obtains the user authorization file (UAF) record
If the UAF
record specifies two passwords, the DECwindows login dialog box is
amended to prompt for the second password, and the listed tasks are
repeated.
- Issues the LGI$ICR_AUTHENTICATE callout
- If the LGI$ICR_AUTHENTICATE callout routine did not return
LGI$_SKIPRELATED, validates the passwords against the UAF record
The LGI$ICR_IDENTIFY and LGI$ICR_AUTHENTICATE callouts may create
additional DECwindows dialog boxes to communicate with the user, but
the initial dialog box must be created by LOGINOUT.
Typical Condition Values
|
SS$_NORMAL
|
Access permitted; continue policy checks.
|
|
LGI$_SKIPRELATED
|
Not supported. Returning this status will cause unpredictable behavior.
|
|
Other
|
Disallow the login.
|
Associated OpenVMS Policy Function
1
Create dialog box, read user name and password, and call the
identification and authentication routines.
LGI$ICR_FINISH
The LGI$ICR_FINISH callout routine permits the site program to take
final local action before exiting from LOGINOUT.
Format
LGI$ICR_FINISH arg_vector ,context ,user_cond_value
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Returns status indicating whether and how to proceed with the login.
Arguments
arg_vector
| OpenVMS usage: |
vector |
| type: |
vector_longword_unsigned |
| access: |
modify |
| mechanism: |
by reference |
Vector containing callbacks and login information.
context
| OpenVMS usage: |
context |
| type: |
longword (unsigned) |
| access: |
modify |
| mechanism: |
by reference |
Pointer to site's local context.
user_cond_value
| OpenVMS usage: |
cond_value |
| type: |
longword_unsigned |
| access: |
read only |
| mechanism: |
by value |
SS$_NORMAL for successful login; otherwise, reason for failure.
Description
The site program calls this routine immediately before exiting to take
any final local actions relative to the login process. There is no
OpenVMS login security policy associated with LGI$ICR_FINISH.
LGI$ICR_FINISH does not affect login completions because the login is
audited before the routine is invoked. The routine has no effect on
error recovery when a login fails, and it cannot cause a successful
login to fail.
Typical site action may include the following:
- Override job quotas
- Stack CLI command procedures by examining and modifying the
logicals PROC1 through PROC9
Caution
For DECwindows session manager logins, be careful modifying the command
procedure stack to avoid adversely affecting the command file that
invokes the session manager.
|
- Other postlogin processing
Typical Condition Values
|
LGI$_SKIPRELATED
|
Access permitted; omit calls to the LGI$ICR_FINISH callout routine in
subsequent images.
|
Associated OpenVMS Policy Function
LGI$ICR_IACT_START
The LGI$ICR_IACT_START callout routine may perform initialization
functions for logins from interactive character-cell terminals.
Format
LGI$ICR_IACT_START arg_vector ,context
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Returns status indicating whether and how to proceed with the login.
Arguments
arg_vector
| OpenVMS usage: |
vector |
| type: |
vector_longword_unsigned |
| access: |
modify |
| mechanism: |
by reference |
Vector containing callbacks and login information.
context
| OpenVMS usage: |
context |
| type: |
longword (unsigned) |
| access: |
modify |
| mechanism: |
by reference |
Pointer to site's local context.
Description
This routine makes the first contact for all interactive logins from
other than DECwindows terminals after opening the input and output
files but before any other dialogue with the user.
At this point, the site should be preparing to augment or replace the
OpenVMS system password routine. The callback routine
LGI$ICB_GET_SYSPWD provides access to the system password routine.
However, because LGI$ICB_GET_SYSPWD returns only on success, the site
design should consider what action to take in case LGI$ICB_GET_SYSPWD
does not return control to LGI$ICR_IACT_START.
The LGI$ICR_IACT_START routine can use the LGI$ICB_GET_INPUT callback
routine to:
- Get input from the user
- Use an OpenVMS RMS record access block (RAB) to establish
appropriate terminal mode settings
Typical Condition Values
|
SS$_NORMAL
|
Access permitted; continue OpenVMS system password routine.
|
|
LGI$_SKIPRELATED
|
Access permitted; omit calls to the LGI$ICR_IACT_START callout routine
in subsequent images and calls to the associated OpenVMS policy
function.
|
|
Other
|
Exit quietly to preserve the illusion of an inactive line.
|
Associated OpenVMS Policy Function
LGI$ICR_IDENTIFY
The LGI$ICR_IDENTIFY callout routine identifies the user from the user
name input.
Format
LGI$ICR_IDENTIFY arg_vector ,context
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Returns status indicating whether and how to proceed with the login.
Arguments
arg_vector
| OpenVMS usage: |
vector |
| type: |
vector_longword_unsigned |
| access: |
modify |
| mechanism: |
by reference |
Vector containing callbacks and useful login information.
context
| OpenVMS usage: |
context |
| type: |
longword (unsigned) |
| access: |
modify |
| mechanism: |
by reference |
Pointer to site's local context.
Description
The LGI$ICR_IDENTIFY callout routine is invoked for all types of login
procedures. If the site uses the standard OpenVMS DECwindows dialogue,
the identification routine may be called more than once for accounts
with two passwords.
If you plan to replace the standard OpenVMS identification processing,
consider the following:
- For logins from character-cell terminals, obtain the user name
using one of the following:
- A dialogue with the user. The site can access OpenVMS user name
processing to obtain the standard prompt or a specialized prompt by
invoking the LGI$ICB_USERPROMPT callback routine. Alternatively, the
site may invoke the LGI$ICB_GET_INPUT callback routine to communicate
with the user.
- Site-specific equipment, for example, a card reader or some other
authentication device.
- Autologins. The site may do the identification portion of the
standard OpenVMS autologin by invoking the LGI$ICB_AUTOLOGIN callback
routine.
- For logins from the DECwindows Session Manager, LOGINOUT invokes
the callout module's LGI$ICR_IDENTIFY callout routine after obtaining
the user name and putting it in LGI$A_ICR_USERNAME. The
LGI$ICR_IDENTIFY callout routine can provide any additional checking of
the user name that may be required.
- For batch jobs, network jobs, logged-in DECterm sessions, and
subprocesses, the site may use the LGI$ICR_IDENTIFY routine to verify
information without a user dialogue.
Calls to LGI$ICR_IDENTIFY are always followed by validation of the
presence of the user name in the system authorization file, unless the
routine is invoked for a subprocess.
Typical Condition Values
|
SS$_NORMAL
|
Access permitted; continue policy checks.
|
|
LGI$_SKIPRELATED
|
Access permitted; omit calls to the LGI$ICR_IDENTIFY callout routine in
subsequent images and calls to the associated OpenVMS policy function.
|
|
Other
|
Disallow the login.
|
Associated OpenVMS Policy Function
1
Perform standard OpenVMS user name prompting and parsing.
LGI$ICR_INIT
The LGI$ICR_INIT callout routine may perform any required
initialization functions.
Format
LGI$ICR_INIT arg_vector ,context
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Returns status indicating whether and how to proceed with the login.
Arguments
arg_vector
| OpenVMS usage: |
vector |
| type: |
vector_longword_unsigned |
| access: |
modify |
| mechanism: |
by reference |
Vector containing callbacks and login information.
context
| OpenVMS usage: |
context |
| type: |
longword (unsigned) |
| access: |
modify |
| mechanism: |
by reference |
Pointer to site's local context.
Description
This routine is called for all job types before opening input and
output files. If desired, the callout routine may initialize the
context argument, which LOGINOUT subsequently passes
to each callout routine with the address of local storage specific to
the callout image.
Typical Condition Values
|
SS$_NORMAL
|
Access permitted; continue policy checks.
|
|
LGI$_SKIPRELATED
|
Access permitted; omit calls to the LGI$ICR_INIT callout routine in
subsequent images.
|
|
Other
|
Disallow the login.
|
Associated OpenVMS Policy Function
LGI$ICR_JOBSTEP
The LGI$ICR_JOBSTEP callout routine signals the start of each batch job
step.
Format
LGI$ICR_JOBSTEP input_file_name ,context ,write_fao
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Not applicable.
Arguments
input_file_name
| OpenVMS usage: |
descriptor |
| type: |
character string |
| access: |
read |
| mechanism: |
by reference |
The name of the input file.
context
| OpenVMS usage: |
context |
| type: |
longword (unsigned) |
| access: |
modify |
| mechanism: |
by reference |
Pointer to site's local context.
write_fao (fao_string[,arg1[,arg2][,...]]])
| OpenVMS usage: |
routine |
| type: |
procedure |
| access: |
read |
| mechanism: |
by reference |
Address of a routine that may be called to format and display output.
The routine has fao_string as its first argument,
followed by a variable number of arguments. (See the $FAO system
directive in the OpenVMS System Services Reference Manual for more information.)
Description
The LGI$ICR_JOBSTEP routine alerts the site of each job step in a batch
job. The routine is invoked as LOGINOUT processes each job step. For
the first job step, the LGI$ICR_JOBSTEP callout routine is invoked
immediately following the LGI$ICR_IDENTIFY callout routine. For all
other job steps, it is the only callout routine that is invoked.
The routine is provided with the input file name, but the input file is
not open when the routine is called. For the first job step, the
LGI$ICR_INIT callout routine may provide the batch job step routine
with context. For other job steps, the context
argument is a null.
For all job steps except the first, the output file is open, and the
routine specified by the write_fao argument is
available.
There is no OpenVMS policy associated with LGI$ICR_JOBSTEP.
Typical Condition Values
|
LGI$_SKIPRELATED or any error value
|
Access permitted; omit calls to the LGI$ICR_JOBSTEP callout routine in
subsequent images.
|
Associated OpenVMS Policy Function
LGI$ICR_LOGOUT
The LGI$ICR_LOGOUT callout routine permits the site callout images to
respond to the DCL command LOGOUT.
Note
This routine is not called if the calling process is deleted with
STOP/PROCESS ($DELPRC). If the calling terminal is disconnected when
logout occurs, this routine must not produce output.
|
Format
LGI$ICR_LOGOUT username ,processname ,creprc_flags ,write_fao
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Returns logout status from the site program.
Arguments
username
| OpenVMS usage: |
descriptor |
| type: |
character string |
| access: |
read |
| mechanism: |
by reference |
User name.
processname
| OpenVMS usage: |
descriptor |
| type: |
character string |
| access: |
read |
| mechanism: |
by reference |
Process name.
creprc_flags
| OpenVMS usage: |
mask_longword |
| type: |
longword_unsigned |
| access: |
read |
| mechanism: |
by reference |
Process creation status flags.
write_fao (fao_string[,arg1[,arg2][,...]]])
| OpenVMS usage: |
routine |
| type: |
procedure |
| access: |
read |
| mechanism: |
by reference |
Procedure for writing data. The value is 0 if output is not permitted.
Address of a routine that may be called to format and display output.
The routine has fao_string as its first argument,
followed by a variable number of arguments. (See the $FAO system
directive in the OpenVMS System Services Reference Manual for more information.)
Description
The LGI$ICR_LOGOUT routine is invoked after auditing is completed and
immediately before LOGOUT prints the logout message. This routine
cannot prevent the logout from finishing, but it may prevent display of
the standard logout message.
Typical Condition Values
|
LGI$_SKIPRELATED or any error value
|
Access permitted; omit calls to the LGI$ICR_LOGOUT callout routine in
subsequent images.
|
Associated OpenVMS Policy Function
12.5 LOGINOUT Callback Routines
LOGINOUT callout routines use callback routines to interact with the
user or to access other LOGINOUT services. This section describes the
individual callback routines. The description of each routine includes
the following:
- The format of the call command
- The anticipated information returned by the called routine
- The arguments presented to the called routine
- A general description of the routine
- Condition values that indicate the return status of the routine,
success or failure
![[OpenVMS documentation]](../../images/openvms_doc_banner_bottom.gif)