Document revision date: 19 July 1999

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

Create dialog box, read user name and password, and call the identification and authentication routines.

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

None.

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

Get the system password.

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

Perform standard OpenVMS user name prompting and parsing.

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

None.

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

None.

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

None.

12.5 LOGINOUT Callback Routines

• 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

	privacy and legal statement
4493PRO_028.HTML